@wildo-ai/zod-decorators 1.1.11 → 1.1.13

package/dist/esm/zod-utils.shared.js

@@ -116,8 +116,9 @@ export function unwrapSchema(schema) {
  * - nested PLAIN object fields, recursively, through `optional` / `nullable` wrappers only. An object
  *   nested inside a union, discriminated union, record, intersection, pipe/transform, `readonly` or `lazy`
  *   is NOT peeled and keeps re-materialising its defaults — narrower than it could be, never wrong;
- * - an object carrying its own refinement is NOT peeled: a `.refine()` / `.superRefine()` may read a
- *   defaulted key, and would see `undefined` (or throw) once that default stopped applying;
+ * - an object carrying its own refinement is NOT peeled, and neither is one under a wrapper or a default
+ *   that carries one: a `.refine()` / `.superRefine()` may read a defaulted key, and would see `undefined`
+ *   (or throw) once that default stopped applying (#3342);
  * - a nested key WITH a default becomes optional without it; a nested key WITHOUT one keeps its declared
  *   optionality — a replaced nested object must still carry what it requires;
  * - ARRAYS are left alone: an array element is sent whole, and its defaults describe a new element;
@@ -127,6 +128,8 @@ export function unwrapSchema(schema) {
  *   never mutated, so the source schema is untouched.
  */
 function withoutNestedObjectDefaults(schema) {
+    if (ownChecks(schema).length > 0)
+        return schema;
     const type = getZodType(schema);
     if (type === 'optional' || type === 'nullable') {
         const inner = getZodDefSchemaProperty(schema, 'innerType');
@@ -140,16 +143,13 @@ function withoutNestedObjectDefaults(schema) {
     if (type !== 'object')
         return schema;
     const def = schema._zod.def;
-    if (Array.isArray(def.checks) && def.checks.length > 0)
-        return schema;
     const shape = schema.shape;
     const nextShape = {};
     let changed = false;
     for (const [key, field] of Object.entries(shape)) {
         let next;
         if (isZodDefault(field)) {
-            const peeled = getZodDefSchemaProperty(field, 'innerType');
-            next = peeled ? copySchemaMetadata(field, withoutNestedObjectDefaults(peeled).optional()) : field;
+            next = withoutDefault(field);
         }
         else {
             next = withoutNestedObjectDefaults(field);
@@ -163,6 +163,37 @@ function withoutNestedObjectDefaults(schema) {
     const rebuilt = schema.clone({ ...def, shape: nextShape });
     return copySchemaMetadata(schema, rebuilt);
 }
+/** The checks declared on this schema itself, which a rebuilt wrapper does not inherit. */
+function ownChecks(schema) {
+    return getZodDefProperty(schema, 'checks') ?? [];
+}
+/**
+ * `check`, run only on what the request sent (#3342). A check declared on a `.default()` always had a value to read, so
+ * moved onto the optional that replaces the default it would meet `undefined` on every omitted field, and it has nothing
+ * to say about a field the request did not send. Zod's own `when` is what keeps its abort rule beside this.
+ */
+function checkOnWhatWasSent(check) {
+    const { when } = check._zod.def;
+    const sent = z.check((payload) => (payload.value === undefined ? undefined : check._zod.check(payload)));
+    if (when)
+        sent._zod.def.when = (payload) => payload.value !== undefined && when(payload);
+    return sent;
+}
+/**
+ * A `.default()` field for a PATCH: optional, with nothing to re-materialise, and still held to the checks declared on the
+ * default (#3342). Those checks are the wrapper's own, so they are carried over by hand. With a check present, the fields
+ * under it keep their defaults, so it reads the value it was written against: the same rule as a refined object. The
+ * inner schema stays shared and is never mutated.
+ */
+function withoutDefault(defaulted) {
+    const inner = getZodDefSchemaProperty(defaulted, 'innerType');
+    if (!inner)
+        return defaulted;
+    const checks = ownChecks(defaulted);
+    if (checks.length === 0)
+        return copySchemaMetadata(defaulted, withoutNestedObjectDefaults(inner).optional());
+    return copySchemaMetadata(defaulted, inner.optional().check(...checks.map(checkOnWhatWasSent)));
+}
 /**
  * What a BULK update form validates (#2581): `schema` with every child of a child-writable nested object made optional,
  * at every level ({@link isChildWritableObject}).
@@ -186,6 +217,8 @@ export function withOptionalNestedChildren(schema) {
 }
 /** `field` with, if it is a child-writable object, each of its children optional (and so on down). */
 function withOptionalChildrenOf(field) {
+    if (ownChecks(field).length > 0)
+        return field;
     const type = getZodType(field);
     if (type === 'optional' || type === 'nullable') {
         const inner = getZodDefSchemaProperty(field, 'innerType');
@@ -267,10 +300,11 @@ function copySchemaMetadata(source, target) {
  *   optional and does not already accept null.
  * - Default-wrapped fields: the outer `ZodDefault` is peeled, the inner schema
  *   (keeping `.int()` / `.min()` / refinements) is made optional, and any
- *   decorator metadata attached to the default wrapper (e.g.
+ *   decorator metadata or description on the default wrapper (e.g.
  *   `.default(0).isSummaryField()`) is carried onto the resulting optional so
- *   `getMetadataRecursive` is unchanged. The inner schema is SHARED, never
- *   mutated, so the source schema is left intact.
+ *   `getMetadataRecursive` is unchanged. A check declared ON the default still holds, on what the
+ *   request sent (#3342). The inner schema is SHARED, never mutated, so the source schema is left
+ *   intact.
  *
  * Defaults remain correct for CREATE (a new row gets them) — this transform is
  * for the UPDATE DTO only.
@@ -281,23 +315,11 @@ export function toPatchOptionalField(fieldSchema) {
         const nestedPatched = withoutNestedObjectDefaults(fieldSchema);
         return admitsNullClear ? nestedPatched.nullable().optional() : nestedPatched.optional();
     }
-    const rawInnerType = getZodDefSchemaProperty(fieldSchema, 'innerType');
-    if (!rawInnerType)
+    if (!getZodDefSchemaProperty(fieldSchema, 'innerType'))
         return fieldSchema.optional();
-    const innerType = withoutNestedObjectDefaults(rawInnerType);
     // A defaulted field is never null-clearable (see `fieldAdmitsAddedNullClear`), so the peeled
     // inner is made optional WITHOUT a nullable wrapper.
-    const optionalInner = innerType.optional();
-    const defaultWrapperMetadata = fieldSchema[SCHEMA_METADATA];
-    if (defaultWrapperMetadata) {
-        const optionalRecord = optionalInner;
-        const existing = optionalRecord[SCHEMA_METADATA] ?? {};
-        optionalRecord[SCHEMA_METADATA] = {
-            ...existing,
-            ...defaultWrapperMetadata,
-        };
-    }
-    return optionalInner;
+    return withoutDefault(fieldSchema);
 }
 /**
  * The value an edit control should contribute to form state, once a "the user emptied this field"
@@ -608,6 +630,9 @@ export function withArrayElement(arraySchema, element) {
         return arraySchema;
     }
     const rebuilt = arraySchema.clone({ ...def, element });
+    const decoratorMetadata = arraySchema[SCHEMA_METADATA];
+    if (decoratorMetadata !== undefined)
+        rebuilt[SCHEMA_METADATA] = decoratorMetadata;
     const registered = z.globalRegistry.get(arraySchema);
     if (registered !== undefined && !z.globalRegistry.has(rebuilt)) {
         const { id: _id, ...carried } = registered;
@@ -1270,6 +1295,37 @@ export function getUnionObjectMembers(schema) {
     const options = (getZodDefArrayProperty(schema, 'options') ?? []);
     return options.filter((option) => isZodTypeAny(option) && isZodObject(option));
 }
+/**
+ * The value(s) ONE member of a discriminated union holds for its discriminator, read through every wrapper (#2076).
+ *
+ * A member's discriminator is a literal (`z.literal('recurring')`, whose values Zod 4 keeps in an ARRAY under `values`)
+ * or, for the base values a schema family groups into one member, an enum. It is no longer always BARE: the member that
+ * holds the value the base field declares as its `.default()` carries `literal.optional().default(value)`, the one shape
+ * a Zod 4 discriminated union can route an omitted key by. A reader of the bare `def.values` would miss that member, so
+ * a reader of a DECLARED union's member values goes through here. {@link getUnionDiscriminatorKey}'s inference over a
+ * PLAIN union deliberately does not: it asks whether a key discriminates at all, and only a bare literal proves that.
+ *
+ * Non-string literal values (a numeric discriminator) are kept as they are; an enum contributes its string values.
+ */
+export function getDiscriminatorMemberValues(memberDiscriminator) {
+    if (!memberDiscriminator)
+        return [];
+    const unwrapped = unwrapSchema(memberDiscriminator);
+    if (getZodType(unwrapped) === 'literal') {
+        return (getZodDefArrayProperty(unwrapped, 'values') ?? [getZodDefProperty(unwrapped, 'value')])
+            .filter((value) => value !== undefined && value !== null);
+    }
+    return getEnumValues(unwrapped);
+}
+/**
+ * Whether a member of a declared discriminated union is the one Zod routes a value WITHOUT the discriminator to (#2076):
+ * its discriminator accepts the key's absence, which Zod 4 reads from the member field's `_zod.values` containing
+ * `undefined` (an `.optional()` under the declared `.default()`).
+ */
+function memberTakesOmittedDiscriminator(memberDiscriminator) {
+    const values = memberDiscriminator?._zod?.values;
+    return values instanceof Set && values.has(undefined);
+}
 /**
  * Resolve the ONE variant of a discriminated union that a given value belongs to.
  *
@@ -1282,7 +1338,8 @@ export function getUnionObjectMembers(schema) {
  * The discriminator is {@link getUnionDiscriminatorKey}'s: declared, or carried structurally by a plain
  * `z.union` (#1022 — a versioned record's items). For such a plain union a value carrying NO discriminator
  * belongs to the one strict member that omits the key, when there is one; for a declared discriminated union
- * it belongs to none.
+ * it belongs to the member Zod itself routes it to — the one whose discriminator takes the declared default
+ * (#2076) — and to none when no member does.
  *
  * Returns `null` when the schema is not a discriminated union, when the value carries no
  * discriminator its union can place, or when no variant matches it — all three are "this caller cannot
@@ -1297,8 +1354,9 @@ export function resolveDiscriminatedUnionVariant(schema, value) {
     const discriminatorValue = value[discriminator];
     const options = (getZodDefArrayProperty(schema, 'options') ?? []);
     if (discriminatorValue === undefined) {
-        if (getZodDefStringProperty(schema, 'discriminator'))
-            return null;
+        if (getZodDefStringProperty(schema, 'discriminator')) {
+            return options.find((option) => isZodObject(option) && memberTakesOmittedDiscriminator(getZodObjectShape(option)[discriminator])) ?? null;
+        }
         return options.find((option) => isZodObject(option) && getZodObjectShape(option)[discriminator] === undefined) ?? null;
     }
     for (const option of options) {
@@ -1309,12 +1367,11 @@ export function resolveDiscriminatedUnionVariant(schema, value) {
         if (!discriminatorSchema)
             continue;
         /*
-         * A variant's discriminator is a LITERAL (`z.literal(ICPArchetype.LEGAL_ENTITY)`), whose value
-         * Zod 4 stores as an array under `values` — the same shape `getEnumValues` reads for the
-         * literal case. Comparing against that is what makes the match exact rather than structural.
+         * A variant's discriminator is a LITERAL (`z.literal(ICPArchetype.LEGAL_ENTITY)`), or the enum of a family's base
+         * values, possibly under the declared default's wrappers (#2076). Comparing the exact values
+         * `getDiscriminatorMemberValues` reads is what makes the match exact rather than structural.
          */
-        const literalValues = getZodDefArrayProperty(discriminatorSchema, 'values') ?? [];
-        if (literalValues.includes(discriminatorValue))
+        if (getDiscriminatorMemberValues(discriminatorSchema).includes(discriminatorValue))
             return option;
     }
     return null;
@@ -1896,17 +1953,32 @@ export function getObjectLikeFieldSchema(schema, fieldName) {
  * - a **plain object** (`FieldSchemaType.OBJECT`). A value type stored as an object (money, an address, a duration, a
  *   file, a versioned object) is ONE value, written whole: `price.amount` alone would leave every row's own currency
  *   under it.
- * - with **no refinement of its own** (`.refine()`, `.superRefine()`, `.check()`). A refinement judges the children
- *   TOGETHER (`start` before `end`), and a write of one child never runs it, so such an object is written whole.
+ * - with **no refinement** (`.refine()`, `.superRefine()`, `.check()`) on the object or on any wrapper around it. A
+ *   refinement judges the children TOGETHER (`start` before `end`), and a write of one child never runs it, so such an
+ *   object is written whole. A check on the optional, nullable or default around the object counts too (#3342): the form,
+ *   the write units and the server all ask this, so a wrapper's check cannot be required by one and skipped by another.
  *
  * Arrays are never child-writable: an index addresses a position, which is a different element on every row.
- * Wrappers (optional, nullable, default) are looked through.
+ * Wrappers (optional, nullable, default, readonly, catch, and a pipe's input) are looked through, as `unwrapSchema` does.
  */
 export function isChildWritableObject(schema) {
     if (getSchemaType(schema) !== FieldSchemaType.OBJECT || getObjectShape(schema) === null)
         return false;
-    const checks = unwrapSchema(schema)._zod?.def?.checks;
-    return !(Array.isArray(checks) && checks.length > 0);
+    // The wrappers `unwrapSchema` looks through, so every layer between the field and its object is asked.
+    let current = schema;
+    while (current) {
+        if (ownChecks(current).length > 0)
+            return false;
+        const type = getZodType(current);
+        if (type === 'pipe')
+            current = getZodDefSchemaProperty(current, 'in');
+        else if (type === 'optional' || type === 'nullable' || type === 'default' || type === 'readonly' || type === 'catch') {
+            current = getZodDefSchemaProperty(current, 'innerType');
+        }
+        else
+            return true;
+    }
+    return true;
 }
 /**
  * The schema of ONE CHILD of a nested object, addressed by a dotted path (`contact.city`, `settings.theme.mode`).
@@ -2416,6 +2488,13 @@ export function getBackendOnlyParams(schema) {
         return {}; // Default params when decorator is used without params
     return value;
 }
+/**
+ * Whether a backend-only field declares that its value is the subject's own data, disclosed in their access export
+ * (`isBackendOnly({ disclosedToSubject: true })`, #2958). `false` for a field that is not backend-only.
+ */
+export function isBackendOnlyFieldDisclosedToSubject(schema) {
+    return getBackendOnlyParams(schema)?.disclosedToSubject === true;
+}
 /**
  * Check if a schema field has the isWriteOnlySecret decorator.
  */
@@ -2548,6 +2627,14 @@ export function isDeciderField(schema) {
     const metadata = getMetadataRecursive(schema);
     return metadata?.[ZodDecorator.IS_DECIDER] === true;
 }
+/**
+ * Are this field's values roles the writer grants (`.isRoleGrant()`, #3248)? Reads through wrapper types, so the marker
+ * is seen whether it was declared before or after `.optional()` / `.default()`.
+ */
+export function isRoleGrantField(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.IS_ROLE_GRANT] === true;
+}
 /** The names of a row schema's decider fields (`.isDecider()`), across every variant of a polymorphic row. */
 export function deciderFieldNames(rowSchema) {
     if (!rowSchema)
@@ -2795,8 +2882,7 @@ export function isPrimaryKeyField(schema) {
  *
  * A business key is the **declaration-side identity** used by the data-seeding
  * subsystem to upsert / upgrade / sync seeded rows independently from the
- * random `_id` (`isPrimaryKey`). See `.cursor/plans/seeding-first-class.md`
- * §3.3 for the semantic contract.
+ * random `_id` (`isPrimaryKey`).
  */
 export function isBusinessKeyField(schema) {
     const metadata = getMetadataRecursive(schema);
@@ -2816,8 +2902,7 @@ export function getDocumentSequenceParams(schema) {
  * list of field names, or `undefined` if no composite key is declared.
  *
  * The composite key is the schema-level analog of `isBusinessKey` — used
- * when identity is `(orgId, templateKey)` rather than a single field. See
- * `.cursor/plans/seeding-first-class.md` §3.3.
+ * when identity is `(orgId, templateKey)` rather than a single field.
  */
 export function getBusinessKeySet(schema) {
     return getBusinessKeySetParams(schema)?.fields;
@@ -2836,6 +2921,24 @@ export function getBusinessKeySetParams(schema) {
     const params = metadata?.[ZodDecorator.OBJECT_BUSINESS_KEY_SET];
     return params?.fields ? params : undefined;
 }
+/**
+ * Every NON-unique compound index an object schema declares with `compoundIndex([...])` (#3142), in declaration order,
+ * or `[]`. Each entry's `fields` are in index order. The ONE reader both storage adapters ask (the MongoDB convertor
+ * and the PostgreSQL planner), so they cannot disagree about which indexes a resource has.
+ *
+ * Only the indexes whose fields this object still HAS: Zod's `.omit()`, `.pick()` and `.extend()` copy the outer
+ * metadata wholesale, so an object derived from one that declared an index would otherwise keep an index naming a field
+ * it dropped, and its storage would refuse to build. An object that lost a field lost the index over it.
+ */
+export function getCompoundIndexes(schema) {
+    const declared = getMetadataRecursive(schema)?.[ZodDecorator.OBJECT_COMPOUND_INDEX];
+    if (!Array.isArray(declared))
+        return [];
+    const shape = getZodObjectShape(schema);
+    return declared
+        .filter((index) => index.fields.every((field) => Object.hasOwn(shape, field)))
+        .map((index) => ({ fields: [...index.fields] }));
+}
 /**
  * The target set an object declares with `isResourceReference({ targetSet })` (#2471): the object names one row of a
  * resource whose type is chosen at run time from that set. `undefined` when the object is not a resource reference.