typesea 0.1.0 → 0.3.0

package/dist/optimize/algebraic.js

@@ -0,0 +1,314 @@
+/**
+ * @file algebraic.ts
+ * @brief Boolean algebra simplification for validation predicates.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import { NodeTag } from "../kind/index.js";
+/**
+ * @brief Flatten nested boolean folds of the same kind.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested folds.
+ * @param tag Boolean fold kind to flatten.
+ * @returns Operand list with same-kind nested folds expanded in place.
+ */
+export function flattenBooleanValues(values, nodes, tag) {
+    const flattened = [];
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined) {
+            continue;
+        }
+        const node = nodes[value];
+        if (node?.tag === tag) {
+            /*
+             * And(And(a,b),c) and Or(Or(a,b),c) are associative. Flattening
+             * reduces later duplicate and complement checks to one linear pass.
+             */
+            appendFlattenedBooleanValues(flattened, node.values, nodes, tag);
+        }
+        else {
+            flattened.push(value);
+        }
+    }
+    return flattened;
+}
+/**
+ * @brief Simplify operands of an And fold.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested complement forms.
+ * @returns Simplification result with contradiction status and kept operands.
+ */
+export function simplifyAndValues(values, nodes) {
+    const kept = [];
+    const seen = new Set();
+    const positive = new Set();
+    const negative = new Set();
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined || seen.has(value)) {
+            continue;
+        }
+        if (isAbsorbedAndValue(value, nodes, seen)) {
+            /*
+             * a && (a || b) is equivalent to a. The Or branch cannot make the
+             * validation stricter once the shared value is already required.
+             */
+            continue;
+        }
+        if (hasComplementConflict(value, nodes, positive, negative)) {
+            /*
+             * a && !a is impossible for side-effect-free predicate nodes. Only
+             * complement-safe nodes are allowed into the positive/negative sets.
+             */
+            return {
+                contradiction: true,
+                tautology: false,
+                values: []
+            };
+        }
+        rememberComplementValue(value, nodes, positive, negative);
+        seen.add(value);
+        kept.push(value);
+    }
+    return {
+        contradiction: false,
+        tautology: false,
+        values: kept
+    };
+}
+/**
+ * @brief Simplify operands of an Or fold.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested complement forms.
+ * @returns Simplification result with tautology status and kept operands.
+ */
+export function simplifyOrValues(values, nodes) {
+    const kept = [];
+    const seen = new Set();
+    const positive = new Set();
+    const negative = new Set();
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined || seen.has(value)) {
+            continue;
+        }
+        if (isAbsorbedOrValue(value, nodes, seen)) {
+            /*
+             * a || (a && b) is equivalent to a. The And branch cannot widen the
+             * accepted set once the shared value already passes.
+             */
+            continue;
+        }
+        if (hasComplementConflict(value, nodes, positive, negative)) {
+            /*
+             * a || !a is always true for complement-safe predicates, so the Or
+             * fold can collapse to a tautology.
+             */
+            return {
+                contradiction: false,
+                tautology: true,
+                values: []
+            };
+        }
+        rememberComplementValue(value, nodes, positive, negative);
+        seen.add(value);
+        kept.push(value);
+    }
+    return {
+        contradiction: false,
+        tautology: false,
+        values: kept
+    };
+}
+/**
+ * @brief Recursively append flattened operands.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param output Destination operand list.
+ * @param values Source operand ids.
+ * @param nodes Graph node table used to inspect nested folds.
+ * @param tag Boolean fold kind to flatten.
+ */
+function appendFlattenedBooleanValues(output, values, nodes, tag) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined) {
+            continue;
+        }
+        const node = nodes[value];
+        if (node?.tag === tag) {
+            appendFlattenedBooleanValues(output, node.values, nodes, tag);
+        }
+        else {
+            output.push(value);
+        }
+    }
+}
+/**
+ * @brief Test And absorption for `a && (a || b)`.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param seen Operands already kept by the parent And.
+ * @returns True when the candidate is redundant.
+ */
+function isAbsorbedAndValue(value, nodes, seen) {
+    const node = nodes[value];
+    if (node?.tag !== NodeTag.Or) {
+        return false;
+    }
+    return containsSeenValue(node.values, seen);
+}
+/**
+ * @brief Test Or absorption for `a || (a && b)`.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param seen Operands already kept by the parent Or.
+ * @returns True when the candidate is redundant.
+ */
+function isAbsorbedOrValue(value, nodes, seen) {
+    const node = nodes[value];
+    if (node?.tag !== NodeTag.And) {
+        return false;
+    }
+    return containsSeenValue(node.values, seen);
+}
+/**
+ * @brief Test whether a nested fold contains an operand already kept.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Nested fold operand ids.
+ * @param seen Parent fold operands already kept.
+ * @returns True when the nested fold repeats a kept operand.
+ */
+function containsSeenValue(values, seen) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value !== undefined && seen.has(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * @brief Detect a positive/negative complement conflict.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param positive Complement-safe positive operands already seen.
+ * @param negative Complement-safe negated operands already seen.
+ * @returns True when the candidate conflicts with prior operands.
+ */
+function hasComplementConflict(value, nodes, positive, negative) {
+    const negated = readNegatedValue(value, nodes);
+    if (negated !== undefined) {
+        return isComplementSafe(negated, nodes) && positive.has(negated);
+    }
+    return isComplementSafe(value, nodes) && negative.has(value);
+}
+/**
+ * @brief Record a complement-safe operand in positive or negative form.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param positive Mutable set for positive operands.
+ * @param negative Mutable set for negated operands.
+ */
+function rememberComplementValue(value, nodes, positive, negative) {
+    const negated = readNegatedValue(value, nodes);
+    if (negated !== undefined) {
+        if (isComplementSafe(negated, nodes)) {
+            negative.add(negated);
+        }
+        return;
+    }
+    if (isComplementSafe(value, nodes)) {
+        positive.add(value);
+    }
+}
+/**
+ * @brief Read the operand of a Not node.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate node id.
+ * @param nodes Graph node table.
+ * @returns Inner node id for Not, otherwise undefined.
+ */
+function readNegatedValue(value, nodes) {
+    const node = nodes[value];
+    return node?.tag === NodeTag.Not ? node.value : undefined;
+}
+/**
+ * @brief Decide whether a node is safe for complement algebra.
+ * @details Only pure structural predicates are allowed. Nodes that inspect user
+ * predicates or nested graph execution stay out of `a`/`!a` folding.
+ * @param value Candidate node id.
+ * @param nodes Graph node table.
+ * @returns True when complement laws can be applied to the node.
+ */
+function isComplementSafe(value, nodes) {
+    const node = nodes[value];
+    if (node === undefined) {
+        return false;
+    }
+    switch (node.tag) {
+        case NodeTag.Const:
+            return typeof node.value === "boolean";
+        case NodeTag.IsString:
+        case NodeTag.IsNumber:
+        case NodeTag.IsBoolean:
+        case NodeTag.IsBigInt:
+        case NodeTag.IsSymbol:
+        case NodeTag.IsObject:
+        case NodeTag.IsArray:
+        case NodeTag.IsUndefined:
+        case NodeTag.IsNull:
+        case NodeTag.IsInteger:
+        case NodeTag.Equals:
+        case NodeTag.Gte:
+        case NodeTag.Lte:
+        case NodeTag.StringMin:
+        case NodeTag.StringMax:
+        case NodeTag.Regex:
+        case NodeTag.HasOwn:
+        case NodeTag.HasOwnData:
+        case NodeTag.StrictKeys:
+            return true;
+        case NodeTag.Not:
+            return isComplementSafe(node.value, nodes);
+        case NodeTag.And:
+        case NodeTag.Or:
+            return areComplementSafeValues(node.values, nodes);
+        default:
+            return false;
+    }
+}
+/**
+ * @brief Decide whether every value in a boolean fold is complement-safe.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Operand ids from a nested fold.
+ * @param nodes Graph node table.
+ * @returns True when the whole nested fold can participate in complement laws.
+ */
+function areComplementSafeValues(values, nodes) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined || !isComplementSafe(value, nodes)) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/optimize/compact.d.ts

