typesea 0.1.0 → 0.3.0

package/dist/builders/object/schema.d.ts

@@ -1,44 +1,121 @@
 /**
  * @file schema.ts
  * @brief Object schema construction and shape rewrites.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { ObjectModeTag } from "../../kind/index.js";
-import type { ObjectEntry, ObjectSchema } from "../../schema/index.js";
+import type { ObjectEntry, ObjectSchema, Schema } from "../../schema/index.js";
 import type { ObjectShape } from "./types.js";
 /**
- * @brief object schema.
+ * @brief Normalize an object shape into ordered entries and lookup metadata.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare function objectSchema(shape: ObjectShape, mode: ObjectModeTag): ObjectSchema;
 /**
- * @brief object schema from entries.
+ * @brief Rebuild object metadata after shape transformations.
+ * @details Duplicate keys are rejected here so pick/omit/extend cannot create
+ * a schema that disagrees with its strict-key lookup table.
  */
-export declare function objectSchemaFromEntries(sourceEntries: readonly ObjectEntry[], mode: ObjectModeTag): ObjectSchema;
+export declare function objectSchemaFromEntries(sourceEntries: readonly ObjectEntry[], mode: ObjectModeTag, catchall: Schema | undefined): ObjectSchema;
 /**
- * @brief read object constructor schema.
+ * @brief Rebuild an object schema with a different unknown-key mode.
+ * @param schema Source object schema.
+ * @param mode Unknown-key policy for the rebuilt schema.
+ * @returns Object schema with identical entries and catchall policy.
+ */
+export declare function objectSchemaWithMode(schema: ObjectSchema, mode: ObjectModeTag): ObjectSchema;
+/**
+ * @brief Rebuild an object schema with an unknown-key validator.
+ * @param schema Source object schema.
+ * @param catchall Schema applied to every undeclared own key.
+ * @returns Object schema that validates extra keys with the supplied schema.
+ */
+export declare function objectSchemaWithCatchall(schema: ObjectSchema, catchall: Schema): ObjectSchema;
+/**
+ * @brief Validate the schema value handed to an ObjectGuard constructor.
+ * @details Constructors are public JavaScript entry points, so the guard checks
+ * both the TypeSea schema marker and the object-schema tag before storing the
+ * value. This prevents forged objects from bypassing builder invariants.
+ * @param schema Candidate schema supplied to the constructor.
+ * @returns Object schema accepted by the constructor.
  */
 export declare function readObjectConstructorSchema(schema: unknown): ObjectSchema;
 /**
- * @brief read object method schema.
+ * @brief Extract an object schema from another guard for object-only methods.
+ * @details Methods such as merge and extension compose object shapes. Accepting
+ * a scalar guard here would build an impossible schema, so the check is kept at
+ * the API edge with the caller-facing label in the error message.
+ * @param guard Candidate TypeSea guard.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Object schema owned by the supplied guard.
  */
 export declare function readObjectMethodSchema(guard: unknown, label: string): ObjectSchema;
 /**
- * @brief merge object schemas.
+ * @brief Merge two object schemas while letting extension keys override base keys.
+ * @details Existing base order is preserved for stable diagnostics and codegen.
+ * Extension-only keys are appended afterward, and the base strict/open mode is
+ * retained so shape extension does not silently change excess-key policy.
+ * @param base Source object schema being extended.
+ * @param extension Object schema whose matching keys replace base entries.
+ * @returns Rebuilt object schema with fresh lookup metadata.
  */
 export declare function mergeObjectSchemas(base: ObjectSchema, extension: ObjectSchema): ObjectSchema;
 /**
- * @brief pick object schema.
+ * @brief Build an object schema containing only a validated key selection.
+ * @details The caller has already checked that keys are known and unique. This
+ * function preserves selection order so user-requested projection order is also
+ * the order used by diagnostics and generated object checks.
+ * @param schema Source object schema.
+ * @param keys Validated key selection.
+ * @returns Rebuilt object schema containing only selected entries.
  */
 export declare function pickObjectSchema(schema: ObjectSchema, keys: readonly string[]): ObjectSchema;
 /**
- * @brief omit object schema.
+ * @brief Build an object schema with a validated key selection removed.
+ * @details Entries not listed for removal keep their original relative order
+ * and presence metadata. The object mode is preserved across the rewrite.
+ * @param schema Source object schema.
+ * @param keys Validated key selection to remove.
+ * @returns Rebuilt object schema without the selected entries.
  */
 export declare function omitObjectSchema(schema: ObjectSchema, keys: readonly string[]): ObjectSchema;
 /**
- * @brief partial object schema.
+ * @brief Convert every object entry to optional presence.
+ * @details The child schemas are not wrapped or cloned; only field presence is
+ * rewritten. This keeps value-domain wrappers such as nullable and brand exactly
+ * as they were on the original entries.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with optional entries.
  */
 export declare function partialObjectSchema(schema: ObjectSchema): ObjectSchema;
 /**
- * @brief read object key selection.
+ * @brief Recursively convert object entries to optional presence.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with nested object/container children partialized.
+ * @details Lazy and refinement schemas are treated as semantic barriers because
+ * their runtime callbacks may depend on the original exact value domain.
+ */
+export declare function deepPartialObjectSchema(schema: ObjectSchema): ObjectSchema;
+/**
+ * @brief Convert every object entry to required presence.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with required entries.
+ * @details Object construction already stripped Optional wrappers into entry
+ * presence metadata. Requiring a field therefore only needs to flip that
+ * metadata back to Required while preserving each value-domain schema.
+ */
+export declare function requiredObjectSchema(schema: ObjectSchema): ObjectSchema;
+/**
+ * @brief Validate the key list supplied to object pick and omit operations.
+ * @details The returned array contains only known, unique string keys. This
+ * preflight keeps later schema rewriting simple and prevents silently selecting
+ * fields that were never part of the source object schema.
+ * @param keys Candidate key list from public API calls.
+ * @param schema Object schema whose keys define the valid selection domain.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Ordered key selection accepted by the object builder.
  */
 export declare function readObjectKeySelection(keys: unknown, schema: ObjectSchema, label: string): readonly string[];
 //# sourceMappingURL=schema.d.ts.map

