From 6176e2c3adc249412e7b4cb239ec213a4a1bf1ce Mon Sep 17 00:00:00 2001
From: Steffen Sauder <steffen.sauder@gmail.com>
Date: Fri, 17 Apr 2026 09:03:33 +0200
Subject: [PATCH] fix: rewrite defineLinks JSDoc example to not crash at
 runtime

The public @example showed `'posts[]': { to: 'posts' }` as a validated
link path. After housekeeping #10 hardened validateResourceDefinition
to reject bare terminal `[]` segments, copying this example verbatim
throws `Array segment 'posts[]' cannot be terminal.` at runtime.

Rewrite the example to be self-contained: show UserSchema with a `posts`
field of shape `Type.Array(Type.Object({ href: Type.String() }))` and
use the `'posts[].href'` link path, matching the canonical idiom used
in examples/petshop-api.ts.

Addresses FINDING-01 from code review.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 src/link-definition.ts | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/src/link-definition.ts b/src/link-definition.ts
index 49df768..2b0dfb6 100644
--- a/src/link-definition.ts
+++ b/src/link-definition.ts
@@ -126,22 +126,36 @@ export type ApiDefinition<ValidNames extends string = string> = Record<string, R
  *
  * @example
  * ```typescript
- * // Define API with validated resource references
- * const api = defineLinks(['users', 'posts'], {
+ * import { Type } from '@sinclair/typebox';
+ * import { defineLinks } from 'typesafe-hypermedia';
+ *
+ * const PostSchema = Type.Object({
+ *   id: Type.String(),
+ *   title: Type.String(),
+ * });
+ *
+ * const UserSchema = Type.Object({
+ *   id: Type.String(),
+ *   name: Type.String(),
+ *   // `posts` is an array of link objects, each with an `href` URL
+ *   posts: Type.Array(Type.Object({ href: Type.String() })),
+ * });
+ *
+ * export const api = defineLinks(['users', 'posts'], {
  *   users: {
  *     schema: UserSchema,
  *     links: {
- *       'posts[]': { to: 'posts' }  // ✓ Autocomplete for 'posts' works! Validated!
- *     }
+ *       // Resolve each post's href → posts resource. Validated at compile
+ *       // and runtime: the path `posts[].href` must exist on UserSchema.
+ *       'posts[].href': { to: 'posts' },
+ *     },
  *   },
  *   posts: {
  *     schema: PostSchema,
  *     links: {
- *       'author': { to: 'users' }    // ✓ Validated!
- *       // 'author': { to: 'userz' } // ✗ TypeScript error - 'userz' not in ['users', 'posts']
- *       // 'othor': { to: 'users' }  // ✗ fails during runtime validation
- *     }
- *   }
+ *       // 'author': { to: 'userz' } // ✗ TypeScript error — 'userz' not in ['users', 'posts']
+ *     },
+ *   },
  * });
  * ```
  */