typesea 0.1.0 → 0.3.0

package/dist/guard/index.d.ts

@@ -1,8 +1,12 @@
 /**
  * @file index.ts
  * @brief Public guard module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { BaseGuard } from "./base.js";
+export { ArrayGuard } from "./array.js";
+export { DateGuard } from "./date.js";
 export { TypeSeaAssertionError } from "./error.js";
 export { NumberGuard } from "./number.js";
 export { StringGuard } from "./string.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACV,KAAK,EACL,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACR,YAAY,EACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACR,KAAK,EACL,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACR,YAAY,EACf,MAAM,YAAY,CAAC"}

package/dist/guard/index.js

@@ -1,8 +1,12 @@
 /**
  * @file index.ts
  * @brief Public guard module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { BaseGuard } from "./base.js";
+export { ArrayGuard } from "./array.js";
+export { DateGuard } from "./date.js";
 export { TypeSeaAssertionError } from "./error.js";
 export { NumberGuard } from "./number.js";
 export { StringGuard } from "./string.js";

package/dist/guard/number.d.ts

@@ -1,32 +1,107 @@
 /**
  * @file number.ts
  * @brief Number guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import type { NumberSchema } from "../schema/index.js";
 import { BaseGuard } from "./base.js";
 import type { Presence } from "./types.js";
 /**
- * @brief number guard.
- * @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 Persistent builder for finite number predicates.
+ * @details Bounds are normalized before entering the schema so the evaluator
+ * and compiler never have to defend against NaN or infinities later.
  */
 export declare class NumberGuard<TPresence extends Presence = "required"> extends BaseGuard<number, TPresence> {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a frozen number guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema Number schema backing this guard.
      */
     constructor(schema: NumberSchema);
     /**
-     * @brief int.
-         */
+     * @brief Require finite numbers to be integers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh NumberGuard with an appended integer check.
+     */
     int(): NumberGuard<TPresence>;
     /**
-     * @brief gte.
-           */
+     * @brief Add an inclusive lower bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gte check.
+     */
     gte(value: number): NumberGuard<TPresence>;
     /**
-     * @brief lte.
-           */
+     * @brief Alias for an inclusive lower bound.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gte check.
+     */
+    min(value: number): NumberGuard<TPresence>;
+    /**
+     * @brief Add an inclusive upper bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lte check.
+     */
     lte(value: number): NumberGuard<TPresence>;
+    /**
+     * @brief Alias for an inclusive upper bound.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lte check.
+     */
+    max(value: number): NumberGuard<TPresence>;
+    /**
+     * @brief Add an exclusive lower bound.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gt check.
+     */
+    gt(value: number): NumberGuard<TPresence>;
+    /**
+     * @brief Add an exclusive upper bound.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lt check.
+     */
+    lt(value: number): NumberGuard<TPresence>;
+    /**
+     * @brief Require a number to be divisible by a positive finite divisor.
+     * @param value Positive finite divisor.
+     * @returns Fresh NumberGuard with an appended multipleOf check.
+     */
+    multipleOf(value: number): NumberGuard<TPresence>;
+    /**
+     * @brief Require a number greater than zero.
+     * @returns Fresh NumberGuard with `gt(0)`.
+     */
+    positive(): NumberGuard<TPresence>;
+    /**
+     * @brief Require a number greater than or equal to zero.
+     * @returns Fresh NumberGuard with `gte(0)`.
+     */
+    nonnegative(): NumberGuard<TPresence>;
+    /**
+     * @brief Require a number less than zero.
+     * @returns Fresh NumberGuard with `lt(0)`.
+     */
+    negative(): NumberGuard<TPresence>;
+    /**
+     * @brief Require a number less than or equal to zero.
+     * @returns Fresh NumberGuard with `lte(0)`.
+     */
+    nonpositive(): NumberGuard<TPresence>;
+    /**
+     * @brief Keep the explicit Zod-compatible finite marker.
+     * @returns This guard because TypeSea numbers are finite by construction.
+     */
+    finite(): this;
+    /**
+     * @brief Require a safe JavaScript integer.
+     * @returns Fresh NumberGuard constrained to Number.isSafeInteger domain.
+     */
+    safe(): NumberGuard<TPresence>;
 }
 //# sourceMappingURL=number.d.ts.map