@@ -1,10 +1,17 @@
 /**
  * @file compact.ts
  * @brief Reachability compaction for optimized graphs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import type { Graph } from "../ir/index.js";
 /**
- * @brief compact reachable.
+ * @brief Remove unreachable IR nodes and remap the remaining node ids densely.
+ * @details Earlier optimizer passes may leave replaced nodes in the arena so
+ * alias bookkeeping stays simple. This pass is the boundary that rewrites the
+ * graph back into the dense id space expected by codegen and public graph reads.
+ * @param graph Graph produced by earlier optimizer passes.
+ * @returns Graph containing only nodes reachable from entry and result.
  */
 export declare function compactReachable(graph: Graph): Graph;
 //# sourceMappingURL=compact.d.ts.map

package/dist/optimize/compact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../src/optimize/compact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAqB,MAAM,gBAAgB,CAAC;AAG/D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAyBpD"}
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../src/optimize/compact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAqB,MAAM,gBAAgB,CAAC;AAG/D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAyBpD"}

package/dist/optimize/compact.js

@@ -1,10 +1,17 @@
 /**
  * @file compact.ts
  * @brief Reachability compaction for optimized graphs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { remapId, remapNode } from "./remap.js";
 /**
- * @brief compact reachable.
+ * @brief Remove unreachable IR nodes and remap the remaining node ids densely.
+ * @details Earlier optimizer passes may leave replaced nodes in the arena so
+ * alias bookkeeping stays simple. This pass is the boundary that rewrites the
+ * graph back into the dense id space expected by codegen and public graph reads.
+ * @param graph Graph produced by earlier optimizer passes.
+ * @returns Graph containing only nodes reachable from entry and result.
  */
 export function compactReachable(graph) {
     const reachable = markReachable(graph);
@@ -33,7 +40,11 @@ export function compactReachable(graph) {
     };
 }
 /**
- * @brief mark reachable.
+ * @brief Mark graph nodes reachable from the entry and result roots.
+ * @details The scan walks dependency edges with an explicit stack to avoid
+ * recursion limits on large generated schemas.
+ * @param graph Graph to scan.
+ * @returns Boolean reachability bitmap aligned with the original node table.
  */
 function markReachable(graph) {
     const reachable = new Array(graph.nodes.length).fill(false);

package/dist/optimize/domain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file domain.ts
+ * @brief Validation-domain specialization for dispatch child graphs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import type { Graph } from "../ir/index.js";
+/**
+ * @brief Specialize nested validation graphs with domain knowledge.
+ * @details Dispatch nodes already know the primitive domain of each child arm.
+ * This pass pushes that fact into child graphs so redundant type checks collapse.
+ * @param graph Root graph to specialize.
+ * @returns The original graph when no node changed, otherwise a rewritten graph.
+ */
+export declare function specializeDomains(graph: Graph): Graph;
+//# sourceMappingURL=domain.d.ts.map

package/dist/optimize/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../src/optimize/domain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAER,KAAK,EAIR,MAAM,gBAAgB,CAAC;AAiDxB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAsBrD"}