@wildo-ai/zod-decorators 1.1.9 → 1.1.11

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

@@ -163,11 +163,74 @@ function withoutNestedObjectDefaults(schema) {
     const rebuilt = schema.clone({ ...def, shape: nextShape });
     return copySchemaMetadata(schema, rebuilt);
 }
+/**
+ * What a BULK update form validates (#2581): `schema` with every child of a child-writable nested object made optional,
+ * at every level ({@link isChildWritableObject}).
+ *
+ * A bulk update writes a nested object child by child, and only the children the person changed, so a child its
+ * object REQUIRES is not required of the form: requiring it would make the person fill every required sibling to change
+ * one, and those siblings would then be written to every selected row. The server validates each child written against
+ * its own declaration, and builds a whole object only for a row that has none (refusing when the children written do
+ * not make one).
+ *
+ * Only nested children change: a top-level field keeps its own optionality, since the action's request decides what it
+ * cannot run without. An object that is not child-writable (a value type, one with its own refinement) and an array are
+ * left exactly as declared: they are written whole. Rebuilt like {@link withoutNestedObjectDefaults} does, with Zod's
+ * own `clone(def)` and every rebuilt schema carrying its source's metadata, so labels, edit modes and descriptions
+ * survive and the source is untouched. A schema that is not an object (a union) is returned as it is.
+ */
+export function withOptionalNestedChildren(schema) {
+    if (getZodType(schema) !== 'object')
+        return schema;
+    return rebuildObjectShape(schema, (field) => withOptionalChildrenOf(field));
+}
+/** `field` with, if it is a child-writable object, each of its children optional (and so on down). */
+function withOptionalChildrenOf(field) {
+    const type = getZodType(field);
+    if (type === 'optional' || type === 'nullable') {
+        const inner = getZodDefSchemaProperty(field, 'innerType');
+        if (!inner)
+            return field;
+        const rebuiltInner = withOptionalChildrenOf(inner);
+        if (rebuiltInner === inner)
+            return field;
+        return copySchemaMetadata(field, type === 'optional' ? rebuiltInner.optional() : rebuiltInner.nullable());
+    }
+    if (type !== 'object' || !isChildWritableObject(field))
+        return field;
+    return rebuildObjectShape(field, (child) => {
+        const rebuiltChild = withOptionalChildrenOf(child);
+        if (rebuiltChild.safeParse(undefined).success)
+            return rebuiltChild;
+        return copySchemaMetadata(child, rebuiltChild.optional());
+    });
+}
+/** `schema` (a Zod object) with each field passed through `rebuild`; the same schema when nothing changed. */
+function rebuildObjectShape(schema, rebuild) {
+    const def = schema._zod.def;
+    const shape = schema.shape;
+    const nextShape = {};
+    let changed = false;
+    for (const [key, field] of Object.entries(shape)) {
+        const next = rebuild(field);
+        if (next !== field)
+            changed = true;
+        nextShape[key] = next;
+    }
+    if (!changed)
+        return schema;
+    const rebuilt = schema.clone({ ...def, shape: nextShape });
+    return copySchemaMetadata(schema, rebuilt);
+}
 /** Carry decorator metadata from a source wrapper onto a rebuilt one; the source is never mutated. */
 function copySchemaMetadata(source, target) {
     const registered = z.globalRegistry.get(source);
-    if (registered && !z.globalRegistry.has(target))
-        z.globalRegistry.add(target, registered);
+    if (registered && !z.globalRegistry.has(target)) {
+        // Never the `id`: an id names ONE schema, and the rebuilt copy taking it would rename the source's export.
+        const { id: _id, ...inherited } = registered;
+        if (Object.keys(inherited).length > 0)
+            z.globalRegistry.add(target, inherited);
+    }
     const metadata = source[SCHEMA_METADATA];
     if (metadata) {
         const record = target;
@@ -779,7 +842,17 @@ export function getSchemaType(schema) {
             }
         }
         /*
-         * A `z.date()` is a DAY unless it declares itself a MOMENT.
+         * Which CONTROL a `z.date()` gets: the day pair unless it declares itself a MOMENT. Three declarations, two
+         * classifications (#2180):
+         *
+         * - `z.date().isCalendarDate()` → `DATE`. A calendar day, held as UTC midnight and read by its UTC day, the
+         *   same day for every reader. `isCalendarDateSchema` is what the formatters and the picker read for that.
+         * - bare `z.date()` → `DATE` as well. Edited and shown as a day, but the value is an INSTANT, read in the
+         *   reader's zone: its picker shows the day it reads there, and a picked day is that day in that zone at the
+         *   value's own time of day (its start, for an empty field) (#2454). Right for a timestamp shown by its day
+         *   (`createdAt`); a field meaning a day should declare `isCalendarDate()`.
+         * - `z.date().dateTimeUI(...)` → `DATETIME`. A moment with a time of day. It cannot be combined with
+         *   `isCalendarDate()`: applying the second one throws.
          *
          * In Wildo a datetime is Date-based — an ISO-8601 string is a wire format for one, never the
          * model — so `ZodDate` is the carrier for both "a day" (`dueDate`) and "a point in time"
@@ -1799,21 +1872,66 @@ function stripZodInternalKeys(shape) {
  * @returns the field's declared schema, or `undefined` when no variant declares it.
  */
 export function getObjectLikeFieldSchema(schema, fieldName) {
+    // OWN keys only: a name like `constructor` or `__proto__` would otherwise answer with an Object.prototype member,
+    // which is not a schema and makes every reader that inspects it throw.
     const directShape = getObjectShape(schema);
     if (directShape)
-        return directShape[fieldName];
+        return Object.hasOwn(directShape, fieldName) ? directShape[fieldName] : undefined;
     const unwrapped = unwrapSchema(schema);
     if (!isZodUnion(unwrapped))
         return undefined;
     const options = getZodDefArrayProperty(unwrapped, 'options') ?? [];
     for (const option of options) {
         const optionShape = getObjectShape(option);
-        const fieldSchema = optionShape?.[fieldName];
+        const fieldSchema = optionShape && Object.hasOwn(optionShape, fieldName) ? optionShape[fieldName] : undefined;
         if (fieldSchema)
             return fieldSchema;
     }
     return undefined;
 }
+/**
+ * Whether a nested object's CHILDREN may be written one by one (`contact.city`), leaving each stored row's other
+ * children as they are: what a bulk update does to part of a nested object (#2581).
+ *
+ * - 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.
+ *
+ * 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.
+ */
+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 schema of ONE CHILD of a nested object, addressed by a dotted path (`contact.city`, `settings.theme.mode`).
+ *
+ * This is what a bulk update writes when it changes part of a nested object on many rows: each row keeps the children
+ * it was not asked to change, which a whole-object write cannot do (it replaces the object on every row). So the path
+ * walks only objects whose children can be written one by one ({@link isChildWritableObject}) at every level.
+ *
+ * @param schema - the object (or union of objects) whose top-level field the path starts from; wrappers are unwrapped.
+ * @param path - `<field>.<child>[.<child>…]`. A top-level name is not a child path.
+ * @returns the child's declared schema, or `undefined` when the path names no child of a child-writable object.
+ */
+export function getNestedChildFieldSchema(schema, path) {
+    const segments = path.split('.');
+    if (segments.length < 2 || segments.some((segment) => segment.length === 0))
+        return undefined;
+    let current = getObjectLikeFieldSchema(schema, segments[0]);
+    for (const segment of segments.slice(1)) {
+        if (!current || !isChildWritableObject(current))
+            return undefined;
+        const shape = getObjectShape(current);
+        current = shape && Object.hasOwn(shape, segment) ? shape[segment] : undefined;
+    }
+    return current;
+}
 export function getObjectShape(schema) {
     const unwrapped = unwrapSchema(schema);
     if (getZodType(unwrapped) !== 'object') {
@@ -2349,8 +2467,9 @@ export function getPortabilityProvenance(schema) {
  * or `undefined` when the field carries no declaration.
  *
  * Set via the fluent `.dataCategories(...)` method or `addDataCategories(schema, ...)`. Always an
- * ARRAY, deduped and non-empty: the decorator chokepoint normalizes a single-value authoring form
- * on the way in, so a caller never has to handle two shapes.
+ * ARRAY, deduped and non-empty: the decorator chokepoint normalizes every authoring form on the way
+ * in, so a caller never has to handle two shapes. The optional condition is read separately, by
+ * {@link getPersonalDataCondition}.
  *
  * Reads through wrapper types (`getMetadataRecursive` walks outer → inner), so it observes the
  * declaration whether it was written before or after `.optional()` / `.nullable()` / `.nullish()` /
@@ -2364,9 +2483,30 @@ export function getPortabilityProvenance(schema) {
  * @wildo_source:part:start zod.decorators.data-categories facet:layer:shared facet:family:decorator facet:kind:api facet:audience:app-developer
  */
 export function getDataCategories(schema) {
-    const metadata = getMetadataRecursive(schema);
-    const value = metadata?.[ZodDecorator.DATA_CATEGORIES];
-    return Array.isArray(value) && value.length > 0 ? value : undefined;
+    const categories = getMetadataRecursive(schema)?.[ZodDecorator.DATA_CATEGORIES]?.categories;
+    return Array.isArray(categories) && categories.length > 0 ? categories : undefined;
+}
+/**
+ * Under WHICH CONDITION is this field personal data at all? Returns the `PersonalDataCondition`
+ * value declared through `.dataCategories(categories, { personalOnlyWhen })` (as an opaque string),
+ * or `undefined` when the field is personal data on every row — or declares no category (#2119).
+ *
+ * Read it beside {@link getDataCategories}, never instead of it: a conditional field still HOLDS
+ * those categories, and every reader deciding whether a field is personal (erasure, export, the
+ * stance checks) keeps counting it. The condition matters only to a statement made about the data,
+ * such as a privacy notice saying "where the customer is an individual".
+ */
+export function getPersonalDataCondition(schema) {
+    const condition = getMetadataRecursive(schema)?.[ZodDecorator.DATA_CATEGORIES]?.personalOnlyWhen;
+    return typeof condition === 'string' && condition.length > 0 ? condition : undefined;
+}
+/**
+ * Does this field name a party OTHER than the one its row is about, as declared through
+ * `.dataCategories(categories, { aboutAnotherParty: true })` (#2535)? `false` for every field that does not say so.
+ * WHOSE data the field is, not WHETHER it is personal: read it beside {@link getDataCategories}, never instead of it.
+ */
+export function isPersonalDataAboutAnotherParty(schema) {
+    return getMetadataRecursive(schema)?.[ZodDecorator.DATA_CATEGORIES]?.aboutAnotherParty === true;
 }
 /** @wildo_source:part:end zod.decorators.data-categories */
 /**
@@ -2391,6 +2531,48 @@ export function isAuditEvidenceField(schema) {
     const metadata = getMetadataRecursive(schema);
     return metadata?.[ZodDecorator.IS_AUDIT_EVIDENCE] === true;
 }
+/**
+ * Does this row field hold what the most recent action said about itself (the reason given for a decision),
+ * rather than state the next action starts from? Set via the fluent `.isLastActionRecord()`. Reads through
+ * wrapper types, so the marker is seen whether it was declared before or after `.optional()` / `.default()`.
+ */
+export function isLastActionRecordField(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.IS_LAST_ACTION_RECORD] === true;
+}
+/**
+ * Does this row field record which person decided something on the row (`.isDecider()`, #2906)? Reads through wrapper
+ * types, so the marker is seen whether it was declared before or after `.optional()` / `.default()`.
+ */
+export function isDeciderField(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.IS_DECIDER] === true;
+}
+/** The names of a row schema's decider fields (`.isDecider()`), across every variant of a polymorphic row. */
+export function deciderFieldNames(rowSchema) {
+    if (!rowSchema)
+        return new Set();
+    const names = new Set();
+    for (const [fieldName, fieldSchema] of Object.entries(getMergedObjectOrUnionShape(rowSchema))) {
+        if (isDeciderField(fieldSchema))
+            names.add(fieldName);
+    }
+    return names;
+}
+/**
+ * The names of a row schema's last-action-record fields (`.isLastActionRecord()`), across every variant of a
+ * polymorphic (discriminated-union) row. What a form that starts from the row must leave out of its seed.
+ */
+export function lastActionRecordFieldNames(rowSchema) {
+    if (!rowSchema)
+        return new Set();
+    const names = new Set();
+    for (const [fieldName, fieldSchema] of Object.entries(getMergedObjectOrUnionShape(rowSchema))) {
+        if (isLastActionRecordField(fieldSchema))
+            names.add(fieldName);
+    }
+    return names;
+}
 function getImpersonalizeParams(schema) {
     const metadata = getMetadataRecursive(schema);
     const value = metadata?.[ZodDecorator.IMPERSONALIZE_WITH];
@@ -2620,6 +2802,14 @@ export function isBusinessKeyField(schema) {
     const metadata = getMetadataRecursive(schema);
     return metadata?.[ZodDecorator.IS_BUSINESS_KEY] === true;
 }
+/**
+ * The `documentSequence` parameters a field declares (#2509), through any wrapper, or `undefined`. What the backend's
+ * allocator reads to number a row's document field.
+ */
+export function getDocumentSequenceParams(schema) {
+    const metadata = getMetadataRecursive(schema);
+    return metadata?.[ZodDecorator.DOCUMENT_SEQUENCE];
+}
 /**
  * Read the composite business key declared on an object schema via
  * `businessKeySet([...])` (object-level decorator). Returns the ordered
@@ -2646,6 +2836,15 @@ export function getBusinessKeySetParams(schema) {
     const params = metadata?.[ZodDecorator.OBJECT_BUSINESS_KEY_SET];
     return params?.fields ? params : undefined;
 }
+/**
+ * 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.
+ * Read through wrappers, so `WorkUnitRefSchema.optional()` answers like `WorkUnitRefSchema`.
+ */
+export function getResourceReferenceTargetSet(schema) {
+    const params = getMetadataRecursive(schema)?.[ZodDecorator.RESOURCE_REFERENCE];
+    return typeof params?.targetSet === 'string' && params.targetSet.length > 0 ? params.targetSet : undefined;
+}
 /**
  * Convenience predicate: does the schema declare any business key
  * identity (single field-level marker OR composite object-level set)?
@@ -3555,6 +3754,17 @@ export function isEligibleForLayoutDefaultInlineEdit(schema) {
         return false;
     return true;
 }
+/**
+ * Is this field editable in place because it DECLARES so (`inlineEditable`, true or with params)?
+ *
+ * Its own declaration, the counterpart of {@link isEligibleForLayoutDefaultInlineEdit}, with the one clause a
+ * declaration cannot override: a field `.excludeFromUpdate()` strips is never offered (#2322). The write would
+ * persist nothing while the control reported success, so the rule belongs to the engine rather than to every author
+ * who combines the two decorators.
+ */
+export function isInlineEditableByDeclaration(schema) {
+    return hasInlineEditableDecorator(schema) && !isExcludedFromUpdate(schema);
+}
 /**
  * Get the resolved inline editable params from `{primitive}UI.display.inlineEditable`.
  * Handles both `true` shorthand and full object config.
@@ -4253,6 +4463,14 @@ export function getDateUI(schema) {
 export function hasDateUI(schema) {
     return hasDecorator(schema, ZodDecorator.DATE_UI);
 }
+/**
+ * Whether a date field holds a CALENDAR DAY (`z.date().isCalendarDate()`) rather than an instant: stored as
+ * UTC midnight of the day, shown and edited by that day whatever the reader's time zone. See
+ * `ZodDecorator.IS_CALENDAR_DATE`.
+ */
+export function isCalendarDateSchema(schema) {
+    return schema !== undefined && hasDecorator(schema, ZodDecorator.IS_CALENDAR_DATE);
+}
 export function getDateTimeUI(schema) {
     return getCustomFieldMetadata(schema)[ZodDecorator.DATETIME_UI];
 }