zod-nest 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -28,6 +28,40 @@ interface OverrideContext {
 }
 type Override = (ctx: OverrideContext) => void;
 
+/**
+ * Composition layer — emits OpenAPI `allOf` for schemas derived via `extend`.
+ *
+ * **EXPERIMENTAL (v0.2)**: output shape may change as edge cases surface.
+ */
+
+/**
+ * Lineage record for a composition-derived schema. Read by the override to
+ * emit `allOf` instead of a flat body.
+ *
+ * @experimental v0.2 — shape may change.
+ */
+interface LineageEntry {
+    readonly op: 'extend';
+    readonly parent: z.ZodObject;
+}
+/**
+ * Wraps a derived `z.ZodObject` and records the parent → child link so
+ * emission rewrites the body to `allOf: [{ $ref: <parent> }, <delta>]`.
+ *
+ * @experimental v0.2 — output shape may change as the surface stabilizes.
+ *
+ * @example
+ *   const Base  = z.object({ id: z.string() }).meta({ id: 'Base' });
+ *   const Child = extend(Base, (s) => s.extend({ role: z.string() }).meta({ id: 'Child' }));
+ */
+declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P, build: (p: P) => S) => S;
+/**
+ * Read the lineage entry for a composition-derived schema, or `undefined`.
+ *
+ * @experimental v0.2 — `LineageEntry` shape may change.
+ */
+declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
+
 interface ZodNestRegistry {
     readonly zodRegistry: typeof z.globalRegistry;
     register(schema: z.ZodType, id: string): void;
@@ -470,4 +504,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };

package/dist/index.d.ts

@@ -28,6 +28,40 @@ interface OverrideContext {
 }
 type Override = (ctx: OverrideContext) => void;
 
+/**
+ * Composition layer — emits OpenAPI `allOf` for schemas derived via `extend`.
+ *
+ * **EXPERIMENTAL (v0.2)**: output shape may change as edge cases surface.
+ */
+
+/**
+ * Lineage record for a composition-derived schema. Read by the override to
+ * emit `allOf` instead of a flat body.
+ *
+ * @experimental v0.2 — shape may change.
+ */
+interface LineageEntry {
+    readonly op: 'extend';
+    readonly parent: z.ZodObject;
+}
+/**
+ * Wraps a derived `z.ZodObject` and records the parent → child link so
+ * emission rewrites the body to `allOf: [{ $ref: <parent> }, <delta>]`.
+ *
+ * @experimental v0.2 — output shape may change as the surface stabilizes.
+ *
+ * @example
+ *   const Base  = z.object({ id: z.string() }).meta({ id: 'Base' });
+ *   const Child = extend(Base, (s) => s.extend({ role: z.string() }).meta({ id: 'Child' }));
+ */
+declare const extend: <P extends z.ZodObject, S extends z.ZodObject>(parent: P, build: (p: P) => S) => S;
+/**
+ * Read the lineage entry for a composition-derived schema, or `undefined`.
+ *
+ * @experimental v0.2 — `LineageEntry` shape may change.
+ */
+declare const getLineage: (schema: z.ZodType) => LineageEntry | undefined;
+
 interface ZodNestRegistry {
     readonly zodRegistry: typeof z.globalRegistry;
     register(schema: z.ZodType, id: string): void;
@@ -470,4 +504,4 @@ declare class ZodNestDocumentError extends ZodNestError {
     constructor(code: ZodNestDocumentErrorCode, message: string, details?: Record<string, unknown>);
 }
 
-export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };
+export { type ApplyZodNestOptions, COMPONENTS_SCHEMAS_PREFIX, type CreateSerializationException, type CreateValidationException, type CreateZodDtoOptions, DEFAULT_MAX_LOGGED_VALUE_BYTES, DEFAULT_REDACT_KEYS, type Io, type LineageEntry, type NormalizedZodNestOptions, type Override, type OverrideContext, type ResponseVariant, type ResponseVariantKind, type SchemaObject, type ToOpenApiOptions, type ToOpenApiResult, ZOD_DTO_SYMBOL, ZOD_NEST_DTO_EXTENSION, ZOD_NEST_ERROR_DUPLICATE_ID, ZOD_NEST_ERROR_EXTENSION, ZOD_NEST_OPTIONS, ZOD_RESPONSES_METADATA_KEY, type ZodDto, type ZodDtoMarker, ZodNestDocumentError, type ZodNestDocumentErrorCode, ZodNestError, ZodNestModule, type ZodNestModuleOptions, type ZodNestRegistry, ZodNestUnrepresentableError, ZodResponse, type ZodResponseDescription, type ZodResponseOptions, type ZodResponseType, ZodSerializationException, ZodSerializerInterceptor, ZodValidationException, ZodValidationPipe, type ZodValidationPipeArg, type ZodValidationPipeOptions, applyZodNest, createRegistry, createZodDto, defaultRegistry, defaultStatusFor, extend, getLineage, isZodDto, isZodDtoMarker, makeZodDtoMarker, resolveEffectiveStatus, toOpenApi };

