genoc 0.4.0 → 0.4.2

package/README.md

@@ -4,7 +4,7 @@ Generate TypeScript HTTP clients from OpenAPI 3.0 or 3.1 specifications.
 Generated code depends only on the tiny `genoc/runtime` module. Full type safety. Bring your own HTTP client.
 
 [![npm version](https://img.shields.io/npm/v/genoc)](https://www.npmjs.com/package/genoc)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.18.1-green)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/typescript-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
@@ -122,7 +122,7 @@ For the full example of catching and narrowing errors, see [Error handling](./do
 
 ## Requirements
 
-- Node.js 18 or later
+- Node.js 20.18.1 or later
 - OpenAPI 3.0.x or 3.1.x specification (JSON or YAML, file path or URL)
 
 ## License

package/dist/analyzer/analyze.js

@@ -1,42 +1,21 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { buildSchemaRenameMap, buildTypeJsDoc, sanitizeJsDocText, sanitizeTypeName, toPascalCase, } from '../utils/generator-helpers.js';
 import { operationEmissions, RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { buildDiscriminatorRegistry, renameAwareTypeName } from './discriminator-registry.js';
 import { analyzePathsDetailed } from './path-analyzer.js';
 import { SchemaMapper } from './schema-mapper.js';
-/**
- * If the schema is a $ref to a discriminated base type (or an array whose items
- * are), replace the type name with the {Base}Variant union type.
- */
-function substituteDiscriminatedType(tsType, schema, discriminatorInfo, renameMap) {
-    const refSchema = schema;
-    if (!refSchema || typeof refSchema !== 'object')
-        return tsType;
-    if (typeof refSchema.$ref === 'string') {
-        const rawName = refSchema.$ref.split('/').pop();
-        const schemaName = sanitizeTypeName(rawName);
-        if (schemaName && discriminatorInfo.has(schemaName)) {
-            const renamed = renameMap.get(rawName) ?? schemaName;
-            return tsType.replace(new RegExp(`\\b${renamed}\\b`, 'g'), `${renamed}Variant`);
-        }
-    }
-    if (refSchema.items && typeof refSchema.items === 'object') {
-        const items = refSchema.items;
-        if (typeof items.$ref === 'string') {
-            const rawName = items.$ref.split('/').pop();
-            const schemaName = sanitizeTypeName(rawName);
-            if (schemaName && discriminatorInfo.has(schemaName)) {
-                const renamed = renameMap.get(rawName) ?? schemaName;
-                return tsType.replace(new RegExp(`\\b${renamed}\\b`, 'g'), `${renamed}Variant`);
-            }
-        }
-    }
-    return tsType;
-}
 /**
  * Indent unit matching `INDENT_UNIT` in schema-mapper.ts (2 spaces, pinned by
  * the mapper's golden tests). Kept local to avoid modifying the mapper module.
  */
 const INDENT_UNIT = '  ';
+/**
+ * Shared warning channel for analyze() and the discriminator registry —
+ * the same sink the mapper defaults to.
+ */
+function writeWarning(message) {
+    process.stderr.write(message);
+}
 /**
  * Build a description-only type-level JSDoc comment for operation-derived
  * types (body / response). Returns '' when the description is absent or
@@ -301,45 +280,25 @@ export function analyze(doc, opts = {}) {
     const renamingTypeGenerator = (refString) => {
         const segments = refString.split('/');
         const rawSegment = segments[segments.length - 1] || 'unknown';
-        return renameMap.get(rawSegment) ?? sanitizeTypeName(rawSegment);
+        return renameAwareTypeName(renameMap, rawSegment);
     };
-    const discriminatorInfo = new Map();
-    if (doc.components?.schemas) {
-        for (const [name, schema] of Object.entries(doc.components.schemas)) {
-            const resolved = resolver.resolve(schema);
-            if (resolved.discriminator) {
-                const mapping = new Map();
-                if (resolved.discriminator.mapping) {
-                    for (const [key, ref] of Object.entries(resolved.discriminator.mapping)) {
-                        const rawTarget = ref.split('/').pop() || key;
-                        const renamedTarget = renameMap.get(rawTarget) ?? sanitizeTypeName(rawTarget);
-                        mapping.set(key, renamedTarget);
-                    }
-                }
-                discriminatorInfo.set(sanitizeTypeName(name), {
-                    rawName: name,
-                    propertyName: resolved.discriminator.propertyName,
-                    mapping,
-                });
-            }
-        }
-    }
-    const discriminatorTargets = new Map();
-    for (const [, info] of discriminatorInfo) {
-        for (const [mappingKey, schemaName] of info.mapping) {
-            discriminatorTargets.set(schemaName, {
-                propertyName: info.propertyName,
-                literalValue: mappingKey,
-            });
-        }
-    }
     const allSchemaNames = new Set();
     if (doc.components?.schemas) {
         for (const name of Object.keys(doc.components.schemas)) {
             allSchemaNames.add(renameMap.get(name) ?? sanitizeTypeName(name));
         }
     }
-    const mapper = new SchemaMapper(resolver, renamingTypeGenerator, discriminatorTargets, allSchemaNames);
+    // Family-aware discriminator registry (plan D5) — the single knowledge
+    // source for discriminator translation: the mapper's ref-translation seam
+    // consumes it, and the always-emitted `{Base}Variant` unions below are
+    // emitted from it.
+    const discriminatorRegistry = buildDiscriminatorRegistry(doc.components?.schemas, resolver, renameMap, allSchemaNames, writeWarning);
+    const mapper = new SchemaMapper(resolver, {
+        typeNameGenerator: renamingTypeGenerator,
+        emittedNames: allSchemaNames,
+        discriminatorRegistry,
+        effectiveVersion: opts?.effectiveVersion,
+    });
     // Section 1: Schema types
     const schemaEntries = [];
     if (doc.components?.schemas) {
@@ -362,17 +321,18 @@ export function analyze(doc, opts = {}) {
         definition: entry.definition,
         jsDoc: entry.jsDoc,
     }));
-    for (const [, info] of discriminatorInfo) {
-        const subtypeNames = Array.from(info.mapping.values());
-        if (subtypeNames.length === 0)
+    // Variant unions are emitted from the registry (D6): ALWAYS (mapping
+    // values ∪ implicit oneOf/anyOf refs, deduped by rename-aware name) and
+    // under collision-safe names so a user schema named `{Base}Variant`
+    // cannot collide with the generated union.
+    for (const family of discriminatorRegistry.families.values()) {
+        if (family.variantUnionMembers.length === 0)
             continue;
-        const unionType = subtypeNames.join(' | ');
-        const renamedBase = renameMap.get(info.rawName) ?? sanitizeTypeName(info.rawName);
         schemaTypes.push({
-            name: `${renamedBase}Variant`,
-            definition: `export type ${renamedBase}Variant = ${unionType};`,
+            name: family.variantUnionName,
+            definition: `export type ${family.variantUnionName} = ${family.variantUnionMembers.join(' | ')};`,
         });
-        allSchemaNames.add(`${renamedBase}Variant`);
+        allSchemaNames.add(family.variantUnionName);
     }
     const { operations: analyzedOperations, requestBodySchemas } = analyzePathsDetailed(doc, resolver, strategy);
     const operations = [];
@@ -461,10 +421,9 @@ export function analyze(doc, opts = {}) {
                     return 'StreamResponse';
                 }
                 if (r.schema) {
-                    const result = mapper.mapSchema(r.schema, undefined, 'response').tsType;
-                    const substituted = substituteDiscriminatedType(result, r.schema, discriminatorInfo, renameMap);
-                    r.finishedType = substituted;
-                    return substituted;
+                    const tsType = mapper.mapSchema(r.schema, undefined, 'response').tsType;
+                    r.finishedType = tsType;
+                    return tsType;
                 }
                 r.finishedType = r.isVoid ? 'void' : 'unknown';
                 return r.finishedType;

package/dist/analyzer/discriminator-registry.d.ts

@@ -0,0 +1,108 @@
+import type { RefResolver } from '../parser/ref-resolver.js';
+import type { SchemaObject } from '../types/openapi.js';
+/**
+ * Family-aware discriminator registry (plan D5) — the single knowledge source
+ * for discriminator families the mapper seam will translate through:
+ *
+ * - One record per discriminator family (a component schema declaring
+ *   `discriminator`), keyed by `familyId` (the base's raw component name).
+ * - Variant entries keyed by the FULL `$ref` string (mapping values are exact
+ *   ref strings) plus a derived rename-aware name index.
+ * - Literals are stored PRE-ESCAPED (D8: `'` and `\` only) so the mapper never
+ *   interpolates raw values into string literals.
+ * - Implicit variants (oneOf/anyOf `$ref` members absent from `mapping`) carry
+ *   the RAW last ref segment as their literal (D3 precedence: mapping key >
+ *   own `const` > single-value `enum` > raw segment).
+ *
+ * Field budget (D5): audited — every remaining field has a live consumer in
+ * production (seam / Variant-union emission) or in the registry unit tests.
+ * Rename-aware keying is mandatory: the name index goes through the same
+ * `buildSchemaRenameMap` machinery `analyze()` uses (see the past-bug note at
+ * schema-mapper.ts:75–78 — raw-name keying silently drops literal injection
+ * for renamed subtypes).
+ */
+/** Rename-aware type-name derivation — the exact expression `analyze()` wires
+ * into the mapper's `typeNameGenerator` (`renameMap.get(raw) ?? sanitized`).
+ * Single source of truth so registry name keys can never diverge from the
+ * names the mapper emits for the same `$ref`.
+ */
+export declare function renameAwareTypeName(renameMap: Map<string, string>, rawName: string): string;
+/**
+ * One discriminator variant target inside a family. Consumers: `propertyName`
+ * → literal append + `Omit<M, quoteKey(P)>` key + union wrapper;
+ * `literalValue` → the appended literal (pre-escaped — render as
+ * `'${literalValue}'`); `isNamed` → bare-name vs inline-expansion decision;
+ * `isUnion`/`isNullable` → spine `Omit` fallback decision (D2); `familyId` →
+ * same-family spine detection (D1/D2); `refStr` → identity match at the
+ * ref-translation seam; `typeName` → bare-name emission and the name index.
+ */
+export interface DiscriminatorVariantEntry {
+    /** Discriminator property name declared by the family base (e.g. `'$type'`). */
+    propertyName: string;
+    /** Pre-escaped literal (D8) — the mapping key, own const/enum value, or raw ref segment. No surrounding quotes. */
+    literalValue: string;
+    /** The rename-aware derived name is an emitted component schema (`∈ allSchemaNames`). */
+    isNamed: boolean;
+    /** The target's own resolved schema declares `oneOf`/`anyOf` (spine `Omit` would drop variant props — D2 fallback). */
+    isUnion: boolean;
+    /** The target's own resolved schema is nullable (3.0 `nullable: true` or a 3.1 type array containing `'null'`). */
+    isNullable: boolean;
+    /** Owning family id — the discriminator base's raw component name. */
+    familyId: string;
+    /** The exact `$ref` string that produced this entry (mapping value or oneOf/anyOf member ref). */
+    refStr: string;
+    /** Rename-aware type name for the ref (same derivation as the mapper's `typeNameGenerator`). */
+    typeName: string;
+}
+/**
+ * One discriminator family: a component schema declaring `discriminator`
+ * (`familyId` = its raw component name). Consumers: `baseRefStr` → base-ref
+ * detection at the seam (D1: `$ref` to the base emits `variantUnionName`
+ * outside same-family spines); `variantUnionName` / `variantUnionMembers` →
+ * the always-emit `{Base}Variant` union (D6); `entriesByRef` → family
+ * construction substrate and per-family lookups.
+ */
+export interface DiscriminatorFamily {
+    /** Raw component name of the discriminator base — the family id. */
+    familyId: string;
+    /** Rename-aware emitted type name of the base. */
+    baseTypeName: string;
+    /** Canonical ref of the base component (`#/components/schemas/<encoded key>`). */
+    baseRefStr: string;
+    /** Discriminator property name (`discriminator.propertyName`). */
+    propertyName: string;
+    /** Collision-safe `{Base}Variant` union name (D6 — via the reserved-name machinery). */
+    variantUnionName: string;
+    /** Union member type names (rename-aware, deduped; mapping order, then unmapped oneOf/anyOf refs). */
+    variantUnionMembers: string[];
+    /** Family entries keyed by the FULL `$ref` string (mapping value or oneOf/anyOf member ref). */
+    entriesByRef: Map<string, DiscriminatorVariantEntry>;
+}
+/**
+ * The discriminator registry built once per `analyze()` run. Consumers:
+ * `byRef`/`byName` for variant-target lookup at the ref-translation seam;
+ * `baseRefs` for D1 base-ref translation; `families` for same-family spine
+ * scoping (entry `familyId` → family) and the `{Base}Variant` union emission.
+ * Flat lookups are first-wins across families (spec order) — ambiguous
+ * cross-family targets stay reachable through their per-family maps.
+ */
+export interface DiscriminatorRegistry {
+    /** Families keyed by familyId (raw base component name), in spec order. */
+    families: Map<string, DiscriminatorFamily>;
+    /** Flat lookup: full refStr → entry (first-wins across families). */
+    byRef: Map<string, DiscriminatorVariantEntry>;
+    /** Flat lookup: rename-aware type name → entry (first-wins across families). */
+    byName: Map<string, DiscriminatorVariantEntry>;
+    /** Canonical base refStr → family, for D1 base-ref translation. */
+    baseRefs: Map<string, DiscriminatorFamily>;
+}
+/**
+ * Build the family-aware discriminator registry from the component schemas.
+ *
+ * Inputs must be the SAME `renameMap` / `allSchemaNames` `analyze()` derives
+ * (the rename-aware keying discipline) — pass `buildSchemaRenameMap`'s output
+ * and the emitted-name set, never a parallel sanitization. Pure with respect
+ * to the document: no mutation of the schemas; warnings (D3 mapping-key
+ * conflicts) go to `warnSink`.
+ */
+export declare function buildDiscriminatorRegistry(schemas: Record<string, SchemaObject> | undefined, resolver: RefResolver, renameMap: Map<string, string>, allSchemaNames: ReadonlySet<string>, warnSink?: (message: string) => void): DiscriminatorRegistry;

package/dist/analyzer/discriminator-registry.js

@@ -0,0 +1,209 @@
+import { buildSchemaRenameMap, sanitizeTypeName } from '../utils/generator-helpers.js';
+import { RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
+import { parseJsonPointer } from '../utils/url.js';
+/**
+ * Family-aware discriminator registry (plan D5) — the single knowledge source
+ * for discriminator families the mapper seam will translate through:
+ *
+ * - One record per discriminator family (a component schema declaring
+ *   `discriminator`), keyed by `familyId` (the base's raw component name).
+ * - Variant entries keyed by the FULL `$ref` string (mapping values are exact
+ *   ref strings) plus a derived rename-aware name index.
+ * - Literals are stored PRE-ESCAPED (D8: `'` and `\` only) so the mapper never
+ *   interpolates raw values into string literals.
+ * - Implicit variants (oneOf/anyOf `$ref` members absent from `mapping`) carry
+ *   the RAW last ref segment as their literal (D3 precedence: mapping key >
+ *   own `const` > single-value `enum` > raw segment).
+ *
+ * Field budget (D5): audited — every remaining field has a live consumer in
+ * production (seam / Variant-union emission) or in the registry unit tests.
+ * Rename-aware keying is mandatory: the name index goes through the same
+ * `buildSchemaRenameMap` machinery `analyze()` uses (see the past-bug note at
+ * schema-mapper.ts:75–78 — raw-name keying silently drops literal injection
+ * for renamed subtypes).
+ */
+/** Rename-aware type-name derivation — the exact expression `analyze()` wires
+ * into the mapper's `typeNameGenerator` (`renameMap.get(raw) ?? sanitized`).
+ * Single source of truth so registry name keys can never diverge from the
+ * names the mapper emits for the same `$ref`.
+ */
+export function renameAwareTypeName(renameMap, rawName) {
+    return renameMap.get(rawName) ?? sanitizeTypeName(rawName);
+}
+function isRefObject(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        !Array.isArray(obj) &&
+        '$ref' in obj);
+}
+/** Decode the last segment of a `$ref` string into its raw component key (`~1`/`~0` unescaped). */
+function rawRefSegment(refStr) {
+    const segments = refStr.startsWith('#') ? parseJsonPointer(refStr.slice(1)) : refStr.split('/');
+    return segments[segments.length - 1] ?? refStr;
+}
+/** Encode a component key for embedding in a `#/components/schemas/…` ref string. */
+function encodePointerSegment(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * A discriminator variant's own declared literal on the discriminator
+ * property: `const` first, then a single-value `enum` (D3 steps 2–3).
+ * Returns the string form; multi-value enums and absent props yield nothing.
+ */
+function resolveOwnDiscriminatorLiteral(resolved, propertyName, resolver) {
+    if (!resolved)
+        return undefined;
+    let prop = resolved.properties?.[propertyName];
+    if (prop === undefined)
+        return undefined;
+    if (isRefObject(prop)) {
+        try {
+            prop = resolver.resolveSchema(prop);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (prop.const !== undefined)
+        return { value: String(prop.const), source: 'const' };
+    if (prop.enum !== undefined && prop.enum.length === 1) {
+        return { value: String(prop.enum[0]), source: 'enum' };
+    }
+    return undefined;
+}
+/** Resolve a mapping/oneOf ref target for flag facts; unresolvable refs degrade to undefined (mapper-style try/catch). */
+function resolveTargetSchema(resolver, refStr) {
+    try {
+        return resolver.resolveSchema({ $ref: refStr });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the family-aware discriminator registry from the component schemas.
+ *
+ * Inputs must be the SAME `renameMap` / `allSchemaNames` `analyze()` derives
+ * (the rename-aware keying discipline) — pass `buildSchemaRenameMap`'s output
+ * and the emitted-name set, never a parallel sanitization. Pure with respect
+ * to the document: no mutation of the schemas; warnings (D3 mapping-key
+ * conflicts) go to `warnSink`.
+ */
+export function buildDiscriminatorRegistry(schemas, resolver, renameMap, allSchemaNames, warnSink) {
+    const warn = warnSink ??
+        ((message) => {
+            process.stderr.write(message);
+        });
+    const registry = {
+        families: new Map(),
+        byRef: new Map(),
+        byName: new Map(),
+        baseRefs: new Map(),
+    };
+    if (!schemas)
+        return registry;
+    // Pass 1 — discover families; per family, register mapping entries first
+    // (D3: mapping key wins), then implicit oneOf/anyOf variants absent from
+    // the mapping (literal = own const > single-value enum > RAW ref segment).
+    for (const [name, schema] of Object.entries(schemas)) {
+        const resolved = resolver.resolve(schema);
+        const disc = resolved.discriminator;
+        if (!disc)
+            continue;
+        const familyId = name;
+        const family = {
+            familyId,
+            baseTypeName: renameAwareTypeName(renameMap, name),
+            baseRefStr: `#/components/schemas/${encodePointerSegment(name)}`,
+            propertyName: disc.propertyName,
+            variantUnionName: '',
+            variantUnionMembers: [],
+            entriesByRef: new Map(),
+        };
+        const mappedRefStrs = new Set();
+        if (disc.mapping) {
+            for (const [mappingKey, refStr] of Object.entries(disc.mapping)) {
+                if (mappedRefStrs.has(refStr))
+                    continue; // two keys → same target: first key wins
+                mappedRefStrs.add(refStr);
+                const target = resolveTargetSchema(resolver, refStr);
+                const own = resolveOwnDiscriminatorLiteral(target, disc.propertyName, resolver);
+                if (own !== undefined && own.value !== mappingKey) {
+                    warn(`Warning: Discriminator mapping key "${mappingKey}" for "${refStr}" conflicts with its own declared ${own.source} literal "${own.value}"; the mapping key wins.\n`);
+                }
+                const rawSegment = rawRefSegment(refStr);
+                const entry = {
+                    propertyName: disc.propertyName,
+                    literalValue: escapeStringLiteral(mappingKey),
+                    isNamed: allSchemaNames.has(renameAwareTypeName(renameMap, rawSegment)),
+                    isUnion: (target?.oneOf?.length ?? 0) > 0 || (target?.anyOf?.length ?? 0) > 0,
+                    isNullable: target?.nullable === true ||
+                        (Array.isArray(target?.type) ? target.type.includes('null') : false),
+                    familyId,
+                    refStr,
+                    typeName: renameAwareTypeName(renameMap, rawSegment),
+                };
+                family.entriesByRef.set(refStr, entry);
+            }
+        }
+        const implicitRefs = [];
+        for (const member of [...(resolved.oneOf ?? []), ...(resolved.anyOf ?? [])]) {
+            if (isRefObject(member))
+                implicitRefs.push(member.$ref);
+        }
+        for (const refStr of implicitRefs) {
+            if (mappedRefStrs.has(refStr))
+                continue; // already registered via mapping
+            const target = resolveTargetSchema(resolver, refStr);
+            const own = resolveOwnDiscriminatorLiteral(target, disc.propertyName, resolver);
+            const rawSegment = rawRefSegment(refStr);
+            const entry = {
+                propertyName: disc.propertyName,
+                // D3 fallback chain for unmapped variants: own const > single-value
+                // enum > RAW last ref segment (the runtime value, NOT the sanitized
+                // type name).
+                literalValue: escapeStringLiteral(own?.value ?? rawSegment),
+                isNamed: allSchemaNames.has(renameAwareTypeName(renameMap, rawSegment)),
+                isUnion: (target?.oneOf?.length ?? 0) > 0 || (target?.anyOf?.length ?? 0) > 0,
+                isNullable: target?.nullable === true ||
+                    (Array.isArray(target?.type) ? target.type.includes('null') : false),
+                familyId,
+                refStr,
+                typeName: renameAwareTypeName(renameMap, rawSegment),
+            };
+            family.entriesByRef.set(refStr, entry);
+        }
+        registry.families.set(familyId, family);
+    }
+    // Pass 2 — flat lookups + per-family name index + union members
+    // (mapping order, then unmapped oneOf/anyOf refs; deduped by refStr and
+    // by typeName — alias refs to one emitted name collapse).
+    for (const family of registry.families.values()) {
+        const memberNames = [];
+        const seenNames = new Set();
+        for (const [refStr, entry] of family.entriesByRef) {
+            if (!registry.byRef.has(refStr))
+                registry.byRef.set(refStr, entry);
+            if (!registry.byName.has(entry.typeName))
+                registry.byName.set(entry.typeName, entry);
+            if (!seenNames.has(entry.typeName)) {
+                seenNames.add(entry.typeName);
+                memberNames.push(entry.typeName);
+            }
+        }
+        family.variantUnionMembers = memberNames;
+        registry.baseRefs.set(family.baseRefStr, family);
+    }
+    // Pass 3 — collision-safe `{Base}Variant` union names (D6): candidates go
+    // through the SAME reserved-name machinery as schemas, seeded with every
+    // emitted schema name, so a user schema literally named `ThingVariant`
+    // forces the generated union to `ThingVariantModel` (no duplicate export).
+    const unionCandidates = [...registry.families.values()].map((f) => `${f.baseTypeName}Variant`);
+    const unionRenames = buildSchemaRenameMap(unionCandidates, new Set([...RESERVED_TYPE_NAMES, ...allSchemaNames]));
+    for (const family of registry.families.values()) {
+        const candidate = `${family.baseTypeName}Variant`;
+        family.variantUnionName = unionRenames.get(candidate) ?? candidate;
+    }
+    return registry;
+}

package/dist/analyzer/schema-mapper.d.ts

@@ -1,10 +1,32 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import type { TypeMappingResult } from '../types/contracts.js';
 import type { SchemaObject, ReferenceObject } from '../types/openapi.js';
+import type { DiscriminatorRegistry } from './discriminator-registry.js';
 /**
  * Callback to customize how $ref strings are converted to TypeScript type names.
  */
 export type TypeNameGenerator = (refString: string) => string;
+/**
+ * Optional construction dependencies for {@link SchemaMapper}. Every field is
+ * optional and defaults exactly as the previous positional constructor
+ * parameters did.
+ */
+export interface SchemaMapperOptions {
+    typeNameGenerator?: TypeNameGenerator;
+    discriminatorTargets?: Map<string, {
+        propertyName: string;
+        literalValue: string;
+    }>;
+    emittedNames?: Set<string>;
+    warnSink?: (message: string) => void;
+    discriminatorRegistry?: DiscriminatorRegistry;
+    /**
+     * Effective OpenAPI dialect. Omitted is treated as '3.1' (the nullable
+     * deprecation warning fires). Pass '3.0' to silence it — 'nullable' is the
+     * correct mechanism in 3.0.
+     */
+    effectiveVersion?: '3.0' | '3.1';
+}
 /**
  * SchemaMapper converts OpenAPI 3.1 Schema Objects to TypeScript type strings.
  *
@@ -15,14 +37,13 @@ export declare class SchemaMapper {
     private readonly resolver;
     private readonly typeNameGenerator;
     private readonly discriminatorTargets;
-    private readonly reservedNames;
+    private readonly emittedNames;
+    private readonly discriminatorRegistry;
     private readonly brandedTypes;
     private nullableWarned;
     private readonly warnSink;
-    constructor(resolver: RefResolver, typeNameGenerator?: TypeNameGenerator, discriminatorTargets?: Map<string, {
-        propertyName: string;
-        literalValue: string;
-    }>, reservedNames?: Set<string>, warnSink?: (message: string) => void);
+    private readonly effectiveVersion;
+    constructor(resolver: RefResolver, opts?: SchemaMapperOptions);
     getBrandedTypes(): Map<string, {
         name: string;
         format: string;
@@ -37,12 +58,52 @@ export declare class SchemaMapper {
      * @returns TypeMappingResult with tsType string and imports array
      */
     mapSchema(schema: SchemaObject | ReferenceObject, name?: string, context?: 'request' | 'response'): TypeMappingResult;
+    /**
+     * Append the discriminator literal intersection exactly ONCE (site 2),
+     * parenthesizing a top-level union so `X | null & {...}` cannot bind the
+     * literal to the last union member only (D9).
+     */
+    private appendDiscriminatorLiteral;
     private getBrandTypeName;
     private mapInternal;
+    /**
+     * The single ref-translation seam (site 1). When the mapper carries a
+     * discriminator registry, EVERY `$ref` resolves through here:
+     *
+     * - a discriminator BASE becomes `{Base}Variant` at all sites except
+     *   inside a same-family member's own definition spine, where it stays
+     *   the bare base name (structural inheritance, no circularity — D1);
+     * - a same-family mapping target inside a spine becomes `Omit<M, 'P'>`,
+     *   falling back to inline expansion WITHOUT the literal when M is a
+     *   union, nullable, unnamed or non-object (D2/D4);
+     * - a mapping target at any other site is its bare name — the literal is
+     *   injected exactly once, at the target's own named definition.
+     */
+    private translateRefThroughSeam;
+    /**
+     * D2/D4 spine rule for a same-family `$ref`. `Omit<M, 'P'>` strips the
+     * sibling's own literal so the appender can re-add ours; the inline-strip
+     * fallback covers the cases where `Omit` would silently drop data
+     * (union target: `Omit<A|B,K>` drops variant props; nullable target:
+     * `Omit<M|null,K>` collapses to `{}`; unnamed/non-object target).
+     */
+    private mapSameFamilySpineRef;
+    /** Normalize a `#/components/schemas/…` ref to its canonically-encoded form (`a/b` ↔ `a~1b`). */
+    private canonicalSchemasRef;
+    private tryResolveRef;
+    private isObjectIshSchema;
     private resolveDiscriminatorInfo;
     private mapEnumValues;
     private mapCombinator;
     private mapDiscriminatedUnion;
+    /**
+     * D3 literal precedence for registry-mode wrapper literals (inline variant
+     * schemas and foreign refs): mapping key > own `const` on the discriminant
+     * property > single-value `enum` > RAW last ref segment (the runtime
+     * value, NOT the sanitized type name). Values are escaped for a
+     * single-quoted TS string.
+     */
+    private resolveRegistryDiscriminantValue;
     private resolveDiscriminantValue;
     private mapArray;
     /**