package/dist/builders/object/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/builders/object/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EAEb,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAU9C;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,aAAa,GAClB,YAAY,CAsBd;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,SAAS,WAAW,EAAE,EACrC,IAAI,EAAE,aAAa,GAClB,YAAY,CAuBd;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAMlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,YAAY,GACtB,YAAY,CAed;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,YAAY,CAad;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,YAAY,CASd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAatE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GACZ,SAAS,MAAM,EAAE,CAmBnB"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/builders/object/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,aAAa,EAGhB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EACR,WAAW,EAEX,YAAY,EACZ,MAAM,EACT,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY9C;;;;GAIG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,aAAa,GACpB,YAAY,CAsBd;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACnC,aAAa,EAAE,SAAS,WAAW,EAAE,EACrC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC7B,YAAY,CAwBd;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,aAAa,GACpB,YAAY,CAEd;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,GACjB,YAAY,CAEd;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAMlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,YAAY,GACxB,YAAY,CAmBd;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACxB,YAAY,CAad;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACxB,YAAY,CASd;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAatE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAgB1E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAavE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GACd,SAAS,MAAM,EAAE,CAsBnB"}

package/dist/builders/object/schema.js

@@ -1,12 +1,16 @@
 /**
  * @file schema.ts
  * @brief Object schema construction and shape rewrites.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { ObjectModeTag, PresenceTag, SchemaTag } from "../../kind/index.js";
 import { includesString, isRecord, isUnknownArray, readGuardSchema } from "../../internal/index.js";
 import { isSchemaValue } from "../../schema/index.js";
 /**
- * @brief object schema.
+ * @brief Normalize an object shape into ordered entries and lookup metadata.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export function objectSchema(shape, mode) {
     if (!isRecord(shape)) {
@@ -27,12 +31,14 @@ export function objectSchema(shape, mode) {
             presence: entrySchema.presence
         };
     }
-    return objectSchemaFromEntries(entries, mode);
+    return objectSchemaFromEntries(entries, mode, undefined);
 }
 /**
- * @brief object schema from entries.
+ * @brief Rebuild object metadata after shape transformations.
+ * @details Duplicate keys are rejected here so pick/omit/extend cannot create
+ * a schema that disagrees with its strict-key lookup table.
  */