package/dist/guard/number.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../src/guard/number.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,WAAW,CACtB,SAAS,SAAS,QAAQ,GAAG,UAAU,CACvC,SAAQ,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAEpC;;;OAGG;gBACgB,MAAM,EAAE,YAAY;IAKvC;;WAEO;IACA,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC;IAapC;;aAES;IACF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAejD;;aAES;IACF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;CAclD"}
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../src/guard/number.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,WAAW,CACpB,SAAS,SAAS,QAAQ,GAAG,UAAU,CACzC,SAAQ,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAElC;;;;;OAKG;gBACgB,MAAM,EAAE,YAAY;IAKvC;;;;;OAKG;IACI,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC;IAapC;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAmBjD;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAIjD;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAejD;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAIjD;;;;OAIG;IACI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAehD;;;;OAIG;IACI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAehD;;;;OAIG;IACI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAexD;;;OAGG;IACI,QAAQ,IAAI,WAAW,CAAC,SAAS,CAAC;IAIzC;;;OAGG;IACI,WAAW,IAAI,WAAW,CAAC,SAAS,CAAC;IAI5C;;;OAGG;IACI,QAAQ,IAAI,WAAW,CAAC,SAAS,CAAC;IAIzC;;;OAGG;IACI,WAAW,IAAI,WAAW,CAAC,SAAS,CAAC;IAI5C;;;OAGG;IACI,MAAM,IAAI,IAAI;IAIrB;;;OAGG;IACI,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC;CAKxC"}

package/dist/guard/number.js

