zod-nest 2.0.1 → 2.1.1

package/dist/index.d.mts

@@ -118,6 +118,15 @@ declare const registerSchema: (schema: z.ZodType, registry?: ZodNestRegistry, op
 interface LineageEntry {
     readonly op: 'extend';
     readonly parent: z.ZodObject;
+    /**
+     * Keys the child redeclared with a *different* schema than the parent's
+     * (e.g. narrowing `type: SomeEnum` to `type: z.literal('A')`). Computed by
+     * reference comparison at `extend()` time — Zod's `.extend()` keeps the same
+     * shape reference for untouched keys and assigns a fresh one for overrides.
+     * The composition override keeps these in the delta instead of dropping them
+     * as parent-owned, so the narrowing survives in the emitted `allOf`.
+     */
+    readonly overriddenKeys: ReadonlySet<string>;
 }
 /**
  * Wraps a derived `z.ZodObject` and records the parent → child link so
@@ -831,6 +840,18 @@ interface ApplyZodNestOptions {
      * `@ZodQuery({ ref })` override takes precedence over this preference.
      */
     queryParamStyle?: QueryParamStyle;
+    /**
+     * Copy each named component's `title` (when set via `.meta({ title })`) onto
+     * every `$ref` that targets it, as a sibling: `{ $ref, title }` (default
+     * `true`).
+     *
+     * OpenAPI 3.1 allows siblings next to `$ref`, and Swagger UI's 3.1 renderer
+     * inlines referenced schemas without showing their component name
+     * (swagger-api/swagger-ui#9540); the sibling `title` gives the renderer (and
+     * other 3.1-aware tools) a name to display. The annotation is semantically
+     * inert. Set `false` to emit bare `$ref`s.
+     */
+    refTitles?: boolean;
 }
 /**
  * Post-processor over the OpenAPI document emitted by
@@ -856,6 +877,9 @@ interface ApplyZodNestOptions {
  *   transitive `$ref` deps, plus any `{ expose: true }` opt-ins) are kept —
  *   unreferenced registered schemas are pruned. Exposure is document-scoped, so
  *   several documents sharing one registry each carry only what they use.
+ * - Each named component's `title` is copied onto every `$ref` that targets it
+ *   as a `{ $ref, title }` sibling (`applyRefTitles`, unless `refTitles: false`)
+ *   so Swagger UI's 3.1 renderer surfaces the component name. Inert annotation.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
  * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
  *   guarantees the version string matches the emitted body regardless of the

package/dist/index.d.ts

@@ -118,6 +118,15 @@ declare const registerSchema: (schema: z.ZodType, registry?: ZodNestRegistry, op
 interface LineageEntry {
     readonly op: 'extend';
     readonly parent: z.ZodObject;
+    /**
+     * Keys the child redeclared with a *different* schema than the parent's
+     * (e.g. narrowing `type: SomeEnum` to `type: z.literal('A')`). Computed by
+     * reference comparison at `extend()` time — Zod's `.extend()` keeps the same
+     * shape reference for untouched keys and assigns a fresh one for overrides.
+     * The composition override keeps these in the delta instead of dropping them
+     * as parent-owned, so the narrowing survives in the emitted `allOf`.
+     */
+    readonly overriddenKeys: ReadonlySet<string>;
 }
 /**
  * Wraps a derived `z.ZodObject` and records the parent → child link so
@@ -831,6 +840,18 @@ interface ApplyZodNestOptions {
      * `@ZodQuery({ ref })` override takes precedence over this preference.
      */
     queryParamStyle?: QueryParamStyle;
+    /**
+     * Copy each named component's `title` (when set via `.meta({ title })`) onto
+     * every `$ref` that targets it, as a sibling: `{ $ref, title }` (default
+     * `true`).
+     *
+     * OpenAPI 3.1 allows siblings next to `$ref`, and Swagger UI's 3.1 renderer
+     * inlines referenced schemas without showing their component name
+     * (swagger-api/swagger-ui#9540); the sibling `title` gives the renderer (and
+     * other 3.1-aware tools) a name to display. The annotation is semantically
+     * inert. Set `false` to emit bare `$ref`s.
+     */
+    refTitles?: boolean;
 }
 /**
  * Post-processor over the OpenAPI document emitted by
@@ -856,6 +877,9 @@ interface ApplyZodNestOptions {
  *   transitive `$ref` deps, plus any `{ expose: true }` opt-ins) are kept —
  *   unreferenced registered schemas are pruned. Exposure is document-scoped, so
  *   several documents sharing one registry each carry only what they use.
+ * - Each named component's `title` is copied onto every `$ref` that targets it
+ *   as a `{ $ref, title }` sibling (`applyRefTitles`, unless `refTitles: false`)
+ *   so Swagger UI's 3.1 renderer surfaces the component name. Inert annotation.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
  * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
  *   guarantees the version string matches the emitted body regardless of the

package/dist/index.js

@@ -246,11 +246,22 @@ var computeShapeKeys = /* @__PURE__ */ __name((schema) => {
     required
   };
 }, "computeShapeKeys");
