typesea 0.1.0 → 0.2.0

package/dist/compile/check.js

@@ -1,6 +1,8 @@
 /**
  * @file compile/check.ts
  * @brief Diagnostic validator function table emitter.
+ * @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 { emitArrayCheck, emitDiscriminatedUnionCheck, emitObjectCheck, emitRecordCheck, emitTupleCheck } from "./check-composite.js";
@@ -10,12 +12,22 @@ import { emitIssue } from "./issue.js";
 import { emitUnion } from "./predicate.js";
 /**
  * @brief emit check function.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema whose diagnostics should be emitted.
+ * @param context Shared code-generation context.
+ * @returns Generated diagnostic function name.
+ * @invariant The same schema object maps to one diagnostic function per bundle.
  */
 export function emitCheckFunction(schema, context) {
     const cached = context.checkFunctionNames.get(schema);
     if (cached !== undefined) {
         return cached;
     }
+    /*
+     * Insert the placeholder before emitting the body. Recursive schemas can
+     * request this same function while the current body is still being built.
+     */
     const name = `c${String(context.checkFunctions.length)}`;
     const source = {
         name,
@@ -28,6 +40,10 @@ export function emitCheckFunction(schema, context) {
 }
 /**
  * @brief emit check functions.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Shared code-generation context with accumulated check sources.
+ * @returns Concatenated JavaScript function declarations.
  */
 export function emitCheckFunctions(context) {
     const chunks = new Array(context.checkFunctions.length);
@@ -42,6 +58,14 @@ export function emitCheckFunctions(context) {
 }
 /**
  * @brief emit check body.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by this diagnostic body.
+ * @param value Generated expression for the candidate value.
+ * @param path Generated expression for the mutable path stack.
+ * @param issues Generated expression for the issue buffer.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source for diagnostic collection.
  */
 function emitCheckBody(schema, value, path, issues, context) {
     switch (schema.tag) {
@@ -87,11 +111,24 @@ function emitCheckBody(schema, value, path, issues, context) {
             return emitCheckCall(schema.inner, value, path, issues, context);
         case SchemaTag.Lazy:
         case SchemaTag.Refine:
+            /*
+             * Lazy and refine schemas execute runtime logic that cannot be safely
+             * inlined into generated source. The `m` helper calls the interpreter
+             * diagnostic path through the dynamic schema side table.
+             */
             return `m(${String(pushSchema(context, schema))},${value},${path},${issues});`;
     }
 }
 /**
  * @brief emit check call.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Child schema to dispatch to.
+ * @param value Generated expression for the child value.
+ * @param path Generated expression for the mutable path stack.
+ * @param issues Generated expression for the issue buffer.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source for invoking the child diagnostic function.
  */
 function emitCheckCall(schema, value, path, issues, context) {
     return `${emitCheckFunction(schema, context)}(${value},${path},${issues});`;

package/dist/compile/context.d.ts

@@ -1,35 +1,73 @@
 /**
  * @file compile/context.ts
  * @brief Generated-source emitter side-table context.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 import type { LiteralValue, Schema } from "../schema/index.js";
-import type { EmitContext } from "./types.js";
+import type { CompileMode, EmitContext } from "./types.js";
 /**
- * @brief create emit context.
+ * @brief Create one mutable source-emission context.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param mode Compile mode that controls safety and allocation tradeoffs.
+ * @returns Fresh side-table context consumed by predicate and diagnostic emitters.
+ * @invariant Side tables are append-only during one bundle emission.
  */
-export declare function createEmitContext(): EmitContext;
+export declare function createEmitContext(mode: CompileMode): EmitContext;
 /**
- * @brief push literal.
+ * @brief Append a literal to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Literal value referenced by generated source.
+ * @returns Index used by generated code to read `l[index]`.
  */
 export declare function pushLiteral(context: EmitContext, value: LiteralValue): number;
 /**
- * @brief push regex.
+ * @brief Append a regular expression to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Source RegExp from the schema.
+ * @returns Index used by generated code to read `r[index]`.
+ * @post The stored RegExp is cloned so generated validation does not mutate user state.
  */
 export declare function pushRegex(context: EmitContext, value: RegExp): number;
 /**
- * @brief push keyset.
+ * @brief Append a keyset to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Frozen or caller-owned key list used by object checks.
+ * @returns Index used by generated code to read `k[index]`.
  */
 export declare function pushKeyset(context: EmitContext, value: readonly string[]): number;
 /**
- * @brief string ref.
+ * @brief Return a generated expression for a string side-table entry.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value String value to intern.
+ * @returns Generated expression of the form `u[index]`.
  */
 export declare function stringRef(context: EmitContext, value: string): string;
 /**
- * @brief push string.
+ * @brief Intern a string in the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value String value referenced by generated source.
+ * @returns Stable side-table index for the string.
  */
 export declare function pushString(context: EmitContext, value: string): number;
 /**
- * @brief push schema.
+ * @brief Append a dynamic schema to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Schema used by fallback or lazy generated paths.
+ * @returns Index used by generated code to read `d[index]`.
  */
 export declare function pushSchema(context: EmitContext, value: Schema): number;
 //# sourceMappingURL=context.d.ts.map

package/dist/compile/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/compile/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CAa/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAI7E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAIjF;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAStE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAItE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/compile/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAchE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAI7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAIjF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAatE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAItE"}

package/dist/compile/context.js

@@ -1,12 +1,20 @@
 /**
  * @file compile/context.ts
  * @brief Generated-source emitter side-table context.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 /**
- * @brief create emit context.
+ * @brief Create one mutable source-emission context.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param mode Compile mode that controls safety and allocation tradeoffs.
+ * @returns Fresh side-table context consumed by predicate and diagnostic emitters.
+ * @invariant Side tables are append-only during one bundle emission.
  */
-export function createEmitContext() {
+export function createEmitContext(mode) {
     return {
+        mode,
         literals: [],
         regexps: [],
         keysets: [],
@@ -20,7 +28,12 @@ export function createEmitContext() {
     };
 }
 /**
- * @brief push literal.
+ * @brief Append a literal to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Literal value referenced by generated source.
+ * @returns Index used by generated code to read `l[index]`.
  */
 export function pushLiteral(context, value) {
     const index = context.literals.length;
@@ -28,7 +41,13 @@ export function pushLiteral(context, value) {
     return index;
 }
 /**
- * @brief push regex.
+ * @brief Append a regular expression to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Source RegExp from the schema.
+ * @returns Index used by generated code to read `r[index]`.
+ * @post The stored RegExp is cloned so generated validation does not mutate user state.
  */
 export function pushRegex(context, value) {
     const index = context.regexps.length;
@@ -36,7 +55,12 @@ export function pushRegex(context, value) {
     return index;
 }
 /**
- * @brief push keyset.
+ * @brief Append a keyset to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Frozen or caller-owned key list used by object checks.
+ * @returns Index used by generated code to read `k[index]`.
  */
 export function pushKeyset(context, value) {
     const index = context.keysets.length;
@@ -44,26 +68,45 @@ export function pushKeyset(context, value) {
     return index;
 }
 /**
- * @brief string ref.
+ * @brief Return a generated expression for a string side-table entry.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value String value to intern.
+ * @returns Generated expression of the form `u[index]`.
  */
 export function stringRef(context, value) {
     return `u[${String(pushString(context, value))}]`;
 }
 /**
- * @brief push string.
+ * @brief Intern a string in the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value String value referenced by generated source.
+ * @returns Stable side-table index for the string.
  */
 export function pushString(context, value) {
     const cached = context.stringIndexes.get(value);
     if (cached !== undefined) {
         return cached;
     }
+    /*
+     * String interning keeps generated source small and lets repeated object
+     * keys reuse the same frozen path segment cache.
+     */
     const index = context.strings.length;
     context.strings.push(value);
     context.stringIndexes.set(value, index);
     return index;
 }
 /**
- * @brief push schema.
+ * @brief Append a dynamic schema to the generated factory side table.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Mutable emission context.
+ * @param value Schema used by fallback or lazy generated paths.
+ * @returns Index used by generated code to read `d[index]`.
  */
 export function pushSchema(context, value) {
     const index = context.schemas.length;

package/dist/compile/graph-predicate.d.ts

@@ -1,15 +1,17 @@
 /**
  * @file graph-predicate.ts
  * @brief Predicate source emitter backed by optimized Sea-of-Nodes graphs.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
-import type { Schema } from "../schema/index.js";
+import { type Schema } from "../schema/index.js";
 import type { EmitContext } from "./types.js";
 /**
  * @brief emit graph function.
  * @details Emits one predicate function from the optimized graph owned by a schema plan.
  * @returns Generated function name.
  */
-export declare function emitGraphFunction(schema: Schema, context: EmitContext): string;
+export declare function emitGraphFunction(schema: Schema, context: EmitContext, preferredName?: string): string;
 /**
  * @brief emit graph functions.
  * @details Serializes every graph predicate function accumulated in the context.

package/dist/compile/graph-predicate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-predicate.d.ts","sourceRoot":"","sources":["../../src/compile/graph-predicate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAgB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAQ/D,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAoB9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,GACnB,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAS/D"}
+{"version":3,"file":"graph-predicate.d.ts","sourceRoot":"","sources":["../../src/compile/graph-predicate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAGH,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AA8G9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,aAAa,CAAC,EAAE,MAAM,GACvB,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAS/D"}