@@ -1,27 +1,34 @@
 /**
  * @file number.ts
  * @brief Number guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { NumberCheckTag, SchemaTag } from "../kind/index.js";
 import { BaseGuard } from "./base.js";
 import { checkFiniteNumberBound, readNumberConstructorSchema, readNumberMethodSchema } from "./read.js";
 /**
- * @brief number guard.
- * @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 Persistent builder for finite number predicates.
+ * @details Bounds are normalized before entering the schema so the evaluator
+ * and compiler never have to defend against NaN or infinities later.
  */
 export class NumberGuard extends BaseGuard {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a frozen number guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema Number schema backing this guard.
      */
     constructor(schema) {
         super(readNumberConstructorSchema(schema));
         Object.freeze(this);
     }
     /**
-     * @brief int.
-         */
+     * @brief Require finite numbers to be integers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh NumberGuard with an appended integer check.
+     */
     int() {
         const schema = readNumberMethodSchema(this, "number int receiver");
         return new NumberGuard({
@@ -35,11 +42,19 @@ export class NumberGuard extends BaseGuard {
         });
     }
     /**
-     * @brief gte.
-           */
+     * @brief Add an inclusive lower bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gte check.
+     */
     gte(value) {
         const schema = readNumberMethodSchema(this, "number gte receiver");
         const bound = checkFiniteNumberBound(value, "gte");
+        /*
+         * Bounds are normalized before schema construction so interpreters and
+         * compilers never need to handle NaN or infinity inside hot validation.
+         */
         return new NumberGuard({
             tag: SchemaTag.Number,
             checks: [
@@ -52,8 +67,20 @@ export class NumberGuard extends BaseGuard {
         });
     }
     /**
-     * @brief lte.
-           */
+     * @brief Alias for an inclusive lower bound.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gte check.
+     */
+    min(value) {
+        return this.gte(value);
+    }
+    /**
+     * @brief Add an inclusive upper bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lte check.
+     */
     lte(value) {
         const schema = readNumberMethodSchema(this, "number lte receiver");
         const bound = checkFiniteNumberBound(value, "lte");
@@ -68,4 +95,125 @@ export class NumberGuard extends BaseGuard {
             ]
         });
     }
+    /**
+     * @brief Alias for an inclusive upper bound.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lte check.
+     */
+    max(value) {
+        return this.lte(value);
+    }
+    /**
+     * @brief Add an exclusive lower bound.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gt check.
+     */
+    gt(value) {
+        const schema = readNumberMethodSchema(this, "number gt receiver");
+        const bound = checkFiniteNumberBound(value, "gt");
+        return new NumberGuard({
+            tag: SchemaTag.Number,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: NumberCheckTag.Gt,
+                    value: bound
+                }
+            ]
+        });
+    }
+    /**
+     * @brief Add an exclusive upper bound.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lt check.
+     */
+    lt(value) {
+        const schema = readNumberMethodSchema(this, "number lt receiver");
+        const bound = checkFiniteNumberBound(value, "lt");
+        return new NumberGuard({
+            tag: SchemaTag.Number,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: NumberCheckTag.Lt,
+                    value: bound
+                }
+            ]
+        });
+    }
+    /**
+     * @brief Require a number to be divisible by a positive finite divisor.
+     * @param value Positive finite divisor.
+     * @returns Fresh NumberGuard with an appended multipleOf check.
+     */
+    multipleOf(value) {
+        const schema = readNumberMethodSchema(this, "number multipleOf receiver");
+        const divisor = checkPositiveFiniteNumber(value, "multipleOf");
+        return new NumberGuard({
+            tag: SchemaTag.Number,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: NumberCheckTag.MultipleOf,
+                    value: divisor
+                }
+            ]
+        });
+    }
+    /**
+     * @brief Require a number greater than zero.
+     * @returns Fresh NumberGuard with `gt(0)`.
+     */
+    positive() {
+        return this.gt(0);
+    }
+    /**
+     * @brief Require a number greater than or equal to zero.
+     * @returns Fresh NumberGuard with `gte(0)`.
+     */
+    nonnegative() {
+        return this.gte(0);
+    }
+    /**
+     * @brief Require a number less than zero.
+     * @returns Fresh NumberGuard with `lt(0)`.
+     */
+    negative() {
+        return this.lt(0);
+    }
+    /**
+     * @brief Require a number less than or equal to zero.
+     * @returns Fresh NumberGuard with `lte(0)`.
+     */
+    nonpositive() {
+        return this.lte(0);
+    }
+    /**
+     * @brief Keep the explicit Zod-compatible finite marker.
+     * @returns This guard because TypeSea numbers are finite by construction.
+     */
+    finite() {
+        return this;
+    }
+    /**
+     * @brief Require a safe JavaScript integer.
+     * @returns Fresh NumberGuard constrained to Number.isSafeInteger domain.
+     */
+    safe() {
+        return this.int()
+            .gte(Number.MIN_SAFE_INTEGER)
+            .lte(Number.MAX_SAFE_INTEGER);
+    }
+}
+/**
+ * @brief Validate a positive finite numeric divisor.
+ * @param value Candidate divisor.
+ * @param label Bound label used in RangeError messages.
+ * @returns Accepted divisor.
+ */
+function checkPositiveFiniteNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`${label} numeric divisor must be positive and finite`);
+    }
+    return value;
 }

package/dist/guard/props.d.ts

@@ -1,18 +1,42 @@
 /**
  * @file props.ts
  * @brief Guard object shape helpers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ */
+/**
+ * @brief Define one immutable public property.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param target Object receiving the property.
+ * @param key Property key.
+ * @param value Stored property value.
+ * @param enumerable Whether the property should appear in enumeration.
+ * @post The property is non-configurable and non-writable.
  */
 export declare function defineReadonlyProperty(target: object, key: string, value: unknown, enumerable: boolean): void;
 /**
- * @brief is strict true.
+ * @brief Test for the only accepted refinement success value.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Predicate return value.
+ * @returns True only for the boolean literal true.
  */
 export declare function isStrictTrue(value: unknown): boolean;
 /**
- * @brief is record.
+ * @brief Test whether a value is a non-array object record.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Candidate runtime value.
+ * @returns True for object values that can carry string properties.
  */
 export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
 /**
- * @brief is plain reg exp.
+ * @brief Accept only unmodified RegExp instances for schema storage.
+ * @details User-owned exec/test/source/flags overrides can change validation
+ * behavior after construction, so they are rejected at the API boundary.
+ * @param value Candidate pattern.
+ * @returns True for plain RegExp instances without own behavioral overrides.
  */
 export declare function isPlainRegExp(value: unknown): value is RegExp;
 //# sourceMappingURL=props.d.ts.map

