From 46f40ae58946010d101e9a0be9f4e52ffeab38f9 Mon Sep 17 00:00:00 2001 From: Steffen Sauder Date: Fri, 17 Apr 2026 09:02:51 +0200 Subject: [PATCH] fix: reposition ConnectOptions JSDoc and merge MergeInner JSDoc blocks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ConnectOptions JSDoc block was orphaned — it sat above Verbosity's own JSDoc, so tooling attached Verbosity's block to Verbosity correctly while the ConnectOptions block floated loose. Move it directly above the ConnectOptions interface. Also merge the two adjacent JSDoc blocks on MergeInner into a single block so the description is not silently dropped by tooling that only reads the closest block. Addresses FINDING-06 from code review. Co-Authored-By: Claude Opus 4.7 --- src/type-system.ts | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/src/type-system.ts b/src/type-system.ts index 2cb9024..ed3be1d 100644 --- a/src/type-system.ts +++ b/src/type-system.ts @@ -104,6 +104,18 @@ export interface Navigable> { [$links]: L; } +/** + * Controls how much detail the library includes in error messages. + * + * - `'verbose'` (default): includes full URL, resource names, schema paths — best for client-side debugging. + * - `'safe'`: omits URLs and internal identifiers — use in BFF/API gateway contexts. + * + * Single source of truth for the verbosity union — every internal helper that + * branches on verbosity (`api-client`, `error-handling`, `uri-templates`) + * imports this alias rather than restating the literal union. + */ +export type Verbosity = 'verbose' | 'safe'; + /** * Configuration options for connecting to a hypermedia API. * @@ -121,18 +133,6 @@ export interface Navigable> { * }); * ``` */ -/** - * Controls how much detail the library includes in error messages. - * - * - `'verbose'` (default): includes full URL, resource names, schema paths — best for client-side debugging. - * - `'safe'`: omits URLs and internal identifiers — use in BFF/API gateway contexts. - * - * Single source of truth for the verbosity union — every internal helper that - * branches on verbosity (`api-client`, `error-handling`, `uri-templates`) - * imports this alias rather than restating the literal union. - */ -export type Verbosity = 'verbose' | 'safe'; - export interface ConnectOptions< ApiDef extends ApiDefinition, RootResource extends ResourceNameFrom = ResourceNameFrom @@ -314,8 +314,7 @@ type Merge = MergeInner>; * Non-Navigable overlays (intermediate path segments) add `& unknown` * which TypeScript simplifies away. * - Primitives: Simple intersection S & O - */ -/** + * * @internal Exported solely for type-level test access in `test/unit/type-system.test.ts`. * Not intended for public consumption — consume `Resource` instead. */