typesea 0.1.0 → 0.3.0

package/dist/async/index.js

@@ -4,23 +4,23 @@ import { freezeIssueArray, makeIssue } from "../issue/index.js";
 import { err, ok } from "../result/index.js";
 import { freezeSchema, isSchemaValue } from "../schema/index.js";
 /**
- * @brief async decoder run symbol.
+ * @brief Private runner slot for async decoder instances.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 const AsyncDecoderRunSymbol = Symbol("TypeSea.asyncDecoder.run");
 /**
- * @brief constructed async decoders.
+ * @brief Real async decoder instances tracked without extending object lifetime.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
  */
 const constructedAsyncDecoders = new WeakSet();
 /**
- * @brief base async decoder.
- * @details Owns its state directly; methods expose receiver checks and explicit result flow.
- * @invariant Construction leaves the instance in a fully usable state before it escapes.
+ * @brief Frozen wrapper around one async decode runner.
+ * @details Receiver validation mirrors BaseDecoder so detached method calls do
+ * not bypass TypeSea's object construction checks.
  */
 export class BaseAsyncDecoder {
-    /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor(run) {
         if (typeof run !== "function") {
             throw new TypeError("async decoder run must be a function");
@@ -29,15 +29,9 @@ export class BaseAsyncDecoder {
         constructedAsyncDecoders.add(this);
         Object.freeze(this);
     }
-    /**
-     * @brief decode async.
-             */
     decodeAsync(value) {
         return readAsyncDecoderRunner(this, "async decoder receiver")(value);
     }
-    /**
-     * @brief refine async.
-             */
     refineAsync(predicate, name) {
         if (typeof predicate !== "function") {
             throw new TypeError("async refinement predicate must be a function");
@@ -58,9 +52,6 @@ export class BaseAsyncDecoder {
             return failRefinement(name, decoded.value);
         });
     }
-    /**
-     * @brief transform async.
-           */
     transformAsync(mapper) {
         if (typeof mapper !== "function") {
             throw new TypeError("async transform mapper must be a function");
@@ -74,9 +65,6 @@ export class BaseAsyncDecoder {
             return ok(await mapper(decoded.value));
         });
     }
-    /**
-     * @brief pipe async.
-           */
     pipeAsync(next) {
         const run = readAsyncDecoderRunner(this, "async pipe receiver");
         const nextRun = readAsyncDecodeSourceRunner(next, "async pipe target");
@@ -90,44 +78,58 @@ export class BaseAsyncDecoder {
     }
 }
 /**
- * @brief async decoder.
+ * @brief Execute async decoder.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncDecoder(source) {
     return makeAsyncDecoder(source);
 }
 /**
- * @brief async refine.
+ * @brief Execute async refine.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncRefine(source, predicate, name) {
     return makeAsyncDecoder(source).refineAsync(predicate, name);
 }
 /**
- * @brief async transform.
+ * @brief Execute async transform.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncTransform(source, mapper) {
     return makeAsyncDecoder(source).transformAsync(mapper);
 }
 /**
- * @brief async pipe.
+ * @brief Execute async pipe.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function asyncPipe(source, next) {
     return makeAsyncDecoder(source).pipeAsync(next);
 }
 /**
- * @brief is async decoder value.
+ * @brief Check async decoder value.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function isAsyncDecoderValue(value) {
     return isConstructedAsyncDecoder(value);
 }
 /**
- * @brief make async decoder.
+ * @brief Construct an async decoder from a guard, decoder, or async decoder.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param source Source pipeline element.
+ * @returns Async decoder wrapping the normalized runner.
  */
 function makeAsyncDecoder(source) {
     const run = readAsyncDecodeSourceRunner(source, "async decoder source");
     return new BaseAsyncDecoder(run);
 }
 /**
- * @brief read async decode source runner.
+ * @brief Resolve an async decode source into a promise-returning runner.
+ * @param source Candidate source supplied to async decoder composition.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Runner that always reports through a Promise.
+ * @details Sync decoders and guards are wrapped with Promise.resolve so the
+ * outer async pipeline has one uniform scheduling shape.
  */
 function readAsyncDecodeSourceRunner(source, label) {
     if (isConstructedAsyncDecoder(source)) {
@@ -140,7 +142,13 @@ function readAsyncDecodeSourceRunner(source, label) {
     return (value) => Promise.resolve(checkSchema(schema, value));
 }
 /**
- * @brief read async decoder runner.
+ * @brief Read the private runner from a constructed async decoder.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate async decoder object.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Stored async decode runner.
+ * @throws TypeError when the value was not registered by the constructor.
  */
 function readAsyncDecoderRunner(value, label) {
     if (!isConstructedAsyncDecoder(value)) {
@@ -149,26 +157,41 @@ function readAsyncDecoderRunner(value, label) {
     return value[AsyncDecoderRunSymbol];
 }
 /**
- * @brief is constructed async decoder.
+ * @brief Test async decoder identity through the private registry.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate async decoder.
+ * @returns True when TypeSea constructed the instance.
  */
 function isConstructedAsyncDecoder(value) {
     return isRecord(value) && constructedAsyncDecoders.has(value);
 }
 /**
- * @brief read guard schema.
+ * @brief Normalize a guard-like source used in an async decode pipeline.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate guard-like source.
+ * @param label Message prefix for TypeError diagnostics.
+ * @returns Frozen schema used by the promise-wrapped check runner.
+ * @throws TypeError when the schema slot is absent or malformed.
  */
 function readGuardSchema(value, label) {
     if (!isRecord(value)) {
         throw new TypeError(`${label} must be a TypeSea guard or decoder`);
     }
-    const schema = value["schema"];
+    const schema = readOwnDataProperty(value, "schema");
     if (!isSchemaValue(schema)) {
         throw new TypeError(`${label} must contain a valid TypeSea schema`);
     }
     return freezeSchema(schema);
 }
 /**
- * @brief fail refinement.
+ * @brief Build a single-issue failure for an async refinement.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param name Diagnostic refinement name.
+ * @param value Runtime value rejected by the predicate.
+ * @returns Failure result with a root-level refinement issue.
  */
 function failRefinement(name, value) {
     return err(freezeIssueArray([
@@ -176,7 +199,11 @@ function failRefinement(name, value) {
     ]));
 }
 /**
- * @brief actual type.
+ * @brief Produce the compact runtime type label used in async decoder issues.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Runtime value.
+ * @returns Stable diagnostic type name.
  */
 function actualType(value) {
     if (value === null) {
@@ -197,13 +224,23 @@ function actualType(value) {
     return typeof value;
 }
 /**
- * @brief is strict true.
+ * @brief Accept only the literal boolean success value from async predicates.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Predicate return value.
+ * @returns True only for `true`.
  */
 function isStrictTrue(value) {
     return value === true;
 }
 /**
- * @brief define readonly property.
+ * @brief Define one immutable async decoder instance slot.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param target Async decoder instance.
+ * @param key Public key or private symbol.
+ * @param value Stored field value.
+ * @param enumerable Whether the field should appear in enumeration.
  */
 function defineReadonlyProperty(target, key, value, enumerable) {
     Object.defineProperty(target, key, {
@@ -214,8 +251,28 @@ function defineReadonlyProperty(target, key, value, enumerable) {
     });
 }
 /**
- * @brief is record.
+ * @brief Accept objects that can carry async decoder or guard fields.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Candidate object.
+ * @returns True for non-array objects.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * @brief Read one own data slot from an async decode source.
+ * @details Decoder helpers keep validation failures explicit in Result values while
+ * preserving the original input value.
+ * @param value Object being normalized.
+ * @param key Field name or symbol.
+ * @returns Stored field value, or undefined when absent.
+ */
+function readOwnDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined ||
+        !Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+        return undefined;
+    }
+    return descriptor.value;
+}

package/dist/builders/composite.d.ts

@@ -1,31 +1,65 @@
 /**
  * @file composite.ts
  * @brief Composite guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
-import { BaseGuard, type Guard, type Infer, type Presence } from "../guard/index.js";
-import type { DiscriminatedUnionCases, InferTuple, TupleShape, UnionInput } from "./types.js";
+import { ArrayGuard, BaseGuard, type Guard, type Infer, type Presence } from "../guard/index.js";
+import type { DiscriminatedUnionCases, InferTuple, InferTupleWithRest, TupleShape, UnionInput } from "./types.js";
 /**
- * @brief array.
+ * @brief Build an array guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param item Guard used for each logical array slot.
+ * @returns Fresh array guard.
  */
-export declare function array<TGuard extends Guard<unknown, Presence>>(item: TGuard): BaseGuard<Infer<TGuard>[]>;
+export declare function array<TGuard extends Guard<unknown, Presence>>(item: TGuard): ArrayGuard<Infer<TGuard>>;
 /**
- * @brief tuple.
+ * @brief Build a fixed-length tuple guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param shape Ordered guard list for tuple indexes.
+ * @returns Fresh tuple guard preserving item order.
+ * @throws TypeError when shape is not an array-like tuple input.
  */
 export declare function tuple<const TShape extends TupleShape>(shape: TShape): BaseGuard<InferTuple<TShape>>;
+export declare function tuple<const TShape extends TupleShape, TRest extends Guard<unknown, Presence>>(shape: TShape, rest: TRest): BaseGuard<InferTupleWithRest<TShape, TRest>>;
 /**
- * @brief record.
+ * @brief Build a string-keyed record guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param value Guard used for each enumerable own record value.
+ * @returns Fresh record guard.
  */
 export declare function record<TGuard extends Guard<unknown, Presence>>(value: TGuard): BaseGuard<Readonly<Record<string, Infer<TGuard>>>>;
+export declare function map<TKey extends Guard<unknown, Presence>, TValue extends Guard<unknown, Presence>>(key: TKey, value: TValue): BaseGuard<ReadonlyMap<Infer<TKey>, Infer<TValue>>>;
+export declare function set<TItem extends Guard<unknown, Presence>>(item: TItem): BaseGuard<ReadonlySet<Infer<TItem>>>;
 /**
- * @brief union.
+ * @brief Build a union guard from one or more guards.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guards Non-empty guard list.
+ * @returns Fresh union guard.
+ * @throws TypeError when called without guards.
  */
 export declare function union<const TGuards extends UnionInput>(...guards: TGuards): BaseGuard<Infer<TGuards[number]>>;
 /**
- * @brief intersect.
+ * @brief Build an intersection guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param left Left-hand guard.
+ * @param right Right-hand guard.
+ * @returns Fresh guard requiring both schemas to accept the value.
  */
 export declare function intersect<TLeft extends Guard<unknown, Presence>, TRight extends Guard<unknown, Presence>>(left: TLeft, right: TRight): BaseGuard<Infer<TLeft> & Infer<TRight>>;
 /**
- * @brief discriminated union.
+ * @brief Build a union whose branch can be selected by one literal property.
+ * @details This shape lowers to a dispatch table instead of a linear union
+ * scan, which is the fast path object unions should use.
+ * @param key Discriminant object key.
+ * @param cases Record from discriminant literal to branch guard.
+ * @returns Fresh discriminated-union guard.
+ * @throws TypeError when cases are empty or branch schemas do not require the tag.
  */
 export declare function discriminatedUnion<const TKey extends string, const TCases extends Readonly<Record<string, Guard<unknown, Presence>>>>(key: TKey, cases: TCases & DiscriminatedUnionCases<TKey, TCases>): BaseGuard<Infer<TCases[keyof TCases]>>;
 //# sourceMappingURL=composite.d.ts.map

package/dist/builders/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/builders/composite.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EACL,SAAS,EACT,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EACV,uBAAuB,EACvB,UAAU,EACV,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC3D,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAK5B;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,MAAM,SAAS,UAAU,EACnD,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAc/B;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC5D,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAKpD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,UAAU,EACpD,GAAG,MAAM,EAAE,OAAO,GACjB,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAanC;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACtC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAEvC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAMzC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,CAAC,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAEvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,GACpD,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CA6BxC"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/builders/composite.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACH,UAAU,EACV,SAAS,EACT,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,QAAQ,EAChB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EACR,uBAAuB,EACvB,UAAU,EACV,kBAAkB,EAClB,UAAU,EACV,UAAU,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACzD,IAAI,EAAE,MAAM,GACb,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAM3B;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,MAAM,SAAS,UAAU,EACjD,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAEjC,wBAAgB,KAAK,CACjB,KAAK,CAAC,MAAM,SAAS,UAAU,EAC/B,KAAK,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAEtC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,KAAK,GACZ,SAAS,CAAC,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AA4BhD;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC1D,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAKpD;AAED,wBAAgB,GAAG,CACf,IAAI,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACrC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAEvC,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAMpD;AAED,wBAAgB,GAAG,CAAC,KAAK,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACtD,IAAI,EAAE,KAAK,GACZ,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAKtC;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,UAAU,EAClD,GAAG,MAAM,EAAE,OAAO,GACnB,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAiBnC;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACrB,KAAK,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACtC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAEvC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAMzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,CAAC,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAEvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,GACtD,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CAiCxC"}

package/dist/builders/composite.js

@@ -1,27 +1,35 @@
 /**
  * @file composite.ts
  * @brief Composite guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { PresenceTag, SchemaTag } from "../kind/index.js";
-import { BaseGuard } from "../guard/index.js";
+import { ArrayGuard, BaseGuard } from "../guard/index.js";
 import { isRecord, readGuardSchema } from "../internal/index.js";
 /**
- * @brief array.
+ * @brief Build an array guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param item Guard used for each logical array slot.
+ * @returns Fresh array guard.
  */
 export function array(item) {
-    return new BaseGuard({
+    return new ArrayGuard({
         tag: SchemaTag.Array,
-        item: readGuardSchema(item, "array item")
+        item: readGuardSchema(item, "array item"),
+        checks: []
     });
 }
-/**
- * @brief tuple.
- */
-export function tuple(shape) {
+export function tuple(shape, rest) {
     const rawShape = shape;
     if (!Array.isArray(rawShape)) {
         throw new TypeError("tuple shape must be an array");
     }
+    /*
+     * Tuple indexes are read in order and stored as schemas, not guard objects,
+     * so later validation cannot observe mutation on user-held guard wrappers.
+     */
     const items = new Array(shape.length);
     for (let index = 0; index < shape.length; index += 1) {
         const guard = shape[index];
@@ -29,11 +37,18 @@ export function tuple(shape) {
     }
     return new BaseGuard({
         tag: SchemaTag.Tuple,
-        items
+        items,
+        rest: rest === undefined
+            ? undefined
+            : readGuardSchema(rest, "tuple rest")
     });
 }
 /**
- * @brief record.
+ * @brief Build a string-keyed record guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param value Guard used for each enumerable own record value.
+ * @returns Fresh record guard.
  */
 export function record(value) {
     return new BaseGuard({
@@ -41,13 +56,35 @@ export function record(value) {
         value: readGuardSchema(value, "record value")
     });
 }
+export function map(key, value) {
+    return new BaseGuard({
+        tag: SchemaTag.Map,
+        key: readGuardSchema(key, "map key"),
+        value: readGuardSchema(value, "map value")
+    });
+}
+export function set(item) {
+    return new BaseGuard({
+        tag: SchemaTag.Set,
+        item: readGuardSchema(item, "set item")
+    });
+}
 /**
- * @brief union.
+ * @brief Build a union guard from one or more guards.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guards Non-empty guard list.
+ * @returns Fresh union guard.
+ * @throws TypeError when called without guards.
  */
 export function union(...guards) {
     if (guards.length === 0) {
         throw new TypeError("union requires at least one guard");
     }
+    /*
+     * Preserve option order. Diagnostics and generated dispatch use this order
+     * when probing branches and constructing graph children.
+     */
     const options = new Array(guards.length);
     for (let index = 0; index < guards.length; index += 1) {
         const guard = guards[index];
@@ -59,7 +96,12 @@ export function union(...guards) {
     });
 }
 /**
- * @brief intersect.
+ * @brief Build an intersection guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param left Left-hand guard.
+ * @param right Right-hand guard.
+ * @returns Fresh guard requiring both schemas to accept the value.
  */
 export function intersect(left, right) {
     return new BaseGuard({
@@ -69,7 +111,13 @@ export function intersect(left, right) {
     });
 }
 /**
- * @brief discriminated union.
+ * @brief Build a union whose branch can be selected by one literal property.
+ * @details This shape lowers to a dispatch table instead of a linear union
+ * scan, which is the fast path object unions should use.
+ * @param key Discriminant object key.
+ * @param cases Record from discriminant literal to branch guard.
+ * @returns Fresh discriminated-union guard.
+ * @throws TypeError when cases are empty or branch schemas do not require the tag.
  */
 export function discriminatedUnion(key, cases) {
     if (typeof key !== "string") {
@@ -82,6 +130,10 @@ export function discriminatedUnion(key, cases) {
     if (entries.length === 0) {
         throw new TypeError("discriminated union requires at least one case");
     }
+    /*
+     * Object.entries defines the dispatch order. The literal string is taken
+     * from the case key and must be required by the branch schema below.
+     */
     const unionCases = new Array(entries.length);
     for (let index = 0; index < entries.length; index += 1) {
         const pair = entries[index];
@@ -102,7 +154,15 @@ export function discriminatedUnion(key, cases) {
     });
 }
 /**
- * @brief read discriminated union case schema.
+ * @brief Extract and validate one discriminated-union branch schema.
+ * @details A branch is accepted only when its object schema itself proves the
+ * discriminant literal. Without that proof, dispatch by table key could select
+ * a branch whose validator later accepts a different tag shape.
+ * @param guard Branch guard from the cases table.
+ * @param key Discriminant key shared by all cases.
+ * @param literal Literal value assigned to this case.
+ * @returns Branch schema after discriminant proof.
+ * @throws TypeError when the branch does not require its literal tag.
  */
 function readDiscriminatedUnionCaseSchema(guard, key, literal) {
     const schema = readGuardSchema(guard, `case ${literal}`);
@@ -112,7 +172,15 @@ function readDiscriminatedUnionCaseSchema(guard, key, literal) {
     return schema;
 }
 /**
- * @brief case requires discriminant.
+ * @brief Prove that a branch structurally requires the requested tag literal.
+ * @details Dispatch tables are only sound when accepting a branch implies that
+ * the discriminant key is present and equal to its table literal. The proof is
+ * intentionally structural and refuses schemas whose tag requirement is hidden
+ * behind runtime-only logic.
+ * @param schema Branch schema to inspect.
+ * @param key Discriminant key.
+ * @param literal Required literal value.
+ * @returns True when the branch structurally requires `key: literal`.
  */
 function caseRequiresDiscriminant(schema, key, literal) {
     const objectSchema = unwrapCaseObjectSchema(schema);
@@ -131,13 +199,22 @@ function caseRequiresDiscriminant(schema, key, literal) {
     return false;
 }
 /**
- * @brief unwrap case object schema.
+ * @brief Find the object schema that can prove a discriminant requirement.
+ * @details Brand and refinement wrappers do not change object shape, and either
+ * side of an intersection may supply the tag field. Other schema forms cannot
+ * provide the required object-field proof.
+ * @param schema Branch schema possibly wrapped by brand/refine/intersection.
+ * @returns Object schema used for discriminant inspection, or undefined.
  */
 function unwrapCaseObjectSchema(schema) {
     switch (schema.tag) {
         case SchemaTag.Object:
             return schema;
         case SchemaTag.Intersection:
+            /*
+             * A discriminant can be supplied by either side of an intersection.
+             * Search both sides before rejecting the case.
+             */
             return unwrapCaseObjectSchema(schema.left) ?? unwrapCaseObjectSchema(schema.right);
         case SchemaTag.Brand:
         case SchemaTag.Refine:
@@ -147,7 +224,13 @@ function unwrapCaseObjectSchema(schema) {
     }
 }
 /**
- * @brief schema requires literal.
+ * @brief Prove that a discriminant field schema accepts only one literal.
+ * @details Intersections may prove the literal from either side, while brand
+ * and refinement wrappers preserve the underlying literal requirement. Broader
+ * schemas are rejected because they would make table dispatch unsound.
+ * @param schema Schema attached to the discriminant property.
+ * @param literal Literal value required by the case.
+ * @returns True when the schema accepts only the requested literal.
  */
 function schemaRequiresLiteral(schema, literal) {
     switch (schema.tag) {

package/dist/builders/index.d.ts

@@ -1,11 +1,14 @@
 /**
  * @file index.ts
  * @brief Public builder module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
-export { array, discriminatedUnion, intersect, record, tuple, union } from "./composite.js";
-export { lazy, nullable, optional, refine, undefinedable } from "./modifier.js";
-export { ObjectGuard, extend, object, omit, partial, pick, strictObject, type InferObject, type MergeObjectShapes, type ObjectGuardMode, type ObjectShape, type OmitObjectShape, type PartialObjectShape, type PickObjectShape } from "./object/index.js";
-export { bigintGuard, literal, neverGuard, symbolGuard, unknownGuard } from "./scalar.js";
+export { array, discriminatedUnion, intersect, map, record, set, tuple, union } from "./composite.js";
+export { lazy, nullable, nullish, optional, refine, undefinedable } from "./modifier.js";
+export { ObjectGuard, catchall, deepPartial, extend, merge, object, omit, partial, passthrough, pick, required, safeExtend, strict, strictObject, strip, type DeepPartialObjectShape, type DeepPartialValue, type InferObject, type MaskSelectedKeys, type MergeObjectShapes, type ObjectKeyMask, type ObjectGuardMode, type ObjectShape, type OmitObjectShape, type OmitObjectShapeByMask, type PartialObjectShape, type PickObjectShape, type PickObjectShapeByMask, type RequiredObjectShape } from "./object/index.js";
+export { bigintGuard, booleanGuard, dateGuard, enumValues, enumValues as enum, literal, neverGuard, nullGuard, numberGuard, symbolGuard, stringGuard, unknownGuard, undefinedGuard, voidGuard, type EnumValues } from "./scalar.js";
+export { instanceOf, json, property, type InstanceConstructor, type JsonValue } from "./runtime.js";
 export { t } from "./table.js";
-export type { InferTuple, TupleShape } from "./types.js";
+export type { InferTuple, InferTupleWithRest, TupleShape } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/builders/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,KAAK,EACL,kBAAkB,EAClB,SAAS,EACT,MAAM,EACN,KAAK,EACL,KAAK,EACN,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,EACX,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAC/B,YAAY,EACV,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,KAAK,EACL,kBAAkB,EAClB,SAAS,EACT,GAAG,EACH,MAAM,EACN,GAAG,EACH,KAAK,EACL,KAAK,EACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACH,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,MAAM,EACN,aAAa,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,WAAW,EACX,QAAQ,EACR,WAAW,EACX,MAAM,EACN,KAAK,EACL,MAAM,EACN,IAAI,EACJ,OAAO,EACP,WAAW,EACX,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,MAAM,EACN,YAAY,EACZ,KAAK,EACL,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EACV,UAAU,IAAI,IAAI,EAClB,OAAO,EACP,UAAU,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,SAAS,EACT,KAAK,UAAU,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACH,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAC/B,YAAY,EACR,UAAU,EACV,kBAAkB,EAClB,UAAU,EACb,MAAM,YAAY,CAAC"}

package/dist/builders/index.js

@@ -1,9 +1,12 @@
 /**
  * @file index.ts
  * @brief Public builder module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
-export { array, discriminatedUnion, intersect, record, tuple, union } from "./composite.js";
-export { lazy, nullable, optional, refine, undefinedable } from "./modifier.js";
-export { ObjectGuard, extend, object, omit, partial, pick, strictObject } from "./object/index.js";
-export { bigintGuard, literal, neverGuard, symbolGuard, unknownGuard } from "./scalar.js";
+export { array, discriminatedUnion, intersect, map, record, set, tuple, union } from "./composite.js";
+export { lazy, nullable, nullish, optional, refine, undefinedable } from "./modifier.js";
+export { ObjectGuard, catchall, deepPartial, extend, merge, object, omit, partial, passthrough, pick, required, safeExtend, strict, strictObject, strip } from "./object/index.js";
+export { bigintGuard, booleanGuard, dateGuard, enumValues, enumValues as enum, literal, neverGuard, nullGuard, numberGuard, symbolGuard, stringGuard, unknownGuard, undefinedGuard, voidGuard } from "./scalar.js";
+export { instanceOf, json, property } from "./runtime.js";
 export { t } from "./table.js";