package/dist/guard/props.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/guard/props.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,OAAO,GAClB,IAAI,CAON;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/guard/props.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,OAAO,GACpB,IAAI,CAON;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}

package/dist/guard/props.js

@@ -1,6 +1,18 @@
 /**
  * @file props.ts
  * @brief Guard object shape helpers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ */
+/**
+ * @brief Define one immutable public property.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param target Object receiving the property.
+ * @param key Property key.
+ * @param value Stored property value.
+ * @param enumerable Whether the property should appear in enumeration.
+ * @post The property is non-configurable and non-writable.
  */
 export function defineReadonlyProperty(target, key, value, enumerable) {
     Object.defineProperty(target, key, {
@@ -11,19 +23,31 @@ export function defineReadonlyProperty(target, key, value, enumerable) {
     });
 }
 /**
- * @brief is strict true.
+ * @brief Test for the only accepted refinement success value.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Predicate return value.
+ * @returns True only for the boolean literal true.
  */
 export function isStrictTrue(value) {
     return value === true;
 }
 /**
- * @brief is record.
+ * @brief Test whether a value is a non-array object record.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Candidate runtime value.
+ * @returns True for object values that can carry string properties.
  */
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief is plain reg exp.
+ * @brief Accept only unmodified RegExp instances for schema storage.
+ * @details User-owned exec/test/source/flags overrides can change validation
+ * behavior after construction, so they are rejected at the API boundary.
+ * @param value Candidate pattern.
+ * @returns True for plain RegExp instances without own behavioral overrides.
  */
 export function isPlainRegExp(value) {
     return value instanceof RegExp &&

package/dist/guard/read.d.ts

@@ -1,42 +1,147 @@
 /**
  * @file read.ts
  * @brief Guard receiver and constructor validation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
-import type { NumberSchema, Schema, StringSchema } from "../schema/index.js";
+import type { ArraySchema, DateSchema, NumberSchema, Schema, StringSchema } from "../schema/index.js";
 /**
- * @brief read guard schema.
+ * @brief Read schema from a verified guard receiver.
+ * @details Constructed guards take the WeakSet fast path; forged structural
+ * guards must expose a valid own data schema before use. The fallback exists
+ * because public methods can be detached from their instance in JavaScript.
+ * @param guard Candidate receiver or guard-like value.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Valid runtime schema carried by the guard.
+ * @throws TypeError when the receiver is not a valid TypeSea guard.
  */
 export declare function readGuardSchema(guard: unknown, label: string): Schema;
 /**
- * @brief read string method schema.
+ * @brief Read and require a string schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns String schema carried by the receiver.
+ * @throws TypeError when the receiver is not a string guard.
+ * @details StringGuard methods share this gate so subtype-specific helpers do
+ * not duplicate receiver validation or accept forged schemas.
  */
 export declare function readStringMethodSchema(guard: unknown, label: string): StringSchema;
 /**
- * @brief read number method schema.
+ * @brief Read and require a number schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Number schema carried by the receiver.
+ * @throws TypeError when the receiver is not a number guard.
+ * @details NumberGuard methods must fail before reading numeric check vectors
+ * when a receiver is detached or structurally forged.
  */
 export declare function readNumberMethodSchema(guard: unknown, label: string): NumberSchema;
 /**
- * @brief read constructor schema.
+ * @brief Read and require a Date schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Date schema carried by the receiver.
+ * @throws TypeError when the receiver is not a Date guard.
+ */
+export declare function readDateMethodSchema(guard: unknown, label: string): DateSchema;
+/**
+ * @brief Read and require an array schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Array schema carried by the receiver.
+ * @throws TypeError when the receiver is not an array guard.
+ * @details ArrayGuard methods share this gate so fluent length helpers cannot
+ * be detached and applied to unrelated guard instances.
+ */
+export declare function readArrayMethodSchema(guard: unknown, label: string): ArraySchema;
+/**
+ * @brief Validate and freeze a generic guard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Frozen schema accepted by BaseGuard.
+ * @throws TypeError when the schema is malformed.
+ * @details Constructors are the only place that accepts mutable schema records.
+ * Freezing here lets normal method calls use the registry fast path later.
  */
 export declare function readConstructorSchema(schema: unknown): Schema;
 /**
- * @brief read string constructor schema.
+ * @brief Validate a StringGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns String schema accepted by StringGuard.
+ * @throws TypeError when the schema is not a string schema.
+ * @details Specialized guards keep their schema tag invariant at construction,
+ * so hot method calls only need to verify receiver identity.
  */
 export declare function readStringConstructorSchema(schema: unknown): StringSchema;
 /**
- * @brief read number constructor schema.
+ * @brief Validate a NumberGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Number schema accepted by NumberGuard.
+ * @throws TypeError when the schema is not a number schema.
+ * @details Rejecting non-number schemas at construction prevents mixed scalar
+ * helper methods from observing incompatible check vectors.
  */
 export declare function readNumberConstructorSchema(schema: unknown): NumberSchema;
 /**
- * @brief check refinement input.
+ * @brief Validate a DateGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Date schema accepted by DateGuard.
+ * @throws TypeError when the schema is not a Date schema.
+ */
+export declare function readDateConstructorSchema(schema: unknown): DateSchema;
+/**
+ * @brief Validate an ArrayGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Array schema accepted by ArrayGuard.
+ * @throws TypeError when the schema is not an array schema.
+ * @details The schema validator already checks the item tree and length-check
+ * vector, so the specialized constructor only enforces the root tag.
+ */
+export declare function readArrayConstructorSchema(schema: unknown): ArraySchema;
+/**
+ * @brief Validate refinement API inputs.
+ * @param predicate Candidate refinement predicate.
+ * @param name Candidate diagnostic name.
+ * @throws TypeError when either input has the wrong runtime type.
+ * @details Refinements execute user code by design. This gate narrows the call
+ * target and diagnostic label before the schema stores them.
  */
 export declare function checkRefinementInput(predicate: unknown, name: unknown): asserts predicate is (value: unknown) => boolean;
 /**
- * @brief check string length bound.
+ * @brief Validate a non-negative string length bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is negative or non-integer.
+ * @details Bounds are checked once at builder time so generated validators can
+ * emit straight comparisons without defensive range checks.
  */
 export declare function checkStringLengthBound(value: number, label: string): number;
 /**
- * @brief check finite number bound.
+ * @brief Validate a non-negative array length bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is negative or non-integer.
+ * @details Array bounds share the same integer contract as string length
+ * bounds, but the separate helper keeps public error text precise.
+ */
+export declare function checkArrayLengthBound(value: number, label: string): number;
+/**
+ * @brief Validate a finite numeric bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is not finite.
+ * @details Finite bounds keep interpreter, plan, and emitted code semantics
+ * aligned for comparisons such as gte and lte.
  */
 export declare function checkFiniteNumberBound(value: number, label: string): number;
+/**
+ * @brief Normalize a Date bound into a finite epoch millisecond value.
+ * @param value Candidate Date bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns Finite epoch millisecond value.
+ * @throws RangeError when the bound is not a valid Date instance.
+ */
+export declare function checkDateBound(value: Date, label: string): number;
 //# sourceMappingURL=read.d.ts.map

package/dist/guard/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/guard/read.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK7E;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAK7D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAOlD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/guard/read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACR,WAAW,EACX,UAAU,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACf,MAAM,oBAAoB,CAAC;AAK5B;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACd,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAa9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAahF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAKrE;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,CAKvE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAChC,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,OAAO,GACd,OAAO,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAOlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASjE"}