ts-procedures 8.2.1 → 8.4.0

package/docs/handoffs/ajsc-named-type-support.md

@@ -0,0 +1,181 @@
+# Handoff: named-type / verbatim-type support in ajsc
+
+> **STATUS: Shipped in ajsc 7.3.0 and adopted in ts-procedures (this cutover).** The placeholder-token workaround described below has been deleted; `substituteModelRefs` now emits `{ 'x-named-type': '<Name>' }` and the codegen reads the converter's `referencedNamedTypes`. The rest of this doc is retained for historical context.
+
+**To:** ajsc maintainer
+**From:** ts-procedures codegen (consumer of ajsc as the JSON-Schema → TS/Kotlin/Swift emitter)
+**Date:** 2026-06-05
+**ajsc version inspected:** 7.2.0
+**Priority:** medium — unblocks removing a workaround in ts-procedures, no current breakage
+
+---
+
+## TL;DR
+
+ts-procedures needs a way to tell ajsc: *"this subschema is an already-defined named type called `Message` — emit a reference to it (`Message`), don't convert/inline it, and tell me you referenced it so I can add an import."*
+
+ajsc 7.2.0 has no such mechanism: a `$ref` to a `$defs` entry is **inlined and re-extracted under the property name** (with no dedup), and there is no verbatim-type escape hatch. We've worked around this downstream with a placeholder-token hack (described below) that we'd like to delete once ajsc supports this directly.
+
+The ask is small and **additive** (a new opt-in schema keyword + one new field on the emit result). Nothing changes when the keyword is absent.
+
+---
+
+## Why we need it
+
+ts-procedures generates a typed API client from a server's schema. The same domain entity (e.g. `Message`) appears in many route schemas. Today ajsc inlines a fresh structural literal at every site, so `Message` is emitted ~4–6 times under different names in one file, disconnected from each other and from the author's `Message` type. We want **one** `Message` type that every route references.
+
+We already know the identity: each such schema carries a stable `$id` (e.g. `urn:msg`) and a `title` (`Message`). So at codegen time we hoist every `$id`-bearing schema into a shared `_models.ts` (emitted via `ajsc.emitTypescript(messageSchema, { rootTypeName: 'Message' })` — which works great), and we want each *route* schema to **reference** `Message` rather than inline it.
+
+## What ajsc 7.2.0 does today (the blocker)
+
+Based on inspecting the installed `dist/`:
+
+1. **`$ref` is inlined, not referenced.** The IR layer (`ir/JSONSchemaConverter`) resolves `$ref` against `$defs`/`definitions` by inlining, and rejects non-local refs (`"Only local references are supported"`). With `inlineTypes: false`, the inlined object is then re-extracted **named after the property** — so a schema with `author`, `lastReply`, and `all` all `$ref`-ing the same `Message` emits three duplicate types `Author`, `LastReply`, `All`, with **no deduplication** and no way to make them one `Message`.
+
+   ```jsonc
+   // input
+   { "type": "object", "properties": {
+       "author":    { "$ref": "#/$defs/Message" },
+       "lastReply": { "$ref": "#/$defs/Message" } },
+     "$defs": { "Message": { "type": "object", "title": "Message",
+                             "properties": { "id": { "type": "string" } } } } }
+   ```
+   ```ts
+   // ajsc 7.2.0 output (inlineTypes:false) — duplicated, property-named, no dedup
+   export type Author    = { id?: string };
+   export type LastReply = { id?: string };
+   export type Root = { author?: Author; lastReply?: LastReply };
+   ```
+
+2. **No verbatim-type escape hatch.** Grepping `dist/` for `tsType | x-ts | verbatim | existingType | customType | rawType` returns nothing. We tried `{ tsType: 'Message' }`, `{ "x-tsType": 'Message' }`, `{ $ref: 'Message' }` (bare), `{ type:'object', tsType:'Message' }` — all are ignored (emit `any` / `{ [key:string]: unknown }`) or throw.
+
+3. **`EmitResult.imports` is empty for TypeScript.** The function-form `emitTypescript(schema, opts)` returns `{ code, rootTypeName, extractedTypeNames, imports }`, but `imports` is documented (README ~line 110) as Kotlin/Swift-only — there's no channel to surface "this TS output references external type `Message`."
+
+### Our current workaround (what we want to delete)
+
+Because ajsc can't reference a named type, ts-procedures smuggles a sentinel through ajsc and scrapes it back out:
+
+1. Before calling ajsc, replace each `$id`-bearing subschema with `{ const: '__MODELREF__Message__' }`. ajsc emits that verbatim as a string-literal type (`author?: "__MODELREF__Message__"`), and — usefully — never extracts it as a sub-type, and survives inside `Array<…>`.
+2. After ajsc, a global regex `/["']__MODELREF__([A-Za-z_$][\w$]*)__["']/g` rewrites the tokens to bare names (`author?: Message`) and collects the referenced names so we can emit `import type { Message } from './_models'`.
+
+It works and is well-tested, but it encodes a *type identity* as schema *data*, runs it through a code generator, and recovers it from generated *text* with a regex. We'd much rather express the intent directly to ajsc.
+
+---
+
+## Requested feature
+
+A new **opt-in schema keyword** that marks a subschema as an already-defined named type. When present, ajsc:
+
+1. emits a **reference** to that name (does not convert/inline the subschema, does not extract a sub-type), and
+2. **reports** the referenced name on the emit result so the caller can wire an import.
+
+### Keyword name & shape
+
+ajsc is multi-target (TS/Kotlin/Swift), so prefer a target-agnostic keyword over a TS-specific one. Suggested:
+
+```jsonc
+{ "x-named-type": "Message" }
+```
+
+`x-`-prefixed so it's unambiguously an annotation and ignored by standard JSON-Schema validators. (If you'd rather not use `x-`, `namedType` or `typeRef` are fine — your call on convention.)
+
+- **Value = string:** the identifier emitted verbatim in **every** target (`Message` in TS, Kotlin, and Swift). This matches our usage — we use the same PascalCase name across targets.
+- **Optional future extension:** allow an object for per-language names, e.g. `{ "x-named-type": { "ts": "Message", "kotlin": "Message", "swift": "Message" } }`. Not needed by us now; mentioning so the string form can widen later without a breaking change.
+
+### Semantics
+
+- The keyword **short-circuits conversion** of that subschema node: emit the bare identifier as the type, in all the positions ajsc already handles a leaf type (direct property, `Array<…>` items, union member, map value, etc.).
+- With `inlineTypes: false`, the named type is **not** added to `extractedTypeNames` (it's external — defined elsewhere).
+- The node is **not** recursed into (its `properties`/`items` are irrelevant once it's a named reference). A `type`/`properties` sitting alongside `x-named-type` should be ignored (or, if you prefer strictness, validated to match — but ignore is simpler and matches our need; we strip the body anyway).
+- **Absent keyword ⇒ zero behaviour change.** Fully backward compatible.
+
+### Reporting referenced names
+
+Add referenced external names to the emit result so the caller can build imports. Two acceptable shapes:
+
+- **Preferred:** a new field `referencedNamedTypes: string[]` on `EmitResult` (deduped, sorted or insertion-order — either is fine; we sort downstream).
+- **Or:** populate the existing (currently-empty-for-TS) `imports` field with the bare names.
+
+A new dedicated field is cleaner than overloading `imports` (which means module paths for Kotlin/Swift).
+
+### Worked example
+
+```jsonc
+// input
+{ "type": "object", "properties": {
+    "author": { "x-named-type": "Message" },
+    "replies": { "type": "array", "items": { "x-named-type": "Message" } },
+    "id": { "type": "string" } } }
+```
+
+```ts
+// desired TS output (inlineTypes:false)
+export type Root = { author?: Message; replies?: Array<Message>; id?: string };
+// emitResult.referencedNamedTypes === ['Message']   // Root is NOT polluted with a Message decl
+```
+
+```kotlin
+// desired Kotlin output
+data class Root(val author: Message? = null, val replies: List<Message>? = null, val id: String? = null)
+// referencedNamedTypes === ['Message']
+```
+
+```swift
+// desired Swift output
+struct Root: Codable { let author: Message?; let replies: [Message]?; let id: String? }
+// referencedNamedTypes === ['Message']
+```
+
+In every case ajsc does **not** define `Message` — the caller (ts-procedures) defines it once elsewhere and adds the import/reference.
+
+---
+
+## Where this likely lives in ajsc
+
+From the `dist/` surface (you know the real source layout):
+
+- **IR conversion** (`ir/JSONSchemaConverter` or equivalent): detect `x-named-type` on a node early and lower it to a new IR node kind — e.g. `NamedTypeRef(name)` — instead of converting the object. This is the one place that needs to intercept before the existing `$ref`-inline / object-extract logic runs.
+- **Each language emitter** (`typescript/`, `kotlin/`, `swift/`): render `NamedTypeRef(name)` as the bare identifier wherever a leaf type is rendered, and **collect** the name into the result.
+- **`EmitResult` type** (`index.d.ts`): add `referencedNamedTypes?: string[]` (or document `imports` carrying them for TS).
+- **`BaseConverterOpts`:** no new option needed — the keyword lives in the schema, not the options. (You *could* add a `validateNamedTypes` strictness flag later; not required.)
+
+---
+
+## Tests worth adding (mirror our spike findings)
+
+1. `x-named-type` on a direct property ⇒ `prop?: Message`, `referencedNamedTypes` includes `Message`, no `Message` extracted.
+2. Inside `array.items` ⇒ `Array<Message>` (TS) / `List<Message>` (Kotlin) / `[Message]` (Swift).
+3. Same name referenced by N properties ⇒ deduped to a single `Message` reference, `referencedNamedTypes === ['Message']` (the dedup we can't get today).
+4. As a whole root schema (`{ "x-named-type": "Message" }` at top level) ⇒ output is just `Message` (our route-response-is-exactly-a-model case).
+5. Both `inlineTypes: true` and `inlineTypes: false` behave identically for the referenced name (it's a leaf either way).
+6. Absent keyword ⇒ byte-identical to current output (regression guard).
+7. Coexists with genuine sibling extraction: a schema with one `x-named-type` property and one ordinary nested object still extracts the ordinary object normally under `inlineTypes:false`.
+
+---
+
+## How ts-procedures will consume it (integration contract)
+
+So you can sanity-check the design against the real caller:
+
+1. We already collect every `$id`-bearing subschema into a registry `{ $id, name, schema }` and emit each one standalone via `emitTypescript(schema, { rootTypeName: name })` into `_models.ts`. **No change needed there.**
+2. For each *route* schema, instead of our placeholder-token substitution, we'll walk the schema and replace each `$id`-bearing subschema with `{ "x-named-type": <name> }` before calling ajsc.
+3. We read `emitResult.referencedNamedTypes` to emit `import type { Message, … } from './_models'` per scope file.
+4. We delete `model-refs.ts` (the placeholder/regex module) entirely and the two wrapper functions in `emit-scope.ts`.
+
+The contract we depend on: **(a)** a referenced `x-named-type` is never inlined and never extracted, and **(b)** its name is reported back. Those two guarantees are the whole feature.
+
+---
+
+## Versioning
+
+Additive and opt-in ⇒ a **minor** bump (e.g. 7.3.0). No migration for existing consumers. ts-procedures will gate on the ajsc version that introduces `referencedNamedTypes` and keep the placeholder-token path as a fallback for one release if you'd like a soft cutover, or hard-switch if you prefer.
+
+---
+
+## Contact / context
+
+The placeholder-token workaround, the design rationale, and the empirical ajsc probes live in the ts-procedures repo:
+- `src/codegen/model-refs.ts` — the current substitution we want to remove
+- `src/codegen/emit-models.ts`, `collect-models.ts` — the model collection/emission (unaffected)
+- `docs/superpowers/specs/2026-06-05-dx-feedback-round-design.md` — design (see finding #3)
+- commit `483185e` — the spike that established ajsc's inlining behaviour and chose the workaround

package/docs/http-integrations.md

@@ -134,6 +134,10 @@ new HonoAppBuilder({
 
 For streaming procedures the taxonomy covers the pre-stream path only; mid-stream errors are handled via `stream.onMidStreamError`.
 
+> **Typed client classes — when you get them for free.** A taxonomy entry declared with just `{ class, statusCode }` is self-describing: its default body is `{ name, message }`, so codegen emits a typed client error class and registry entry automatically — `catch (e) { if (e instanceof ApiErrors.NotFound) ... }` works with zero extra ceremony. The framework can only do this when it knows the wire shape. Two cases where it can't, and the client falls back to the untyped `ClientHttpError` until you help it:
+> - **Custom `toResponse` without a `schema`.** Once you shape the body yourself, the framework won't guess it. Add an explicit `schema` matching your `toResponse` to restore the typed class.
+> - **Raw `ErrorDoc`s** added via `DocRegistry.documentError(...)` or a `config.errors` array (rather than a taxonomy). These carry no body contract — give them a `schema` to make them typed on the client.
+
 ### Imperative — the `onError` callback
 
 For apps that don't need typed client dispatch or declarative docs, configure `onError` directly and handle every error in one place: