From 9e0e33f96d561101225f5b0bc73b013cf8aae4f0 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 14:01:07 +0000 Subject: [PATCH 1/2] fix(spec): give the OData @example Programmatic Use bag its $ prefixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The file-level docblock of `packages/spec/src/api/odata.zod.ts` carried an `@example Programmatic Use` block writing every `ODataQuery` key unprefixed — `select`, `filter`, `orderby`, `top`, `skip`, `expand`, `count` — while every key the schema declares carries a `$`. `ODataQuerySchema.safeParse` on that bag succeeded and returned `{}`: all seven keys stripped, no error, no warning. Measured against a bag of one fabricated key, the documented bag parsed identically. The correct spelling was already ten lines above in the same docblock: the `@example OData Query` block spells the URL conventions `$select=`, `$filter=`, `$orderby=`, `$top=`, `$skip=`, `$expand=`, `$count=`. Only the second example was wrong; this commit prefixes its seven keys and regenerates the reference page the same docblock feeds. Example prose only — the schema, its accept set and its unknown-key behaviour are untouched, so there is no behaviour change. Claude-Session: https://claude.ai/code/session_01JbZnqu8bt6YqfJsr9vaFb3 Co-authored-by: Claude --- packages/spec/src/api/odata.zod.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/spec/src/api/odata.zod.ts b/packages/spec/src/api/odata.zod.ts index b25169449f..f411aeca94 100644 --- a/packages/spec/src/api/odata.zod.ts +++ b/packages/spec/src/api/odata.zod.ts @@ -54,13 +54,13 @@ import { z } from 'zod'; * @example Programmatic Use * ```typescript * const query: ODataQuery = { - * select: ['name', 'email'], - * filter: "country eq 'US' and revenue gt 100000", - * orderby: 'revenue desc', - * top: 10, - * skip: 20, - * expand: ['orders'], - * count: true + * $select: ['name', 'email'], + * $filter: "country eq 'US' and revenue gt 100000", + * $orderby: 'revenue desc', + * $top: 10, + * $skip: 20, + * $expand: ['orders'], + * $count: true * } * ``` */ From 84f244a07d4fe2090a872b7d8ececda3094cc3b9 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 18 Sep 2026 14:05:42 +0000 Subject: [PATCH 2/2] docs(spec): regenerate the OData reference page and add the patch changeset `pnpm --filter @objectstack/spec gen:docs` reprojects the corrected docblock into `content/docs/references/api/odata.mdx`; of the 224 files the generator wrote, that page is the only one that moved. `packages/spec` ships `src/**/*.zod.ts` in its `files[]` and the corrected file is in the tarball, so this publishes and takes a patch changeset. Claude-Session: https://claude.ai/code/session_01JbZnqu8bt6YqfJsr9vaFb3 Co-authored-by: Claude --- ...xample-programmatic-use-dollar-prefixes.md | 21 +++++++++++++++++++ content/docs/references/api/odata.mdx | 14 ++++++------- 2 files changed, 28 insertions(+), 7 deletions(-) create mode 100644 .changeset/odata-example-programmatic-use-dollar-prefixes.md diff --git a/.changeset/odata-example-programmatic-use-dollar-prefixes.md b/.changeset/odata-example-programmatic-use-dollar-prefixes.md new file mode 100644 index 0000000000..e3b216158d --- /dev/null +++ b/.changeset/odata-example-programmatic-use-dollar-prefixes.md @@ -0,0 +1,21 @@ +--- +"@objectstack/spec": patch +--- + +docs(spec): the OData `@example Programmatic Use` bag is spelled with the `$` prefixes the schema actually declares (#19028) + +The file-level docblock of `src/api/odata.zod.ts` carried an `@example Programmatic Use` block that wrote every `ODataQuery` key unprefixed — `select`, `filter`, `orderby`, `top`, `skip`, `expand`, `count` — while every key the schema declares carries a `$`. Measured with `safeParse` on that bag verbatim: + +| bag | result | +|:---|:---| +| the documented bag, verbatim | `success: true`, `data: {}` — all seven keys stripped | +| the same bag with `$` prefixes | `success: true`, all seven keys retained | +| a bag holding one fabricated key | `success: true`, `data: {}` | + +So the documented bag and a bag of pure nonsense parsed identically: accepted, silently emptied, no error and no warning. An author who copied it got a query that asked for nothing — no projection, no filter, no ordering, no paging — with nothing anywhere to say so. + +The correct spelling was already ten lines above it in the same docblock: the `@example OData Query` block spells the URL conventions `$select=`, `$filter=`, `$orderby=`, `$top=`, `$skip=`, `$expand=`, `$count=`. Only the second example contradicted the schema, and only the second example moves here. + +**What reaches a consumer.** `@objectstack/spec` ships `src/**/*.zod.ts` in its `files[]`, so this docblock is in the installed tarball as well as on the generated reference page `content/docs/references/api/odata.mdx`, which the same docblock feeds. Both now show the seven prefixed keys. + +**What does not move.** Example prose only. `ODataQuerySchema` is untouched — same accept set, same optionality, same unknown-key behaviour: a key it did not declare is still accepted and stripped rather than refused, exactly as before. No export, no type, no runtime path changes, and no test assertion needed editing. Whether that stripping should instead be a refusal is a separate question, deliberately not answered here. diff --git a/content/docs/references/api/odata.mdx b/content/docs/references/api/odata.mdx index 20ed87d922..c5b4dd3b67 100644 --- a/content/docs/references/api/odata.mdx +++ b/content/docs/references/api/odata.mdx @@ -57,13 +57,13 @@ GET /api/odata/customers? **Programmatic Use** ```typescript const query: ODataQuery = { - select: ['name', 'email'], - filter: "country eq 'US' and revenue gt 100000", - orderby: 'revenue desc', - top: 10, - skip: 20, - expand: ['orders'], - count: true + $select: ['name', 'email'], + $filter: "country eq 'US' and revenue gt 100000", + $orderby: 'revenue desc', + $top: 10, + $skip: 20, + $expand: ['orders'], + $count: true } ```