ajsc 7.1.0 → 7.3.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to ajsc are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project follows [Semantic Versioning](https://semver.org/).
 
+## [7.3.0] — 2026-06-06
+
+### Added
+
+- **`x-named-type` schema keyword** for verbatim references to external, already-defined types. Set `"x-named-type": "TypeName"` on any schema node; ajsc emits a bare reference to that type without inlining or extracting it. Supported in all three languages (TypeScript, Kotlin, Swift). At the root level, ajsc emits a type alias (`export type Root = Message;` / `typealias Root = Message` / `public typealias Root = Message`). The schema body (`type`, `properties`, `$ref`, etc.) is intentionally ignored when the keyword is present.
+
+- **`referencedNamedTypes: string[]`** on `EmitResult`. Lists the names of all external types referenced via `x-named-type` in the emitted schema, deduped and sorted lexicographically. ajsc does not declare these — the caller is responsible for defining or importing them. Empty when `x-named-type` is not used. Available on `emitTypescript`, `emitKotlin`, and `emitSwift`.
+
+### Internal
+
+- New `normalizeNamedType` function exported from `ajsc/ir` — the single widen-able parsing boundary for the `x-named-type` keyword. Today accepts non-empty strings; a future per-language object form would be handled here without touching the IR shape or any emitter.
+- `computeReferencedNamedTypes` helper on `BaseConverter` collects referenced names via `walkIR` in a single IR pass after construction (mirroring `computeExtractedTypeNames`). Emitters remain pure — no name accumulation during emission.
+- New `LanguageProfile.formatRootTypeAlias` hook makes root-level alias syntax declarative for nominal-root languages (Kotlin/Swift) rather than hardcoded in each converter; TypeScript continues to alias via its generic root wrapper. Keeps the alias syntax discoverable in the extension API for future language targets.
+- Documented the `x-named-type` name-collision limitation (a referenced name matching a generated type name is not disambiguated) in the README, pinned by a regression test.
+- New cross-language golden fixture `named-types` (schema × 3 languages = 3 new golden files, corpus grows to 60).
+- Test count: 500 → 525.
+
+## [7.2.0] — 2026-04-25
+
+Maintenance release — version bump only. No source or public-API changes since
+7.1.0 (the published tag differs from 7.1.0 only in `package.json` /
+`package-lock.json`). Output is byte-identical to 7.1.0.
+
+## [7.1.0] — 2026-04-25
+
+### Added
+
+- **`inlineTypes` opt for Kotlin and Swift converters.** When `inlineTypes: true`, nested object types are emitted as nested `data class` (Kotlin) or `struct` (Swift) declarations inside their parent's body, rather than as top-level siblings. For codegen pipelines that emit multiple schemas into one namespace, this eliminates the cross-call name-collision class structurally — each parent's `Address` is name-scoped (`Body.Address` vs `Response.Address`), so no shared `nameRegistry` plumbing is required. Default: `false` (extract to top-level — the v7.0 behavior).
+  - Top-level enums and discriminated unions remain extracted regardless of `inlineTypes` — they have their own dedup story and don't benefit from nesting.
+  - The TypeScript converter has had `inlineTypes` since v6 (anonymous inline literals — a different language mechanism); the Kotlin/Swift addition uses the same opt name for the same consumer-facing intent.
+- New `nested-emission` cross-language fixture covering the inline pattern across TypeScript, Kotlin, and Swift (19th fixture, brings the golden corpus to 57 files).
+- **`generateInlineNestedDecl` and `InlineNestedCollector`** exported from `ajsc/converter` for downstream language authors implementing similar nested-decl semantics.
+
+### Internal
+
+- New shared module `src/converter/inlineEmission.ts` consolidates the per-parent collector type, the `getReferencedType` replacement, and the multi-line indent helper that previously existed (in identical form) inside both `kotlin/objectEmitter.ts` and `swift/structEmitter.ts`. Each language emitter now passes a small language-specific `formatNestedDecl(c, name, body, ir)` callback — the only part that genuinely differs.
+- Test count: 473 → 500 (per-language inline-types coverage + sibling-parent dedup pinning + the cross-language nested-emission fixture).
+- Existing TS / Kotlin / Swift goldens are byte-identical between v7.0.0 and v7.1.0 (the new opt defaults to `false`).
+
 ## [7.0.0] — 2026-04-24
 
 This release adds first-class **Kotlin** and **Swift** language targets, restores the root subpath import that v6 dropped, and ships several behavioral fixes to the TypeScript converter that consumers depending on the older buggy output may need to migrate.

package/README.md

@@ -29,15 +29,18 @@ Each emit function returns the same shape:
 
 ```ts
 interface EmitResult {
-  code: string;                   // declarations only — no `import` lines
-  rootTypeName: string;           // top-level emitted type ("User")
-  extractedTypeNames: string[];   // additional types emitted (nested objects, enums, variants)
-  imports: string[];              // language-native module/symbol paths to import
+  code: string;                        // declarations only — no `import` lines
+  rootTypeName: string;                // top-level emitted type ("User")
+  extractedTypeNames: string[];        // additional types emitted (nested objects, enums, variants)
+  imports: string[];                   // language-native module/symbol paths to import
+  referencedNamedTypes: string[];      // external types referenced via x-named-type (not declared by ajsc)
 }
 ```
 
 `code` contains type declarations only. Consumers assemble the final source file by combining `imports` with `code`.
 
+`referencedNamedTypes` lists the external type names this output refers to via the `x-named-type` keyword. ajsc does **not** declare these — the caller owns those definitions and is responsible for making them available (e.g., via an import or a sibling emit call). The list is deduped and sorted lexicographically. It is empty when no `x-named-type` annotations are present.
+
 ---
 
 ## Output examples
@@ -107,7 +110,7 @@ const { code, imports } = emitKotlin(schema);
 const file = [...imports.map((i) => `import ${i}`), "", code].join("\n");
 ```
 
-Swift `imports` are module names (`["Foundation"]`); Kotlin `imports` are fully-qualified symbol paths. TypeScript `imports` is always empty.
+Swift `imports` are module names (`["Foundation"]`); Kotlin `imports` are fully-qualified symbol paths. TypeScript `imports` is always empty — for TypeScript consumers that need to know which external named types are referenced (via `x-named-type`), use `referencedNamedTypes` instead.
 
 ---
 
@@ -173,6 +176,7 @@ All three converters accept `BaseConverterOpts` plus language-specific options.
 |--------|------|---------|-------------|
 | `serializer` | `"kotlinx" \| "none"` | `"kotlinx"` | Emit `@Serializable`/`@SerialName`/`@Contextual` annotations and matching imports. `"none"` emits plain types. |
 | `packageName` | `string` | `undefined` | If set, emit `package <name>` at the top of the output. |
+| `inlineTypes` | `boolean` | `false` | If true, nested object types emit as nested `data class` declarations inside their parent's body block instead of extracting to top-level siblings. Top-level enums and discriminated unions remain extracted. See "Emitting multiple schemas into one namespace" for the motivation. |
 
 ### Swift (`SwiftConverterOpts`)
 
@@ -180,6 +184,7 @@ All three converters accept `BaseConverterOpts` plus language-specific options.
 |--------|------|---------|-------------|
 | `serializer` | `"codable" \| "none"` | `"codable"` | Emit `: Codable` conformance, `CodingKeys` enums, and discriminated-union `init(from:)`/`encode(to:)` plumbing. `"none"` emits plain types. |
 | `accessLevel` | `"public" \| "internal"` | `"public"` | Access modifier on emitted types and members. |
+| `inlineTypes` | `boolean` | `false` | If true, nested object types emit as nested `struct` declarations inside their parent's body block instead of extracting to top-level siblings. Top-level enums and discriminated `enum`s remain extracted. See "Emitting multiple schemas into one namespace" for the motivation. |
 
 ---
 
@@ -235,6 +240,39 @@ Schema-level `default` values are emitted inline for primitive types in Kotlin/S
 
 Codegen pipelines that emit several sibling schemas into a shared output (e.g., wrapping an endpoint's `pathParams`, `query`, `body`, `response`, and error types under a single Kotlin `object` or Swift `enum`) need to avoid duplicate-name collisions across the emit calls. Each emit call has its own private name-tracking state by default, so two slots with a nested `address: { type: "object" }` would each emit a `data class Address(...)` — a duplicate-class compile error in the merged output.
 
+There are two ways to fix this: nest extracted types inside the parent (recommended for Kotlin/Swift), or share a name registry across calls. Pick whichever output shape your pipeline wants.
+
+### Recommended: `inlineTypes: true` (Kotlin / Swift)
+
+Set `inlineTypes: true` per emit call. Each parent's nested object types are emitted as nested `data class` (Kotlin) or `struct` (Swift) declarations inside the parent's body block, scoped to its namespace. Cross-call collisions disappear structurally — no shared registry plumbing required.
+
+```ts
+import { emitKotlin } from "ajsc";
+
+const body     = emitKotlin(bodySchema,     { inlineTypes: true, rootTypeName: "Body" });
+const response = emitKotlin(responseSchema, { inlineTypes: true, rootTypeName: "Response" });
+
+// body.code:
+//   data class Body(val address: Address, ...) {
+//     data class Address(val street: String, ...)
+//   }
+// response.code:
+//   data class Response(val address: Address, ...) {
+//     data class Address(val street: String, ...)
+//   }
+//
+// Concatenated under one `object Endpoint { ... }` — no name collisions:
+// Body.Address and Response.Address are different scoped names.
+```
+
+`inlineTypes: true` only nests plain object types. Top-level enums and discriminated unions (sealed interface in Kotlin, enum w/ associated values in Swift) remain at the same level as the parent — they have their own dedup story (canonical-key for enums; self-contained namespace for discriminated unions) and don't benefit from nesting.
+
+The TypeScript converter has had `inlineTypes` since v6 — it produces anonymous inline type literals (a different language mechanism, same `inlineTypes` option name).
+
+### Alternative: shared `nameRegistry` + per-slot `namePrefix`
+
+Use this when you specifically want flat top-level output (cleaner imports, simpler navigation in IDE outline panels).
+
 Pass a shared `nameRegistry: Set<string>` across calls. The converter uses it as its declaration registry and mutates it as new types are emitted. Pair with `namePrefix` for clean per-slot names:
 
 ```ts
@@ -280,6 +318,102 @@ emitKotlin(responseSchema, { nameRegistry: registry, rootTypeName: "Response" })
 
 Both `nameRegistry` and `namePrefix` work for all three languages. They're most useful for Kotlin and Swift, which require named declarations for non-primitive types. TypeScript supports them too but rarely needs them — most codegen pipelines use `inlineTypes: true` to flatten nested types instead.
 
+### Choosing between `inlineTypes` and `nameRegistry`
+
+| If you want…                                     | Use                                          |
+|--------------------------------------------------|----------------------------------------------|
+| Flat top-level decls (`Body`, `BodyAddress`, …)  | `nameRegistry` + `namePrefix`                |
+| Nested decls inside each parent (idiomatic K/S)  | `inlineTypes: true`                          |
+| TypeScript anonymous inline literals             | `inlineTypes: true` (TS-specific mechanism)  |
+
+---
+
+## x-named-type — referencing external types verbatim
+
+The `x-named-type` keyword lets you tell ajsc to emit a bare reference to an already-defined external type instead of inlining or extracting it from the schema.
+
+### When to use it
+
+Use `x-named-type` when a property's type is defined elsewhere (a shared library, a hand-written class, a type from another emit call) and you want ajsc to reference it without redeclaring it.
+
+### Usage
+
+Set `"x-named-type": "TypeName"` on any schema node. ajsc short-circuits that node to a verbatim reference — the schema body (`type`, `properties`, `$ref`, etc.) is intentionally ignored.
+
+```json
+{
+  "type": "object",
+  "title": "Thread",
+  "properties": {
+    "author":    { "x-named-type": "Message" },
+    "lastReply": { "x-named-type": "Message" },
+    "replies":   { "type": "array", "items": { "x-named-type": "Message" } },
+    "id":        { "type": "string" }
+  }
+}
+```
+
+**TypeScript output:**
+```ts
+export type Thread = { author?: Message; lastReply?: Message; replies?: Array<Message>; id?: string; };
+```
+
+**Kotlin output:**
+```kotlin
+@Serializable
+data class Thread(
+  val author: Message? = null,
+  val lastReply: Message? = null,
+  val replies: List<Message>? = null,
+  val id: String? = null,
+)
+```
+
+**Swift output:**
+```swift
+public struct Thread: Codable {
+  public let author: Message?
+  public let lastReply: Message?
+  public let replies: [Message]?
+  public let id: String?
+}
+```
+
+### At the root
+
+When `x-named-type` appears at the root level, ajsc emits a type alias:
+
+- TypeScript: `export type Root = Message;`
+- Kotlin: `typealias Root = Message`
+- Swift: `public typealias Root = Message`
+
+### Reporting referenced names
+
+Referenced names are collected in `referencedNamedTypes` on the emit result (deduped and sorted). ajsc does **not** declare these types — the caller is responsible for importing or defining them:
+
+```ts
+const { code, referencedNamedTypes } = emitTypescript(schema);
+// referencedNamedTypes: ["Message"]
+// → caller must import or declare Message separately
+```
+
+### Constraints
+
+- The value must be a non-empty string (the type name to emit verbatim).
+- The schema body is ignored — ajsc never inlines or extracts the node.
+- `Message` will **not** appear in `extractedTypeNames` (ajsc did not declare it).
+
+### Limitations
+
+- **Name collisions are not disambiguated.** If an `x-named-type` value matches a
+  name ajsc generates for a sibling structural type (e.g. you reference
+  `"Profile"` while a sibling object would also extract as `Profile`), ajsc emits
+  the generated declaration and the reference resolves to *that* type — the two
+  are silently merged. Keep `x-named-type` names distinct from the names ajsc
+  derives from your property/path structure. Both names appearing in
+  `extractedTypeNames` **and** `referencedNamedTypes` is the signal that a
+  collision occurred.
+
 ---
 
 ## Working with the IR directly

package/dist/converter/BaseConverter.d.ts

@@ -1,5 +1,6 @@
 import { ILanguageConverter, IRNode, SignatureOccurrenceValue } from "../types.js";
-export { walkIR } from "./walk.js";
+import { walkIR } from "./walk.js";
+export { walkIR };
 export type RefTypeName = string;
 export interface RefTypeEntry {
     signature: SignatureOccurrenceValue["signature"];
@@ -67,6 +68,15 @@ export interface LanguageProfile {
      * Language-specific signature dedup decision. Default: false. TS = `dedupSignatures.has(sig)`.
      */
     shouldReuseExistingSignature?: (signature: string) => boolean;
+    /**
+     * Formats a root-level type alias when the schema root is an `x-named-type`
+     * reference (e.g. Kotlin `typealias Root = Message`). Languages that render
+     * the root through a generic alias wrapper — TypeScript's
+     * `export type Root = <type>` — omit this and get the alias for free.
+     * Languages whose roots are nominal declarations (Kotlin `data class`, Swift
+     * `struct`) provide it so a bare root reference becomes a typealias instead.
+     */
+    formatRootTypeAlias?: (rootName: string, target: string) => string;
 }
 export interface RefTypeNamingConfig {
     /** Base postfixes to try for name collision resolution */
@@ -197,6 +207,7 @@ export declare abstract class BaseConverter implements Partial<ILanguageConverte
     abstract readonly rootTypeName: string;
     abstract readonly extractedTypeNames: string[];
     abstract readonly imports: string[];
+    abstract readonly referencedNamedTypes: string[];
     get language(): string;
     /** @internal Public for `BaseConverterContext`; treat as protected for subclasses. */
     refTypes: RefTypes;
@@ -251,6 +262,12 @@ export declare abstract class BaseConverter implements Partial<ILanguageConverte
      * Subclasses may filter further (e.g. to exclude the root type).
      */
     protected computeExtractedTypeNames(): string[];
+    /**
+     * Collects the names of all external types referenced via `x-named-type`,
+     * deduped and lexicographically sorted. Derived purely from the IR (the set
+     * is independent of language emission), mirroring computeExtractedTypeNames.
+     */
+    protected computeReferencedNamedTypes(ir: IRNode): string[];
     /** Path-derived, collision-free ref type name. Delegates to `naming.ts`. */
     protected getUniqueRefTypeName(signature: string, nodePath: string): RefTypeName;
     /**

package/dist/converter/BaseConverter.js

@@ -2,7 +2,8 @@ import { computeExtractedTypeNames, getUniqueRefTypeName, } from "./naming.js";
 import { getReferencedType } from "./registry.js";
 import { isDiscriminatedUnion, mergeCompatibleUnions, tryMergeObjectUnion, tryMergeProperty, } from "./mergeUnions.js";
 import { applyDiscriminatedUnionEnhancements, collectUnionPropertyNames, enhanceDiscriminatedUnions, findDiscriminatorProperty, getConstStringValue, stripDiscriminatorField, } from "./discriminatedUnions.js";
-export { walkIR } from "./walk.js";
+import { walkIR } from "./walk.js";
+export { walkIR };
 export class BaseConverter {
     constructor() {
         /** @internal Public for `BaseConverterContext`; treat as protected for subclasses. */
@@ -44,6 +45,20 @@ export class BaseConverter {
     computeExtractedTypeNames() {
         return computeExtractedTypeNames(this);
     }
+    /**
+     * Collects the names of all external types referenced via `x-named-type`,
+     * deduped and lexicographically sorted. Derived purely from the IR (the set
+     * is independent of language emission), mirroring computeExtractedTypeNames.
+     */
+    computeReferencedNamedTypes(ir) {
+        const names = new Set();
+        walkIR(ir, (node) => {
+            if (node.type === "namedTypeRef" && node.namedType) {
+                names.add(node.namedType);
+            }
+        });
+        return [...names].sort();
+    }
     /** Path-derived, collision-free ref type name. Delegates to `naming.ts`. */
     getUniqueRefTypeName(signature, nodePath) {
         return getUniqueRefTypeName(this, signature, nodePath);

package/dist/converter/BaseConverter.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseConverter.js","sourceRoot":"","sources":["../../src/converter/BaseConverter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseConverter.js","sourceRoot":"","sources":["../../src/converter/BaseConverter.ts"],"names":[],"mappings":"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"}

package/dist/converter/index.d.ts

@@ -3,9 +3,10 @@
  *
  * This subpath exposes the abstract {@link BaseConverter} class, the
  * {@link LanguageProfile} pattern that consolidates per-language behavior,
- * the {@link RefTypeEntry} registry shape, the indent-aware {@link Emitter}
- * helper (re-exported from `./Emitter.js` if needed by subclasses), and the
- * {@link walkIR} tree-walking helper.
+ * the {@link RefTypeEntry} registry shape, the indent-aware Emitter helper
+ * (importable from `./Emitter.js`), the {@link walkIR} tree-walking helper,
+ * and the {@link generateInlineNestedDecl} helper used by language emitters
+ * to implement `inlineTypes`-style nested-class output.
  *
  * Most consumers do NOT need this subpath — use the function-style emitters
  * (`emitTypescript` / `emitKotlin` / `emitSwift` from `ajsc`) or the
@@ -22,3 +23,5 @@
  */
 export { BaseConverter, walkIR } from "./BaseConverter.js";
 export type { BaseConverterOpts, RefTypeNamingConfig, RefTypeEntry, GenerateTypeUtils, LanguageProfile, } from "./BaseConverter.js";
+export { generateInlineNestedDecl, indentLines } from "./inlineEmission.js";
+export type { InlineNestedCollector } from "./inlineEmission.js";

package/dist/converter/index.js

@@ -3,9 +3,10 @@
  *
  * This subpath exposes the abstract {@link BaseConverter} class, the
  * {@link LanguageProfile} pattern that consolidates per-language behavior,
- * the {@link RefTypeEntry} registry shape, the indent-aware {@link Emitter}
- * helper (re-exported from `./Emitter.js` if needed by subclasses), and the
- * {@link walkIR} tree-walking helper.
+ * the {@link RefTypeEntry} registry shape, the indent-aware Emitter helper
+ * (importable from `./Emitter.js`), the {@link walkIR} tree-walking helper,
+ * and the {@link generateInlineNestedDecl} helper used by language emitters
+ * to implement `inlineTypes`-style nested-class output.
  *
  * Most consumers do NOT need this subpath — use the function-style emitters
  * (`emitTypescript` / `emitKotlin` / `emitSwift` from `ajsc`) or the
@@ -21,4 +22,5 @@
  * Treat `@internal`-tagged symbols as protected.
  */
 export { BaseConverter, walkIR } from "./BaseConverter.js";
+export { generateInlineNestedDecl, indentLines } from "./inlineEmission.js";
 //# sourceMappingURL=index.js.map

package/dist/converter/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/converter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/converter/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQ3D,OAAO,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/converter/inlineEmission.d.ts

@@ -0,0 +1,42 @@
+import type { BaseConverterContext, GenerateTypeUtils } from "./BaseConverter.js";
+import type { IRNode } from "../types.js";
+/**
+ * Per-parent collector used by language emitters under `inlineTypes: true` to
+ * accumulate nested type declarations destined for the parent's body block.
+ *
+ * Each invocation of `generate<Lang>ObjectType` allocates its own collector,
+ * so grandchildren nest into the child's body — preserving the schema's
+ * containment structure rather than flattening to the outermost parent.
+ *
+ * - `decls`: fully-formatted nested type declaration strings, in emission order.
+ * - `bySignature`: within-parent dedup map (signature → already-assigned name).
+ *   Two properties of the same parent referencing the same shape share one
+ *   nested decl; two properties of *different* parents do not (each parent's
+ *   nested decls are scoped to its own namespace).
+ */
+export interface InlineNestedCollector {
+    decls: string[];
+    bySignature: Map<string, string>;
+}
+/**
+ * Inline-mode replacement for `getReferencedType`. Returns the name to use in
+ * place of an extracted top-level reference, side-effecting `collector` with a
+ * fully-formatted nested type declaration when this signature is first seen.
+ *
+ * Language-specific decl assembly is delegated to `formatDecl` (e.g. Kotlin's
+ * `[@Serializable\n]data class ${name}${body}` vs Swift's `${access} struct
+ * ${name}: Codable ${body}`). The recursive emit step is delegated to
+ * `recurseObjectType` — typically the language's `generate<Lang>ObjectType`
+ * function. We pass it our parent's collector-aware utils as a defensive
+ * default; the recursive call sees `c.inlineTypes === true` and will still
+ * allocate its own collector internally for *its* nested types.
+ *
+ * Side effect to be aware of: `defaultResolveRefTypeName` reserves the chosen
+ * name in `c.usedDeclarationNames`. That reservation is what prevents nested
+ * names from colliding with top-level enum / discriminated-union names emitted
+ * elsewhere in the same converter run, and it's why a shared `nameRegistry`
+ * across emit calls flows through to nested-decl naming.
+ */
+export declare function generateInlineNestedDecl<C extends BaseConverterContext>(c: C, ir: IRNode, collector: InlineNestedCollector, formatDecl: (c: C, name: string, body: string, ir: IRNode) => string, recurseObjectType: (c: C, ir: IRNode, utils: GenerateTypeUtils) => string): string | undefined;
+/** Indents each non-empty line of `text` by `n` spaces. */
+export declare function indentLines(text: string, n: number): string;

package/dist/converter/inlineEmission.js

@@ -0,0 +1,49 @@
+import { defaultResolveRefTypeName } from "./naming.js";
+/**
+ * Inline-mode replacement for `getReferencedType`. Returns the name to use in
+ * place of an extracted top-level reference, side-effecting `collector` with a
+ * fully-formatted nested type declaration when this signature is first seen.
+ *
+ * Language-specific decl assembly is delegated to `formatDecl` (e.g. Kotlin's
+ * `[@Serializable\n]data class ${name}${body}` vs Swift's `${access} struct
+ * ${name}: Codable ${body}`). The recursive emit step is delegated to
+ * `recurseObjectType` — typically the language's `generate<Lang>ObjectType`
+ * function. We pass it our parent's collector-aware utils as a defensive
+ * default; the recursive call sees `c.inlineTypes === true` and will still
+ * allocate its own collector internally for *its* nested types.
+ *
+ * Side effect to be aware of: `defaultResolveRefTypeName` reserves the chosen
+ * name in `c.usedDeclarationNames`. That reservation is what prevents nested
+ * names from colliding with top-level enum / discriminated-union names emitted
+ * elsewhere in the same converter run, and it's why a shared `nameRegistry`
+ * across emit calls flows through to nested-decl naming.
+ */
+export function generateInlineNestedDecl(c, ir, collector, formatDecl, recurseObjectType) {
+    if (!ir.signature)
+        return undefined;
+    if ((c.languageProfile.detectSelfReferenceToRoot ?? true) &&
+        ir.name &&
+        ir.name === c.rootName) {
+        return c.rootName;
+    }
+    const cached = collector.bySignature.get(ir.signature);
+    if (cached)
+        return cached;
+    const name = defaultResolveRefTypeName(c, ir, ir.signature);
+    collector.bySignature.set(ir.signature, name);
+    const childUtils = {
+        getReferencedType: (node) => generateInlineNestedDecl(c, node, collector, formatDecl, recurseObjectType),
+    };
+    const body = recurseObjectType(c, ir, childUtils);
+    collector.decls.push(formatDecl(c, name, body, ir));
+    return name;
+}
+/** Indents each non-empty line of `text` by `n` spaces. */
+export function indentLines(text, n) {
+    const pad = " ".repeat(n);
+    return text
+        .split("\n")
+        .map((line) => (line.length ? pad + line : line))
+        .join("\n");
+}
+//# sourceMappingURL=inlineEmission.js.map

package/dist/converter/inlineEmission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inlineEmission.js","sourceRoot":"","sources":["../../src/converter/inlineEmission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAuBxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,wBAAwB,CACtC,CAAI,EACJ,EAAU,EACV,SAAgC,EAChC,UAAoE,EACpE,iBAAyE;IAEzE,IAAI,CAAC,EAAE,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IAEpC,IACE,CAAC,CAAC,CAAC,eAAe,CAAC,yBAAyB,IAAI,IAAI,CAAC;QACrD,EAAE,CAAC,IAAI;QACP,EAAE,CAAC,IAAI,KAAK,CAAC,CAAC,QAAQ,EACtB,CAAC;QACD,OAAO,CAAC,CAAC,QAAQ,CAAC;IACpB,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,yBAAyB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5D,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAE9C,MAAM,UAAU,GAAsB;QACpC,iBAAiB,EAAE,CAAC,IAAI,EAAE,EAAE,CAC1B,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,CAAC;KAC9E,CAAC;IACF,MAAM,IAAI,GAAG,iBAAiB,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IAElD,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACpD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,CAAS;IACjD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAChD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -33,6 +33,12 @@ export interface EmitResult {
      *   const file = [...imports.map((i) => `import ${i}`), "", code].join("\n");
      */
     imports: string[];
+    /**
+     * Names of external, already-defined types this output references via the
+     * `x-named-type` schema keyword. ajsc does NOT declare these — the caller
+     * defines them elsewhere and wires the import/reference. Deduped and sorted.
+     */
+    referencedNamedTypes: string[];
 }
 /**
  * Emits TypeScript source for the given JSON Schema.

package/dist/index.js

@@ -18,6 +18,7 @@ function toEmitResult(c) {
         rootTypeName: c.rootTypeName,
         extractedTypeNames: c.extractedTypeNames,
         imports: c.imports,
+        referencedNamedTypes: c.referencedNamedTypes,
     };
 }
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,0CAA0C;AAC1C,EAAE;AACF,uDAAuD;AACvD,EAAE;AACF,uCAAuC;AACvC,oFAAoF;AACpF,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AAGjF,OAAO,EACL,mBAAmB,GAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAsC1B,SAAS,YAAY,CAAC,CAKrB;IACC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,kBAAkB,EAAE,CAAC,CAAC,kBAAkB;QACxC,OAAO,EAAE,CAAC,CAAC,OAAO;KACnB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA6B,EAC7B,IAA8B;IAE9B,OAAO,YAAY,CAAC,IAAI,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,MAA6B,EAC7B,IAA0B;IAE1B,OAAO,YAAY,CAAC,IAAI,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,MAA6B,EAC7B,IAAyB;IAEzB,OAAO,YAAY,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,oEAAoE;AACpE,iFAAiF;AACjF,qEAAqE;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,0CAA0C;AAC1C,EAAE;AACF,uDAAuD;AACvD,EAAE;AACF,uCAAuC;AACvC,oFAAoF;AACpF,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AAGjF,OAAO,EACL,mBAAmB,GAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,cAAc,GAEf,MAAM,kBAAkB,CAAC;AA6C1B,SAAS,YAAY,CAAC,CAMrB;IACC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,kBAAkB,EAAE,CAAC,CAAC,kBAAkB;QACxC,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,oBAAoB,EAAE,CAAC,CAAC,oBAAoB;KAC7C,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA6B,EAC7B,IAA8B;IAE9B,OAAO,YAAY,CAAC,IAAI,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,MAA6B,EAC7B,IAA0B;IAE1B,OAAO,YAAY,CAAC,IAAI,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CACvB,MAA6B,EAC7B,IAAyB;IAEzB,OAAO,YAAY,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,oEAAoE;AACpE,iFAAiF;AACjF,qEAAqE;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/ir/JSONSchemaConverter.d.ts

@@ -1,5 +1,14 @@
 import { JSONSchema7Definition } from "json-schema";
 import { ConverterOptions, IRNode, SignatureOccurrences } from "../types.js";
+/**
+ * Normalizes the `x-named-type` keyword value into a single external type name.
+ *
+ * This is the one widen-able boundary for the keyword: today only the string
+ * form is supported. A future per-language object form (e.g.
+ * `{ ts, kotlin, swift }`) would be resolved here without touching the IR shape
+ * or any emitter.
+ */
+export declare function normalizeNamedType(value: unknown): string | undefined;
 /**
  * JSONSchemaConverter converts a JSON Schema (Draft-07) into an
  * intermediate representation (IR) that can later be transformed

package/dist/ir/JSONSchemaConverter.js

@@ -1,3 +1,16 @@
+/**
+ * Normalizes the `x-named-type` keyword value into a single external type name.
+ *
+ * This is the one widen-able boundary for the keyword: today only the string
+ * form is supported. A future per-language object form (e.g.
+ * `{ ts, kotlin, swift }`) would be resolved here without touching the IR shape
+ * or any emitter.
+ */
+export function normalizeNamedType(value) {
+    if (typeof value === "string" && value.trim() !== "")
+        return value;
+    return undefined;
+}
 /**
  * JSONSchemaConverter converts a JSON Schema (Draft-07) into an
  * intermediate representation (IR) that can later be transformed
@@ -105,6 +118,16 @@ export class JSONSchemaConverter {
                 };
             }
         }
+        // `x-named-type`: short-circuit to an external named-type reference, ahead
+        // of $ref resolution. The subschema body (type/properties/$ref) is
+        // intentionally ignored — this node is a verbatim reference to a
+        // caller-defined type, never inlined or extracted.
+        const namedType = normalizeNamedType(schema["x-named-type"]);
+        if (namedType) {
+            const node = { type: "namedTypeRef", namedType, path: ctx.path };
+            this.applyMetadata(node, schema);
+            return node;
+        }
         // Step 1.4: If the schema contains a $ref, resolve it with cycle detection.
         if (schema.$ref) {
             const ref = schema.$ref;