-export function objectSchemaFromEntries(sourceEntries, mode) {
+export function objectSchemaFromEntries(sourceEntries, mode, catchall) {
     const entries = new Array(sourceEntries.length);
     const keys = new Array(sourceEntries.length);
     const keyLookup = makeObjectKeyLookup();
@@ -53,11 +59,35 @@ export function objectSchemaFromEntries(sourceEntries, mode) {
         entries,
         keys,
         keyLookup,
-        mode
+        mode,
+        catchall
     };
 }
 /**
- * @brief read object constructor schema.
+ * @brief Rebuild an object schema with a different unknown-key mode.
+ * @param schema Source object schema.
+ * @param mode Unknown-key policy for the rebuilt schema.
+ * @returns Object schema with identical entries and catchall policy.
+ */
+export function objectSchemaWithMode(schema, mode) {
+    return objectSchemaFromEntries(schema.entries, mode, schema.catchall);
+}
+/**
+ * @brief Rebuild an object schema with an unknown-key validator.
+ * @param schema Source object schema.
+ * @param catchall Schema applied to every undeclared own key.
+ * @returns Object schema that validates extra keys with the supplied schema.
+ */
+export function objectSchemaWithCatchall(schema, catchall) {
+    return objectSchemaFromEntries(schema.entries, schema.mode, catchall);
+}
+/**
+ * @brief Validate the schema value handed to an ObjectGuard constructor.
+ * @details Constructors are public JavaScript entry points, so the guard checks
+ * both the TypeSea schema marker and the object-schema tag before storing the
+ * value. This prevents forged objects from bypassing builder invariants.
+ * @param schema Candidate schema supplied to the constructor.
+ * @returns Object schema accepted by the constructor.
  */
 export function readObjectConstructorSchema(schema) {
     if (!isSchemaValue(schema) || schema.tag !== SchemaTag.Object) {
@@ -66,7 +96,13 @@ export function readObjectConstructorSchema(schema) {
     return schema;
 }
 /**
- * @brief read object method schema.
+ * @brief Extract an object schema from another guard for object-only methods.
+ * @details Methods such as merge and extension compose object shapes. Accepting
+ * a scalar guard here would build an impossible schema, so the check is kept at
+ * the API edge with the caller-facing label in the error message.
+ * @param guard Candidate TypeSea guard.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Object schema owned by the supplied guard.
  */
 export function readObjectMethodSchema(guard, label) {
     const schema = readGuardSchema(guard, label);
@@ -76,7 +112,13 @@ export function readObjectMethodSchema(guard, label) {
     return schema;
 }
 /**
- * @brief merge object schemas.
+ * @brief Merge two object schemas while letting extension keys override base keys.
+ * @details Existing base order is preserved for stable diagnostics and codegen.
+ * Extension-only keys are appended afterward, and the base strict/open mode is
+ * retained so shape extension does not silently change excess-key policy.
+ * @param base Source object schema being extended.
+ * @param extension Object schema whose matching keys replace base entries.
+ * @returns Rebuilt object schema with fresh lookup metadata.
  */
 export function mergeObjectSchemas(base, extension) {
     const entries = [];
@@ -92,10 +134,16 @@ export function mergeObjectSchemas(base, extension) {
             entries.push(entry);
         }
     }
-    return objectSchemaFromEntries(entries, base.mode);
+    return objectSchemaFromEntries(entries, base.mode, extension.catchall ?? base.catchall);
 }
 /**
- * @brief pick object schema.
+ * @brief Build an object schema containing only a validated key selection.
+ * @details The caller has already checked that keys are known and unique. This
+ * function preserves selection order so user-requested projection order is also
+ * the order used by diagnostics and generated object checks.
+ * @param schema Source object schema.
+ * @param keys Validated key selection.
+ * @returns Rebuilt object schema containing only selected entries.
  */
 export function pickObjectSchema(schema, keys) {
     const entries = new Array(keys.length);
@@ -109,10 +157,15 @@ export function pickObjectSchema(schema, keys) {
         }
         entries[index] = entry;
     }
-    return objectSchemaFromEntries(entries, schema.mode);
+    return objectSchemaFromEntries(entries, schema.mode, schema.catchall);
 }
 /**
- * @brief omit object schema.
+ * @brief Build an object schema with a validated key selection removed.
+ * @details Entries not listed for removal keep their original relative order
+ * and presence metadata. The object mode is preserved across the rewrite.
+ * @param schema Source object schema.
+ * @param keys Validated key selection to remove.
+ * @returns Rebuilt object schema without the selected entries.
  */
 export function omitObjectSchema(schema, keys) {
     const entries = [];
@@ -122,10 +175,15 @@ export function omitObjectSchema(schema, keys) {
             entries.push(entry);
         }
     }
-    return objectSchemaFromEntries(entries, schema.mode);
+    return objectSchemaFromEntries(entries, schema.mode, schema.catchall);
 }
 /**
- * @brief partial object schema.
+ * @brief Convert every object entry to optional presence.
+ * @details The child schemas are not wrapped or cloned; only field presence is
+ * rewritten. This keeps value-domain wrappers such as nullable and brand exactly
+ * as they were on the original entries.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with optional entries.
  */
 export function partialObjectSchema(schema) {
     const entries = new Array(schema.entries.length);
@@ -139,14 +197,70 @@ export function partialObjectSchema(schema) {
             };
         }
     }
