typesea 0.1.0 → 0.2.0

package/dist/builders/scalar.js

@@ -1,61 +1,86 @@
 /**
  * @file scalar.ts
  * @brief Primitive and literal guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { SchemaTag } from "../kind/index.js";
 import { BaseGuard, NumberGuard, StringGuard } from "../guard/index.js";
 import { isLiteralValue } from "../schema/index.js";
 /**
- * @brief string guard.
+ * @brief Shared string guard singleton.
+ * @details Primitive guards are immutable, so exporting one instance avoids
+ * allocation for the common `t.string` path.
  */
 export const stringGuard = new StringGuard({
     tag: SchemaTag.String,
     checks: []
 });
 /**
- * @brief unknown guard.
+ * @brief Shared unknown guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export const unknownGuard = new BaseGuard({
     tag: SchemaTag.Unknown
 });
 /**
- * @brief never guard.
+ * @brief Shared never guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export const neverGuard = new BaseGuard({
     tag: SchemaTag.Never
 });
 /**
- * @brief number guard.
+ * @brief Shared finite number guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export const numberGuard = new NumberGuard({
     tag: SchemaTag.Number,
     checks: []
 });
 /**
- * @brief bigint guard.
+ * @brief Shared bigint guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export const bigintGuard = new BaseGuard({
     tag: SchemaTag.BigInt
 });
 /**
- * @brief symbol guard.
+ * @brief Shared symbol guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export const symbolGuard = new BaseGuard({
     tag: SchemaTag.Symbol
 });
 /**
- * @brief boolean guard.
+ * @brief Shared boolean guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export const booleanGuard = new BaseGuard({
     tag: SchemaTag.Boolean
 });
 /**
- * @brief literal.
+ * @brief Build a literal guard after rejecting non-literal runtime values.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param value Literal value to match with Object.is.
+ * @returns Fresh guard for exactly the supplied literal.
+ * @throws TypeError when the value cannot be represented as a TypeSea literal.
  */
 export function literal(value) {
     if (!isLiteralValue(value)) {
         throw new TypeError("literal value must be a primitive literal");
     }
+    /*
+     * Literal schemas store the runtime value directly. Rejecting compound input
+     * here keeps later equality checks side-effect free and serializable.
+     */
     return new BaseGuard({
         tag: SchemaTag.Literal,
         value

package/dist/builders/table.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file table.ts
  * @brief Frozen public builder table.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { asyncDecoder, asyncPipe, asyncRefine, asyncTransform } from "../async/index.js";
 import { decoder, pipe, transform } from "../decoder/index.js";
@@ -10,6 +12,8 @@ import { extend, object, omit, partial, pick, strictObject } from "./object/inde
 import { literal } from "./scalar.js";
 /**
  * @brief t.
+ * @details Frozen namespace of all public builders. Freezing prevents accidental
+ * mutation of shared singleton guards and helper functions after module load.
  */
 export declare const t: Readonly<{
     readonly unknown: import("../index.js").BaseGuard<unknown, "required">;

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

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/builders/table.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAU,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACvE,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,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGL,OAAO,EAMR,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,eAAO,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCH,CAAC"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../src/builders/table.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAU,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EACH,KAAK,EACL,kBAAkB,EAClB,SAAS,EACT,MAAM,EACN,KAAK,EACL,KAAK,EACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACH,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,aAAa,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAGH,OAAO,EAMV,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCH,CAAC"}

package/dist/builders/table.js

@@ -1,6 +1,8 @@
 /**
  * @file table.ts
  * @brief Frozen public builder table.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { asyncDecoder, asyncPipe, asyncRefine, asyncTransform } from "../async/index.js";
 import { coerce, decoder, pipe, transform } from "../decoder/index.js";
@@ -10,6 +12,8 @@ import { extend, object, omit, partial, pick, strictObject } from "./object/inde
 import { bigintGuard, booleanGuard, literal, neverGuard, numberGuard, stringGuard, symbolGuard, unknownGuard } from "./scalar.js";
 /**
  * @brief t.
+ * @details Frozen namespace of all public builders. Freezing prevents accidental
+ * mutation of shared singleton guards and helper functions after module load.
  */
 export const t = Object.freeze({
     unknown: unknownGuard,

package/dist/builders/types.d.ts

@@ -1,24 +1,34 @@
 /**
  * @file types.ts
  * @brief Shared builder type algebra.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import type { Guard, Infer, Presence } from "../guard/index.js";
 /**
- * @brief tuple shape.
+ * @brief Tuple builder input shape.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export type TupleShape = readonly Guard<unknown, Presence>[];
 /**
- * @brief infer tuple.
+ * @brief Infer tuple runtime value from a tuple guard shape.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export type InferTuple<TShape extends TupleShape> = {
     readonly [TKey in keyof TShape]: Infer<TShape[TKey]>;
 };
 /**
- * @brief union input.
+ * @brief Non-empty union builder input.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export type UnionInput = readonly [Guard<unknown, Presence>, ...Guard<unknown, Presence>[]];
 /**
- * @brief discriminated union cases.
+ * @brief Compile-time guard that each case owns the requested literal tag.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export type DiscriminatedUnionCases<TKey extends string, TCases extends Readonly<Record<string, Guard<unknown, Presence>>>> = string extends TKey ? TCases : {
     readonly [TCase in keyof TCases]: TCase extends string ? Infer<TCases[TCase]> extends Readonly<Record<TKey, TCase>> ? TCases[TCase] : never : never;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/builders/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,KAAK,EACL,QAAQ,EACT,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,SAAS,UAAU,IAAI;IAClD,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACrD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GACpB,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,uBAAuB,CACjC,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,IAC/D,MAAM,SAAS,IAAI,GACnB,MAAM,GACN;IACE,QAAQ,EAAE,KAAK,IAAI,MAAM,MAAM,GAAG,KAAK,SAAS,MAAM,GAClD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,GACxD,MAAM,CAAC,KAAK,CAAC,GACb,KAAK,GACT,KAAK;CACR,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/builders/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACR,KAAK,EACL,KAAK,EACL,QAAQ,EACX,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,SAAS,UAAU,IAAI;IAChD,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACvD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,CAC/B,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,IACjE,MAAM,SAAS,IAAI,GACjB,MAAM,GACN;IACM,QAAQ,EAAE,KAAK,IAAI,MAAM,MAAM,GAAG,KAAK,SAAS,MAAM,GAChD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,GACtD,MAAM,CAAC,KAAK,CAAC,GACb,KAAK,GACb,KAAK;CACV,CAAC"}

package/dist/builders/types.js

@@ -1,5 +1,7 @@
 /**
  * @file types.ts
  * @brief Shared builder type algebra.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export {};

package/dist/compile/check-composite.d.ts

@@ -1,34 +1,55 @@
 /**
  * @file compile/check-composite.ts
  * @brief Composite diagnostic validator snippets.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 import { SchemaTag } from "../kind/index.js";
-import type { DiscriminatedUnionCase, Schema } from "../schema/index.js";
+import { type DiscriminatedUnionCase, type Schema } from "../schema/index.js";
 import type { EmitContext } from "./types.js";
 /**
  * @brief check function emitter.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 export type CheckFunctionEmitter = (schema: Schema, context: EmitContext) => string;
 /**
  * @brief emit array check.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param item Schema applied to each logical array slot.
+ * @param value Generated expression for the candidate value.
+ * @param path Generated expression for the mutable diagnostic path.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param context Shared code-generation context.
+ * @param emitChild Fallback emitter for non-leaf child validators.
+ * @returns JavaScript source for array diagnostics.
  */
 export declare function emitArrayCheck(item: Schema, value: string, path: string, issues: string, context: EmitContext, emitChild: CheckFunctionEmitter): string;
 /**
  * @brief emit tuple check.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 export declare function emitTupleCheck(items: readonly Schema[], value: string, path: string, issues: string, context: EmitContext, emitChild: CheckFunctionEmitter): string;
 /**
  * @brief emit record check.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 export declare function emitRecordCheck(item: Schema, value: string, path: string, issues: string, context: EmitContext, emitChild: CheckFunctionEmitter): string;
 /**
  * @brief emit object check.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 export declare function emitObjectCheck(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.Object;
 }>, value: string, path: string, issues: string, context: EmitContext, emitChild: CheckFunctionEmitter): string;
 /**
  * @brief emit discriminated union check.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 export declare function emitDiscriminatedUnionCheck(key: string, cases: readonly DiscriminatedUnionCase[], value: string, path: string, issues: string, context: EmitContext, emitChild: CheckFunctionEmitter): string;
 //# sourceMappingURL=check-composite.d.ts.map

package/dist/compile/check-composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-composite.d.ts","sourceRoot":"","sources":["../../src/compile/check-composite.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,SAAS,EACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,sBAAsB,EACtB,MAAM,EACP,MAAM,oBAAoB,CAAC;AAW5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,KACjB,MAAM,CAAC;AAEZ;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAC9B,MAAM,CAuBR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAC9B,MAAM,CAiCR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAC9B,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAC9B,MAAM,CAqDR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAC9B,MAAM,CA+CR"}
+{"version":3,"file":"check-composite.d.ts","sourceRoot":"","sources":["../../src/compile/check-composite.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGH,SAAS,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEH,KAAK,sBAAsB,EAC3B,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAkB5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,KACnB,MAAM,CAAC;AAEZ;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAChC,MAAM,CAgFR;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAChC,MAAM,CAoER;AA+ZD;;;;GAIG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAChC,MAAM,CA2CR;AAmKD;;;;GAIG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAChC,MAAM,CAiGR;AA0KD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACvC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,oBAAoB,GAChC,MAAM,CA4DR"}