zod-nest 0.6.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,7 +818,7 @@ 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);
@@ -1205,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;