package/dist/index.js

@@ -24,9 +24,73 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 
 // src/schema/constants.ts
 var COMPONENTS_SCHEMAS_PREFIX = "#/components/schemas/";
+var DEFS_PREFIX = "#/$defs/";
 var ZOD_NEST_ERROR_EXTENSION = "x-zod-nest-error";
 var ZOD_NEST_ERROR_DUPLICATE_ID = "duplicate-id";
 var ZOD_NEST_DTO_EXTENSION = "x-zod-nest-dto";
+var lineageMap = /* @__PURE__ */ new WeakMap();
+var propsMap = /* @__PURE__ */ new WeakMap();
+var OPTIONAL_WRAPPER_TYPES = /* @__PURE__ */ new Set(["optional", "default"]);
+var isOptionalProp = (propSchema) => OPTIONAL_WRAPPER_TYPES.has(propSchema._zod.def.type);
+var computeShapeKeys = (schema) => {
+  const { shape } = schema;
+  const properties = Object.keys(shape);
+  const required = properties.filter((key) => {
+    const propSchema = shape[key];
+    return propSchema !== void 0 && !isOptionalProp(propSchema);
+  });
+  return { properties, required };
+};
+var extend = (parent, build) => {
+  const result = build(parent);
+  lineageMap.set(result, { op: "extend", parent });
+  if (!propsMap.has(parent)) {
+    propsMap.set(parent, computeShapeKeys(parent));
+  }
+  return result;
+};
+var getLineage = (schema) => lineageMap.get(schema);
+var DEFAULT_BUILD_REF = (id) => `${DEFS_PREFIX}${id}`;
+var createCompositionOverride = (opts) => {
+  const { buildRef } = opts;
+  return (ctx) => {
+    const { jsonSchema, zodSchema } = ctx;
+    const entry = lineageMap.get(zodSchema);
+    if (entry === void 0) {
+      return;
+    }
+    const parentCache = propsMap.get(entry.parent);
+    if (parentCache === void 0) {
+      return;
+    }
+    const parentId = zod.z.globalRegistry.get(entry.parent)?.id;
+    if (parentId === void 0) {
+      return;
+    }
+    const childProps = jsonSchema.properties ?? {};
+    const childRequired = jsonSchema.required ?? [];
+    const parentPropSet = new Set(parentCache.properties);
+    const parentReqSet = new Set(parentCache.required);
+    const deltaProps = {};
+    for (const [key, value] of Object.entries(childProps)) {
+      if (parentPropSet.has(key)) {
+        continue;
+      }
+      deltaProps[key] = value;
+    }
+    const deltaRequired = childRequired.filter((key) => !parentReqSet.has(key));
+    const delta = { type: "object", properties: deltaProps };
+    if (deltaRequired.length > 0) {
+      delta.required = deltaRequired;
+    }
+    delete jsonSchema.type;
+    delete jsonSchema.properties;
+    delete jsonSchema.required;
+    delete jsonSchema.additionalProperties;
+    jsonSchema.allOf = [{ $ref: buildRef(parentId) }, delta];
+    jsonSchema.unevaluatedProperties = false;
+  };
+};
 
 // src/schema/errors.ts
 var ZodNestError = class extends Error {
@@ -55,7 +119,7 @@ var formatPath = (path) => {
 };
 
 // src/schema/override.ts
-var builtInOverride = ({ zodSchema, jsonSchema }) => {
+var primitiveOverride = ({ zodSchema, jsonSchema }) => {
   const type = zodSchema._zod.def.type;
   if (type === "bigint") {
     jsonSchema.type = "integer";
@@ -104,7 +168,6 @@ var combine = (...overrides) => {
 };
 
 // src/schema/post-process.ts
-var DEFS_PREFIX = "#/$defs/";
 var rewriteRefs = (node, selfRef) => {
   if (Array.isArray(node)) {
     for (const item of node) {
@@ -147,7 +210,10 @@ var postProcess = (raw) => {
 // src/schema/engine.ts
 var buildToJsonSchemaOptions = (params) => {
   const strict = params.strict ?? true;
-  const merged = combine(builtInOverride, params.override);
+  const compositionOverride = createCompositionOverride({
+    buildRef: params.uri ?? DEFAULT_BUILD_REF
+  });
+  const merged = combine(primitiveOverride, compositionOverride, params.override);
   const unrepresentableHits = [];
   const wrapped = (ctx) => {
     merged(ctx);
@@ -752,21 +818,33 @@ var runPass = (opts, io, knownIds) => {
     io,
     override: opts.override,
     strict: opts.strict,
-    reused: "ref",
+    reused: "inline",
     uri: URI
   });
   const raw = zod.z.toJSONSchema(opts.registry.zodRegistry, built.options);
   built.consumeUnrepresentable();
   const filtered = /* @__PURE__ */ new Map();
-  const schemas = raw.schemas ?? {};
   for (const id of knownIds) {
-    if (Object.prototype.hasOwnProperty.call(schemas, id)) {
-      filtered.set(id, schemas[id]);
+    if (Object.prototype.hasOwnProperty.call(raw.schemas, id)) {
+      filtered.set(id, raw.schemas[id]);
     }
   }
   return filtered;
 };
-var REF_PREFIX = "#/components/schemas/";
+
+// src/document/http-methods.ts
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+
+// src/document/collect-usage.ts
 var collectUsage = (doc, app) => {
   const classToDtoId = buildClassToDtoIdMap(doc);
   const inputExposedIds = collectInputExposedIds(doc, classToDtoId);
@@ -812,16 +890,6 @@ var collectInputExposedIds = (doc, classToDtoId) => {
   }
   return ids;
 };
-var HTTP_METHODS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace"
-];
 var operationsOf = (pathItem) => {
   const out = [];
   for (const method of HTTP_METHODS) {
@@ -865,10 +933,10 @@ var collectRefFromSchema = (schema, classToDtoId, ids) => {
     return;
   }
   const ref = schema.$ref;
-  if (typeof ref !== "string" || !ref.startsWith(REF_PREFIX)) {
+  if (typeof ref !== "string" || !ref.startsWith(COMPONENTS_SCHEMAS_PREFIX)) {
     return;
   }
-  const className = ref.slice(REF_PREFIX.length);
+  const className = ref.slice(COMPONENTS_SCHEMAS_PREFIX.length);
   const dtoId = classToDtoId.get(className);
   if (dtoId !== void 0) {
     ids.add(dtoId);
@@ -883,9 +951,6 @@ var collectOutputExposedIds = (app) => {
       continue;
     }
     const proto = Object.getPrototypeOf(instance);
-    if (proto === null) {
-      continue;
-    }
     for (const methodName of Object.getOwnPropertyNames(proto)) {
       if (methodName === "constructor") {
         continue;
@@ -957,15 +1022,14 @@ var walkRefs = (node, visit) => {
 };
 
 // src/document/dangling-refs.ts
-var SCHEMA_PREFIX = "#/components/schemas/";
 var assertNoDanglingRefs = (doc) => {
   const schemas = doc.components?.schemas ?? {};
   const dangling = [];
   walkRefs(doc, (ref) => {
-    if (!ref.startsWith(SCHEMA_PREFIX)) {
+    if (!ref.startsWith(COMPONENTS_SCHEMAS_PREFIX)) {
       return void 0;
     }
-    const target = ref.slice(SCHEMA_PREFIX.length);
+    const target = ref.slice(COMPONENTS_SCHEMAS_PREFIX.length);
     if (!(target in schemas)) {
       dangling.push(ref);
     }
@@ -1055,7 +1119,8 @@ var isMarkerPlaceholder = (value) => {
   if (properties === null || typeof properties !== "object") {
     return false;
   }
-  return "x-zod-nest-dto" in properties;
+  const marker = properties[ZOD_NEST_DTO_EXTENSION];
+  return isZodDtoMarker(marker);
 };
 var canonicalEqual = (a, b) => {
   if (a === b) {
@@ -1085,31 +1150,20 @@ var decorateIfPresent = (schemas, key) => {
 };
 
 // src/document/rewrite-refs.ts
-var SCHEMA_PREFIX2 = "#/components/schemas/";
 var OUTPUT_SUFFIX2 = "Output";
-var HTTP_METHODS2 = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace"
-];
 var rewriteRefs2 = (params) => {
   const { doc, renames, divergentOutputIds } = params;
   if (renames.size > 0) {
     walkRefs(doc, (ref) => {
-      if (!ref.startsWith(SCHEMA_PREFIX2)) {
+      if (!ref.startsWith(COMPONENTS_SCHEMAS_PREFIX)) {
         return void 0;
       }
-      const target = ref.slice(SCHEMA_PREFIX2.length);
+      const target = ref.slice(COMPONENTS_SCHEMAS_PREFIX.length);
       const renamed = renames.get(target);
       if (renamed === void 0) {
         return void 0;
       }
-      return `${SCHEMA_PREFIX2}${renamed}`;
+      return `${COMPONENTS_SCHEMAS_PREFIX}${renamed}`;
     });
   }
   if (divergentOutputIds.size === 0) {
@@ -1124,7 +1178,7 @@ var rewriteRefs2 = (params) => {
   }
 };
 var rewriteResponseSubtree = (pathItem, divergentOutputIds) => {
-  for (const method of HTTP_METHODS2) {
+  for (const method of HTTP_METHODS) {
     const op = pathItem[method];
     if (op === null || typeof op !== "object") {
       continue;
@@ -1134,14 +1188,14 @@ var rewriteResponseSubtree = (pathItem, divergentOutputIds) => {
       continue;
     }
     walkRefs(responses, (ref) => {
-      if (!ref.startsWith(SCHEMA_PREFIX2)) {
+      if (!ref.startsWith(COMPONENTS_SCHEMAS_PREFIX)) {
         return void 0;
       }
-      const target = ref.slice(SCHEMA_PREFIX2.length);
+      const target = ref.slice(COMPONENTS_SCHEMAS_PREFIX.length);
       if (!divergentOutputIds.has(target)) {
         return void 0;
       }
-      return `${SCHEMA_PREFIX2}${target}${OUTPUT_SUFFIX2}`;
+      return `${COMPONENTS_SCHEMAS_PREFIX}${target}${OUTPUT_SUFFIX2}`;
     });
   }
 };
@@ -1217,6 +1271,8 @@ exports.createRegistry = createRegistry;
 exports.createZodDto = createZodDto;
 exports.defaultRegistry = defaultRegistry;
 exports.defaultStatusFor = defaultStatusFor;
+exports.extend = extend;
+exports.getLineage = getLineage;
 exports.isZodDto = isZodDto;
 exports.isZodDtoMarker = isZodDtoMarker;
 exports.makeZodDtoMarker = makeZodDtoMarker;