+var computeOverriddenKeys = /* @__PURE__ */ __name((parent, child) => {
+  const overriddenKeys = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(child.shape)) {
+    const parentProp = parent.shape[key];
+    if (parentProp !== void 0 && parentProp !== child.shape[key]) {
+      overriddenKeys.add(key);
+    }
+  }
+  return overriddenKeys;
+}, "computeOverriddenKeys");
 var extend = /* @__PURE__ */ __name((parent, build) => {
   const result = build(parent);
   lineageMap.set(result, {
     op: "extend",
-    parent
+    parent,
+    overriddenKeys: computeOverriddenKeys(parent, result)
   });
   if (!propsMap.has(parent)) {
     propsMap.set(parent, computeShapeKeys(parent));
@@ -284,7 +295,7 @@ var createCompositionOverride = /* @__PURE__ */ __name((opts) => {
     const parentReqSet = new Set(parentCache.required);
     const deltaProps = {};
     for (const [key, value] of Object.entries(childProps)) {
-      if (parentPropSet.has(key)) {
+      if (parentPropSet.has(key) && !entry.overriddenKeys.has(key)) {
         continue;
       }
       deltaProps[key] = value;
@@ -1334,7 +1345,7 @@ var ZodResponse = /* @__PURE__ */ __name((opts) => {
 }, "ZodResponse");
 
 // src/decorators/internal/zod-schema-ref.ts
-var resolveSchemaRef = /* @__PURE__ */ __name((schema, options) => {
+function resolveSchemaRef(schema, options) {
   const registry = options?.registry ?? defaultRegistry;
   const id = registerSchema(schema, registry, {
     id: options?.id
@@ -1371,7 +1382,8 @@ var resolveSchemaRef = /* @__PURE__ */ __name((schema, options) => {
     kind: "inline",
     schema: body
   };
-}, "resolveSchemaRef");
+}
+__name(resolveSchemaRef, "resolveSchemaRef");
 
 // src/decorators/internal/zod-param-expand.ts
 var isZodObject = /* @__PURE__ */ __name((schema) => schema._zod.def.type === "object", "isZodObject");
@@ -1505,12 +1517,11 @@ var resolveBodySchema = /* @__PURE__ */ __name((schema, options) => {
   if (options?.flatten === true) {
     return flattenObjectIntersection(schema, options.registry ?? defaultRegistry, "@ZodBody");
   }
-  const resolution = resolveSchemaRef(schema, {
+  return resolveSchemaRef(schema, {
     id: options?.id,
     registry: options?.registry,
     deferAnonInline: true
-  });
-  return resolution.kind === "ref" ? resolution.ref : resolution.schema;
+  }).ref;
 }, "resolveBodySchema");
 
 // src/decorators/internal/query-marker.ts
@@ -2382,6 +2393,47 @@ var decorateIfPresent = /* @__PURE__ */ __name((schemas, key) => {
   };
 }, "decorateIfPresent");
 
+// src/document/ref-titles.ts
+var applyRefTitles = /* @__PURE__ */ __name((doc) => {
+  const schemas = doc.components?.schemas;
+  if (schemas === void 0) {
+    return;
+  }
+  const titleById = /* @__PURE__ */ new Map();
+  for (const [id, body] of Object.entries(schemas)) {
+    if (isPlainRecord5(body) && typeof body.title === "string" && body.title !== "") {
+      titleById.set(id, body.title);
+    }
+  }
+  if (titleById.size === 0) {
+    return;
+  }
+  addRefTitles(doc.paths, titleById);
+  addRefTitles(schemas, titleById);
+}, "applyRefTitles");
+var isPlainRecord5 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var addRefTitles = /* @__PURE__ */ __name((node, titleById) => {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      addRefTitles(item, titleById);
+    }
+    return;
+  }
+  if (!isPlainRecord5(node)) {
+    return;
+  }
+  const ref = node.$ref;
+  if (typeof ref === "string" && ref.startsWith(COMPONENTS_SCHEMAS_PREFIX) && node.title === void 0) {
+    const title = titleById.get(ref.slice(COMPONENTS_SCHEMAS_PREFIX.length));
+    if (title !== void 0) {
+      node.title = title;
+    }
+  }
+  for (const value of Object.values(node)) {
+    addRefTitles(value, titleById);
+  }
+}, "addRefTitles");
+
 // src/document/rewrite-refs.ts
 var rewriteRefs2 = /* @__PURE__ */ __name((params) => {
   const { doc, renames, divergentOutputIds } = params;
@@ -2527,6 +2579,9 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts = {}) => {
     doc,
     registry
   });
+  if (opts.refTitles !== false) {
+    applyRefTitles(doc);
+  }
   assertNoDanglingRefs({
     doc,
     collected: extended