typesea 0.1.0 → 0.3.0

package/dist/compile/issue.js

@@ -1,28 +1,211 @@
 /**
  * @file compile/issue.ts
  * @brief Diagnostic issue source snippets.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 import { UUID_PATTERN } from "../schema/index.js";
 import { pushRegex, stringRef } from "./context.js";
 import { stringLiteral } from "./names.js";
 /**
  * @brief emit pattern issue.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the string value.
+ * @param path Generated expression for the current diagnostic path.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param regex Pattern used by the schema check.
+ * @param name Human-readable pattern name stored in the issue.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source that appends a pattern issue when the test fails.
  */
 export function emitPatternIssue(value, path, issues, regex, name, context) {
     const source = regex === UUID_PATTERN ? UUID_PATTERN : regex;
     const index = pushRegex(context, source);
     const access = `r[${String(index)}]`;
-    return `if(((${access}.lastIndex=0),!${access}.test(${value}))){${emitIssueExpr(issues, path, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+    const test = regexNeedsLastIndexReset(source)
+        ? `((${access}.lastIndex=0),!${access}.test(${value}))`
+        : `!${access}.test(${value})`;
+    /*
+     * Pattern names live in the string side table. That keeps generated source
+     * stable even when users provide long or escaped pattern descriptions.
+     */
+    return `if(${test}){${emitIssueExpr(issues, path, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+}
+/**
+ * @brief emit pattern issue at one appended path segment.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the string value.
+ * @param path Generated expression for the current diagnostic path.
+ * @param segmentExpression Generated expression for the appended segment.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param regex Pattern used by the schema check.
+ * @param name Human-readable pattern name stored in the issue.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source that appends a one-segment pattern issue.
+ */
+export function emitPatternIssueAtSegment(value, path, segmentExpression, issues, regex, name, context) {
+    const source = regex === UUID_PATTERN ? UUID_PATTERN : regex;
+    const index = pushRegex(context, source);
+    const access = `r[${String(index)}]`;
+    const test = regexNeedsLastIndexReset(source)
+        ? `((${access}.lastIndex=0),!${access}.test(${value}))`
+        : `!${access}.test(${value})`;
+    return `if(${test}){${emitIssueExprAtSegment(issues, path, segmentExpression, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+}
+/**
+ * @brief emit pattern issue at two appended path segments.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the string value.
+ * @param path Generated expression for the current diagnostic path.
+ * @param firstSegmentExpression Generated expression for the first appended segment.
+ * @param secondSegmentExpression Generated expression for the second appended segment.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param regex Pattern used by the schema check.
+ * @param name Human-readable pattern name stored in the issue.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source that appends a two-segment pattern issue.
+ */
+export function emitPatternIssueAtTwoSegments(value, path, firstSegmentExpression, secondSegmentExpression, issues, regex, name, context) {
+    const source = regex === UUID_PATTERN ? UUID_PATTERN : regex;
+    const index = pushRegex(context, source);
+    const access = `r[${String(index)}]`;
+    const test = regexNeedsLastIndexReset(source)
+        ? `((${access}.lastIndex=0),!${access}.test(${value}))`
+        : `!${access}.test(${value})`;
+    return `if(${test}){${emitIssueExprAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+}
+/**
+ * @brief Decide whether a RegExp must be reset before generated testing.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param regex RegExp stored in the generated side table.
+ * @returns True for stateful global or sticky expressions.
+ */
+function regexNeedsLastIndexReset(regex) {
+    return regex.global || regex.sticky;
 }
 /**
  * @brief emit issue.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param code Issue code string.
+ * @param expected Expected type or condition text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue at the current path.
  */
 export function emitIssue(issues, path, code, expected, actualExpression) {
     return emitIssueExpr(issues, path, code, stringLiteral(expected), actualExpression);
 }
+/**
+ * @brief emit issue at one appended path segment.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param segmentExpression Generated expression for the appended segment.
+ * @param code Issue code string.
+ * @param expected Expected type or condition text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue under one extra segment.
+ */
+export function emitIssueAtSegment(issues, path, segmentExpression, code, expected, actualExpression) {
+    return emitIssueExprAtSegment(issues, path, segmentExpression, code, stringLiteral(expected), actualExpression);
+}
+/**
+ * @brief emit issue at two appended path segments.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param firstSegmentExpression Generated expression for the first appended segment.
+ * @param secondSegmentExpression Generated expression for the second appended segment.
+ * @param code Issue code string.
+ * @param expected Expected type or condition text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue under two extra segments.
+ */
+export function emitIssueAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, code, expected, actualExpression) {
+    return emitIssueExprAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, code, stringLiteral(expected), actualExpression);
+}
 /**
  * @brief emit issue expr.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param code Issue code string.
+ * @param expectedExpression Generated expression for expected text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue using expression operands.
  */
 export function emitIssueExpr(issues, path, code, expectedExpression, actualExpression) {
     return `q(${issues},${path},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
 }
+/**
+ * @brief emit issue expr at one appended path segment.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param segmentExpression Generated expression for the appended segment.
+ * @param code Issue code string.
+ * @param expectedExpression Generated expression for expected text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source using the most compact one-segment issue helper.
+ */
+export function emitIssueExprAtSegment(issues, path, segmentExpression, code, expectedExpression, actualExpression) {
+    const stringIndex = readStringRefIndex(segmentExpression);
+    if (stringIndex !== undefined) {
+        /*
+         * q1s reuses the pre-frozen path segment cache for static string keys.
+         * Dynamic segments still go through q1 because their value is known only
+         * inside the generated validator.
+         */
+        return `q1s(${issues},${path},${stringIndex},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
+    }
+    return `q1(${issues},${path},${segmentExpression},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
+}
+/**
+ * @brief emit issue expr at two appended path segments.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param firstSegmentExpression Generated expression for the first appended segment.
+ * @param secondSegmentExpression Generated expression for the second appended segment.
+ * @param code Issue code string.
+ * @param expectedExpression Generated expression for expected text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source using the two-segment issue helper.
+ */
+export function emitIssueExprAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, code, expectedExpression, actualExpression) {
+    return `q2(${issues},${path},${firstSegmentExpression},${secondSegmentExpression},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
+}
+/**
+ * @brief Extract the numeric side-table index from a generated string reference.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param expression Candidate generated expression such as `u[3]`.
+ * @returns Index text when the expression is a plain string-table read.
+ */
+function readStringRefIndex(expression) {
+    if (!expression.startsWith("u[") || !expression.endsWith("]")) {
+        return undefined;
+    }
+    const value = expression.slice(2, -1);
+    if (value.length === 0) {
+        return undefined;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 48 || code > 57) {
+            return undefined;
+        }
+    }
+    return value;
+}

package/dist/compile/names.d.ts

@@ -1,16 +1,26 @@
 /**
  * @file compile-names.ts
  * @brief Generated function-name and string literal helpers.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  *
  * @invariant User-provided names never enter generated source until they are
  * reduced to a strict-mode-safe identifier with a fixed length bound.
  */
 /**
- * @brief safe function name.
+ * @brief Convert a user supplied compile name into a strict-mode function id.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Requested public function name.
+ * @returns Identifier-safe, reserved-word-safe, bounded function name.
  */
 export declare function safeFunctionName(value: string): string;
 /**
- * @brief string literal.
+ * @brief Quote a string for generated JavaScript source.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Runtime string to embed.
+ * @returns JSON-escaped string literal source.
  */
 export declare function stringLiteral(value: string): string;
 //# sourceMappingURL=names.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/compile/names.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYtD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/compile/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/compile/names.js

@@ -1,13 +1,19 @@
 /**
  * @file compile-names.ts
  * @brief Generated function-name and string literal helpers.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  *
  * @invariant User-provided names never enter generated source until they are
  * reduced to a strict-mode-safe identifier with a fixed length bound.
  */
 const MAX_GENERATED_FUNCTION_NAME_LENGTH = 96;
 /**
- * @brief safe function name.
+ * @brief Convert a user supplied compile name into a strict-mode function id.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Requested public function name.
+ * @returns Identifier-safe, reserved-word-safe, bounded function name.
  */
 export function safeFunctionName(value) {
     const replaced = value.replace(/[^$_a-zA-Z0-9]/gu, "_");
@@ -17,19 +23,29 @@ export function safeFunctionName(value) {
     if (/^[$_a-zA-Z]/u.test(bounded) && !reservedFunctionNames.has(bounded)) {
         return bounded;
     }
+    /*
+     * Prefixing recovers names that start with a digit or collide with reserved
+     * words while keeping the final identifier under the same length cap.
+     */
     const prefixed = `_${bounded}`;
     return prefixed.length > MAX_GENERATED_FUNCTION_NAME_LENGTH
         ? prefixed.slice(0, MAX_GENERATED_FUNCTION_NAME_LENGTH)
         : prefixed;
 }
 /**
- * @brief string literal.
+ * @brief Quote a string for generated JavaScript source.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Runtime string to embed.
+ * @returns JSON-escaped string literal source.
  */
 export function stringLiteral(value) {
     return JSON.stringify(value);
 }
 /**
- * @brief reserved function names.
+ * @brief Strict-mode names that cannot be emitted as generated function ids.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 const reservedFunctionNames = new Set([
     "arguments",

package/dist/compile/predicate.d.ts

@@ -1,23 +1,47 @@
 /**
  * @file compile/predicate.ts
  * @brief Boolean validator source emitter.
+ * @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 { EmitContext } from "./types.js";
 /**
  * @brief emit function.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by the predicate.
+ * @param context Shared code-generation context.
+ * @returns Generated predicate function name.
+ * @invariant The same schema object maps to one predicate function per bundle.
  */
 export declare function emitFunction(schema: Schema, context: EmitContext): string;
 /**
  * @brief emit 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 predicate sources.
+ * @returns Concatenated JavaScript function declarations.
  */
 export declare function emitFunctions(context: EmitContext): string;
 /**
  * @brief emit expression.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by the expression.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression that evaluates to a boolean.
  */
 export declare function emitExpression(schema: Schema, value: string, context: EmitContext): string;
 /**
  * @brief emit union.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param options Union option schemas.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression for the union predicate.
  */
 export declare function emitUnion(options: readonly Schema[], value: string, context: EmitContext): string;
 //# sourceMappingURL=predicate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/compile/predicate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAE9D;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAczE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAU1D;AAsBD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACnB,MAAM,CA+CR;AA0PD;;GAEG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACnB,MAAM,CAYR"}
+{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/compile/predicate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,EAYH,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAkBzE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAU1D;AAoCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACrB,MAAM,CAiER;AAucD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACrB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACrB,MAAM,CAYR"}