-    return objectSchemaFromEntries(entries, schema.mode);
+    return objectSchemaFromEntries(entries, schema.mode, schema.catchall);
 }
 /**
- * @brief read object key selection.
+ * @brief Recursively convert object entries to optional presence.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with nested object/container children partialized.
+ * @details Lazy and refinement schemas are treated as semantic barriers because
+ * their runtime callbacks may depend on the original exact value domain.
+ */
+export function deepPartialObjectSchema(schema) {
+    const entries = new Array(schema.entries.length);
+    for (let index = 0; index < schema.entries.length; index += 1) {
+        const entry = schema.entries[index];
+        if (entry !== undefined) {
+            entries[index] = {
+                key: entry.key,
+                schema: deepPartialSchema(entry.schema),
+                presence: PresenceTag.Optional
+            };
+        }
+    }
+    const catchall = schema.catchall === undefined
+        ? undefined
+        : deepPartialSchema(schema.catchall);
+    return objectSchemaFromEntries(entries, schema.mode, catchall);
+}
+/**
+ * @brief Convert every object entry to required presence.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with required entries.
+ * @details Object construction already stripped Optional wrappers into entry
+ * presence metadata. Requiring a field therefore only needs to flip that
+ * metadata back to Required while preserving each value-domain schema.
+ */
+export function requiredObjectSchema(schema) {
+    const entries = new Array(schema.entries.length);
+    for (let index = 0; index < schema.entries.length; index += 1) {
+        const entry = schema.entries[index];
+        if (entry !== undefined) {
+            entries[index] = {
+                key: entry.key,
+                schema: entry.schema,
+                presence: PresenceTag.Required
+            };
+        }
+    }
+    return objectSchemaFromEntries(entries, schema.mode, schema.catchall);
+}
+/**
+ * @brief Validate the key list supplied to object pick and omit operations.
+ * @details The returned array contains only known, unique string keys. This
+ * preflight keeps later schema rewriting simple and prevents silently selecting
+ * fields that were never part of the source object schema.
+ * @param keys Candidate key list from public API calls.
+ * @param schema Object schema whose keys define the valid selection domain.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Ordered key selection accepted by the object builder.
  */
 export function readObjectKeySelection(keys, schema, label) {
+    if (isRecord(keys)) {
+        return readObjectKeyMask(keys, schema, label);
+    }
     if (!isUnknownArray(keys)) {
-        throw new TypeError(`${label} must be an array`);
+        throw new TypeError(`${label} must be an array or key mask`);
     }
     const selected = new Array(keys.length);
     for (let index = 0; index < keys.length; index += 1) {
@@ -165,7 +279,135 @@ export function readObjectKeySelection(keys, schema, label) {
     return selected;
 }
 /**
- * @brief find object entry.
+ * @brief Validate a Zod-style object key mask.
+ * @param mask Candidate object whose selected keys have value true.
+ * @param schema Object schema whose keys define the valid selection domain.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Ordered key selection accepted by object pick and omit.
+ */
+function readObjectKeyMask(mask, schema, label) {
+    const keys = Object.keys(mask);
+    const selected = [];
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
+        if (key === undefined) {
+            continue;
+        }
+        if (mask[key] !== true) {
+            throw new TypeError(`${label} mask values must be true`);
+        }
+        if (!hasObjectKey(schema.keyLookup, key)) {
+            throw new TypeError(`${label} contains unknown object key ${key}`);
+        }
+        selected.push(key);
+    }
+    return selected;
+}
+/**
+ * @brief Recursively partialize pure schema containers.
+ * @param schema Schema to rewrite.
+ * @returns Schema with nested object fields made optional where safe.
+ */
+function deepPartialSchema(schema) {
+    switch (schema.tag) {
+        case SchemaTag.Object:
+            return deepPartialObjectSchema(schema);
+        case SchemaTag.Array:
+            return {
+                tag: SchemaTag.Array,
+                item: deepPartialSchema(schema.item),
+                checks: schema.checks
+            };
+        case SchemaTag.Tuple:
+            return {
+                tag: SchemaTag.Tuple,
+                items: mapDeepPartialSchemas(schema.items),
+                rest: schema.rest === undefined
+                    ? undefined
+                    : deepPartialSchema(schema.rest)
+            };
+        case SchemaTag.Record:
+            return {
+                tag: SchemaTag.Record,
+                value: deepPartialSchema(schema.value)
+            };
+        case SchemaTag.Map:
+            return {
+                tag: SchemaTag.Map,
+                key: deepPartialSchema(schema.key),
+                value: deepPartialSchema(schema.value)
+            };
+        case SchemaTag.Set:
+            return {
+                tag: SchemaTag.Set,
+                item: deepPartialSchema(schema.item)
+            };
+        case SchemaTag.Property:
+            return {
+                tag: SchemaTag.Property,
+                base: deepPartialSchema(schema.base),
+                key: schema.key,
+                value: deepPartialSchema(schema.value)
+            };
+        case SchemaTag.Union:
+            return {
+                tag: SchemaTag.Union,
+                options: mapDeepPartialSchemas(schema.options)
+            };
+        case SchemaTag.Intersection:
+            return {
+                tag: SchemaTag.Intersection,
+                left: deepPartialSchema(schema.left),
+                right: deepPartialSchema(schema.right)
+            };
+        case SchemaTag.Optional:
+            return {
+                tag: SchemaTag.Optional,
+                inner: deepPartialSchema(schema.inner)
+            };
+        case SchemaTag.Undefinedable:
+            return {
+                tag: SchemaTag.Undefinedable,
+                inner: deepPartialSchema(schema.inner)
+            };
+        case SchemaTag.Nullable:
+            return {
+                tag: SchemaTag.Nullable,
+                inner: deepPartialSchema(schema.inner)
+            };
+        case SchemaTag.Brand:
+            return {
+                tag: SchemaTag.Brand,
+                inner: deepPartialSchema(schema.inner),
+                brand: schema.brand
+            };
+        default:
+            return schema;
+    }
+}
+/**
+ * @brief Deep-partialize a schema vector.
+ * @param schemas Source schema vector.
+ * @returns New schema vector preserving index order.
+ */
+function mapDeepPartialSchemas(schemas) {
+    const mapped = new Array(schemas.length);
+    for (let index = 0; index < schemas.length; index += 1) {
+        const schema = schemas[index];
+        if (schema !== undefined) {
+            mapped[index] = deepPartialSchema(schema);
+        }
+    }
+    return mapped;
+}
+/**
+ * @brief Find an object entry by key using the ordered entry vector.
+ * @details The ordered vector is the source of truth for diagnostic and codegen
+ * order. The lookup table proves membership, while this helper recovers the
+ * full entry payload.
+ * @param entries Ordered object entries.
+ * @param key Field name to locate.
+ * @returns Matching object entry, or undefined when absent.
  */
 function findObjectEntry(entries, key) {
     for (let index = 0; index < entries.length; index += 1) {
@@ -177,13 +419,21 @@ function findObjectEntry(entries, key) {
     return undefined;
 }
 /**
- * @brief make object key lookup.
+ * @brief Allocate a null-prototype lookup table for object schema keys.
+ * @details User field names may overlap with Object.prototype properties. A
+ * null-prototype table keeps membership checks data-only and avoids inherited
+ * keys participating in schema construction.
+ * @returns Empty key lookup table used by object schemas.
  */
 function makeObjectKeyLookup() {
     return Object.create(null);
 }
 /**
- * @brief define object key.
+ * @brief Install one immutable key marker into an object-schema lookup table.
+ * @details Object keys are defined as own data properties so membership checks
+ * cannot be influenced by prototype state or later mutation of the table.
+ * @param target Null-prototype key lookup table.
+ * @param key Field name to mark as present.
  */
 function defineObjectKey(target, key) {
     Object.defineProperty(target, key, {
@@ -194,13 +444,23 @@ function defineObjectKey(target, key) {
     });
 }
 /**
- * @brief has object key.
+ * @brief Test object-schema key membership through the prepared lookup table.
+ * @details The table stores immutable true values, so direct indexed access is
+ * sufficient and avoids repeated descriptor allocation during builder work.
+ * @param keyLookup Null-prototype lookup table from the object schema.
+ * @param key Candidate field name.
+ * @returns True when the key belongs to the object schema.
  */
 function hasObjectKey(keyLookup, key) {
     return keyLookup[key] === true;
 }
 /**
- * @brief normalize object entry schema.
+ * @brief Split object-field presence from value-domain schema wrappers.
+ * @details Optional is the only wrapper that changes field presence. Other
+ * wrappers are rebuilt around the normalized inner schema so optionality can
+ * propagate outward without losing nullable, brand, or refinement behavior.
+ * @param schema Field schema supplied by the object builder.
+ * @returns Normalized child schema and required/optional presence tag.
  */
 function normalizeObjectEntrySchema(schema) {
     switch (schema.tag) {
@@ -240,7 +500,14 @@ function normalizeObjectEntrySchema(schema) {
     }
 }
 /**
- * @brief normalize wrapped object entry schema.
+ * @brief Rebuild a wrapper after normalizing its inner object-field schema.
+ * @details When the inner schema stays required, the original wrapper can be
+ * kept unchanged. When optionality is discovered inside, the wrapper is rebuilt
+ * around the normalized child and the field presence becomes optional.
+ * @param inner Inner schema carried by the wrapper.
+ * @param wrap Function that rebuilds the same wrapper around a new child.
+ * @param original Original wrapper schema.
+ * @returns Normalized schema and presence tag for the object field.
  */
 function normalizeWrappedObjectEntrySchema(inner, wrap, original) {
     const normalized = normalizeObjectEntrySchema(inner);

package/dist/builders/object/types.d.ts

@@ -1,63 +1,52 @@
 /**
  * @file types.ts
  * @brief Object builder type algebra.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import type { BaseGuard, Guard, GuardPresence, GuardValue, Infer, Presence } from "../../guard/index.js";
 import type { ObjectModeTag } from "../../kind/index.js";
-/**
- * @brief object shape.
- */
 export type ObjectShape = Readonly<Record<string, Guard<unknown, Presence>>>;
-/**
- * @brief object guard mode.
- */
 export type ObjectGuardMode = typeof ObjectModeTag.Passthrough | typeof ObjectModeTag.Strict;
-/**
- * @brief optional keys.
- */
 export type OptionalKeys<TShape extends ObjectShape> = {
     [TKey in keyof TShape]-?: GuardPresence<TShape[TKey]> extends "optional" ? TKey : never;
 }[keyof TShape];
-/**
- * @brief required keys.
- */
 export type RequiredKeys<TShape extends ObjectShape> = {
     [TKey in keyof TShape]-?: GuardPresence<TShape[TKey]> extends "optional" ? never : TKey;
 }[keyof TShape];
 /**
- * @brief infer object.
+ * @brief Infer required and optional object fields from guard presence tags.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export type InferObject<TShape extends ObjectShape> = Simplify<{
     readonly [TKey in RequiredKeys<TShape>]: Infer<TShape[TKey]>;
 } & {
     readonly [TKey in OptionalKeys<TShape>]?: GuardValue<TShape[TKey]>;
 }>;
-/**
- * @brief simplify.
- */
 export type Simplify<TValue> = {
     readonly [TKey in keyof TValue]: TValue[TKey];
 } & {};
-/**
- * @brief merge object shapes.
- */
 export type MergeObjectShapes<TBase extends ObjectShape, TExtension extends ObjectShape> = Simplify<Omit<TBase, keyof TExtension> & TExtension>;
-/**
- * @brief partial object shape.
- */
 export type PartialObjectShape<TShape extends ObjectShape> = {
     readonly [TKey in keyof TShape]: BaseGuard<GuardValue<TShape[TKey]>, "optional">;
 };
-/**
- * @brief pick object shape.
- */
+export type DeepPartialValue<TValue> = TValue extends (infer TItem)[] ? DeepPartialValue<TItem>[] : TValue extends readonly (infer TItem)[] ? readonly DeepPartialValue<TItem>[] : TValue extends object ? {
+    readonly [TKey in keyof TValue]?: DeepPartialValue<TValue[TKey]>;
+} : TValue;
+export type DeepPartialObjectShape<TShape extends ObjectShape> = {
+    readonly [TKey in keyof TShape]: BaseGuard<DeepPartialValue<GuardValue<TShape[TKey]>>, "optional">;
+};
+export type RequiredObjectShape<TShape extends ObjectShape> = {
+    readonly [TKey in keyof TShape]: BaseGuard<GuardValue<TShape[TKey]>>;
+};
+export type ObjectKeyMask<TShape extends ObjectShape> = Partial<Readonly<Record<StringKeyOf<TShape>, true>>>;
+export type MaskSelectedKeys<TShape extends ObjectShape, TMask extends ObjectKeyMask<TShape>> = {
+    [TKey in keyof TMask]-?: TMask[TKey] extends true ? TKey : never;
+}[keyof TMask];
 export type PickObjectShape<TShape extends ObjectShape, TKey extends string> = Pick<TShape, Extract<keyof TShape, TKey>>;
-/**
- * @brief omit object shape.
- */
+export type PickObjectShapeByMask<TShape extends ObjectShape, TMask extends ObjectKeyMask<TShape>> = Pick<TShape, Extract<keyof TShape, MaskSelectedKeys<TShape, TMask>>>;
 export type OmitObjectShape<TShape extends ObjectShape, TKey extends string> = Omit<TShape, Extract<keyof TShape, TKey>>;
-/**
- * @brief string key of.
- */
+export type OmitObjectShapeByMask<TShape extends ObjectShape, TMask extends ObjectKeyMask<TShape>> = Omit<TShape, Extract<keyof TShape, MaskSelectedKeys<TShape, TMask>>>;
 export type StringKeyOf<TValue> = Extract<keyof TValue, string>;
 //# sourceMappingURL=types.d.ts.map

package/dist/builders/object/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/object/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,OAAO,aAAa,CAAC,WAAW,GAChC,OAAO,aAAa,CAAC,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,WAAW,IAAI;KACpD,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,UAAU,GACpE,IAAI,GACJ,KAAK;CACV,CAAC,MAAM,MAAM,CAAC,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,WAAW,IAAI;KACpD,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,UAAU,GACpE,KAAK,GACL,IAAI;CACT,CAAC,MAAM,MAAM,CAAC,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,WAAW,IAAI,QAAQ,CAC5D;IACE,QAAQ,EAAE,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC7D,GAAG;IACF,QAAQ,EAAE,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACnE,CACF,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,IAAI;IAC7B,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;CAC9C,GAAG,EAAE,CAAC;AAEP;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAC3B,KAAK,SAAS,WAAW,EACzB,UAAU,SAAS,WAAW,IAC5B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,UAAU,CAAC,GAAG,UAAU,CAAC,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,MAAM,SAAS,WAAW,IAAI;IAC3D,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC;CACjF,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,CACzB,MAAM,SAAS,WAAW,EAC1B,IAAI,SAAS,MAAM,IACjB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,eAAe,CACzB,MAAM,SAAS,WAAW,EAC1B,IAAI,SAAS,MAAM,IACjB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/object/types.ts"],"names":[],"mappings":"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"}