typesea 0.1.0 → 0.2.0

package/dist/optimize/fold-scalar.js

@@ -1,11 +1,20 @@
 /**
  * @file fold-scalar.ts
  * @brief Constant folding for scalar graph nodes.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { NodeTag } from "../kind/index.js";
 import { ensureConst, isFiniteNumber, isPlainRecord, keep, readConst, replace } from "./fold-common.js";
 /**
- * @brief fold get prop.
+ * @brief Fold property reads whose receiver is already a literal constant.
+ * @details Lowered graphs never materialize object literals as safe Const data,
+ * so a constant receiver cannot provide a trustworthy property slot. The node
+ * folds to undefined instead of executing user accessors during optimization.
+ * @param node Property-read node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the property read.
  */
 export function foldGetProp(node, nodes, aliases) {
     const value = readConst(nodes, node.object);
@@ -15,7 +24,14 @@ export function foldGetProp(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold unary.
+ * @brief Fold unary predicate nodes when their subject is constant.
+ * @details Each predicate mirrors the runtime validator's exact primitive test,
+ * including finite-number and plain-record semantics, so compile-time folding
+ * cannot widen the accepted value set.
+ * @param node Unary predicate node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the predicate.
  */
 export function foldUnary(node, nodes, aliases) {
     const value = readConst(nodes, node.value);
@@ -48,7 +64,13 @@ export function foldUnary(node, nodes, aliases) {
     }
 }
 /**
- * @brief fold equals.
+ * @brief Fold literal equality when both operands are constants.
+ * @details `Object.is` is used so NaN and negative zero follow TypeSea literal
+ * equality semantics instead of JavaScript `===` corner cases.
+ * @param node Equality node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the equality node.
  */
 export function foldEquals(node, nodes, aliases) {
     const left = readConst(nodes, node.left);
@@ -59,7 +81,13 @@ export function foldEquals(node, nodes, aliases) {
     return replace(node, ensureConst(nodes, aliases, Object.is(left.value, right.value)));
 }
 /**
- * @brief fold numeric.
+ * @brief Fold numeric comparisons with two constant operands.
+ * @details Non-number operands fold to false, matching the runtime predicate
+ * path where numeric schema checks require number values before comparison.
+ * @param node Numeric comparison node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the comparison node.
  */
 export function foldNumeric(node, nodes, aliases) {
     const left = readConst(nodes, node.left);
@@ -74,7 +102,13 @@ export function foldNumeric(node, nodes, aliases) {
     return replace(node, ensureConst(nodes, aliases, result));
 }
 /**
- * @brief fold string bound.
+ * @brief Fold string length predicates with a constant subject.
+ * @details Non-string subjects fold to false because the separate string guard
+ * may later be removed or reordered by boolean simplification.
+ * @param node String bound node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the string bound node.
  */
 export function foldStringBound(node, nodes, aliases) {
     const value = readConst(nodes, node.value);
@@ -87,7 +121,13 @@ export function foldStringBound(node, nodes, aliases) {
     return replace(node, ensureConst(nodes, aliases, result));
 }
 /**
- * @brief fold regex.
+ * @brief Fold regular expression checks with a constant string subject.
+ * @details `lastIndex` is reset before and after the test so global or sticky
+ * expressions cannot leak state across optimizer and runtime use.
+ * @param node Regex node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the regex node.
  */
 export function foldRegex(node, nodes, aliases) {
     const value = readConst(nodes, node.value);
@@ -103,7 +143,14 @@ export function foldRegex(node, nodes, aliases) {
     return replace(node, ensureConst(nodes, aliases, result));
 }
 /**
- * @brief fold has own.
+ * @brief Fold own-property presence checks on constant receivers.
+ * @details Const nodes do not carry safe object identity, so the optimizer never
+ * inspects properties here. A constant receiver means the object check cannot be
+ * satisfied through this IR path and folds to false.
+ * @param node Own-property check node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the own-property check.
  */
 export function foldHasOwn(node, nodes, aliases) {
     const value = readConst(nodes, node.object);
@@ -113,7 +160,13 @@ export function foldHasOwn(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold has own data.
+ * @brief Fold own-data-property checks on constant receivers.
+ * @details The optimizer refuses to execute descriptors or getters. Constant
+ * receivers therefore fold to false instead of probing runtime object state.
+ * @param node Own-data-property check node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the data-property check.
  */
 export function foldHasOwnData(node, nodes, aliases) {
     const value = readConst(nodes, node.object);
@@ -123,7 +176,14 @@ export function foldHasOwnData(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold strict keys.
+ * @brief Fold strict-key checks on constant receivers.
+ * @details Strict-key validation depends on own property keys. The optimizer
+ * does not enumerate runtime objects, so constant receivers fold to false and
+ * non-constant receivers stay intact.
+ * @param node Strict-key node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the strict-key node.
  */
 export function foldStrictKeys(node, nodes, aliases) {
     const value = readConst(nodes, node.object);
@@ -133,7 +193,14 @@ export function foldStrictKeys(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold array every.
+ * @brief Fold array iteration nodes with constant receivers.
+ * @details Iteration semantics require reading runtime indexes and child
+ * schemas. Constants cannot safely stand in for arrays here, so the node folds
+ * to false only when the receiver is already constant.
+ * @param node Array iteration node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the array iteration node.
  */
 export function foldArrayEvery(node, nodes, aliases) {
     const value = readConst(nodes, node.value);
@@ -143,7 +210,13 @@ export function foldArrayEvery(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold tuple items.
+ * @brief Fold tuple item checks with constant receivers.
+ * @details Tuple validation depends on array length and descriptor-backed item
+ * reads, so the optimizer does not simulate it for constant receivers.
+ * @param node Tuple item node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the tuple item node.
  */
 export function foldTupleItems(node, nodes, aliases) {
     const value = readConst(nodes, node.value);
@@ -153,7 +226,13 @@ export function foldTupleItems(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold record every.
+ * @brief Fold record iteration nodes with constant receivers.
+ * @details Record validation must enumerate own keys at runtime. The optimizer
+ * keeps non-constant records intact and folds constant receivers closed.
+ * @param node Record iteration node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the record iteration node.
  */
 export function foldRecordEvery(node, nodes, aliases) {
     const value = readConst(nodes, node.value);
@@ -163,7 +242,13 @@ export function foldRecordEvery(node, nodes, aliases) {
     return keep(node);
 }
 /**
- * @brief fold discriminant dispatch.
+ * @brief Fold discriminant dispatch nodes with constant receivers.
+ * @details Dispatch requires an object tag read, which the optimizer does not
+ * perform on constants. Non-constant receivers remain available for codegen.
+ * @param node Discriminant dispatch node to fold.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the dispatch node.
  */
 export function foldDiscriminantDispatch(node, nodes, aliases) {
     const value = readConst(nodes, node.value);

package/dist/optimize/fold.d.ts

@@ -1,10 +1,17 @@
 /**
  * @file fold.ts
  * @brief Constant folding pass driver.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import type { Graph } from "../ir/index.js";
 /**
- * @brief fold constants.
+ * @brief Run the constant and local simplification pass over one graph.
+ * @details The pass keeps an alias table instead of deleting nodes mid-scan.
+ * That gives every later node a stable source id while dependencies are
+ * rewritten to their canonical replacements.
+ * @param graph Input graph to simplify.
+ * @returns Graph with folded nodes and resolved dependency aliases.
  */
 export declare function foldConstants(graph: Graph): Graph;
 //# sourceMappingURL=fold.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../src/optimize/fold.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,KAAK,EAGN,MAAM,gBAAgB,CAAC;AAoBxB;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAsCjD"}
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../src/optimize/fold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACR,KAAK,EAGR,MAAM,gBAAgB,CAAC;AAoBxB;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAsCjD"}

package/dist/optimize/fold.js

@@ -1,6 +1,8 @@
 /**
  * @file fold.ts
  * @brief Constant folding pass driver.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { NodeTag } from "../kind/index.js";
 import { foldAnd, foldOr } from "./fold-boolean.js";
@@ -8,7 +10,12 @@ import { keep } from "./fold-common.js";
 import { foldArrayEvery, foldDiscriminantDispatch, foldEquals, foldGetProp, foldHasOwn, foldHasOwnData, foldNumeric, foldRecordEvery, foldRegex, foldStrictKeys, foldStringBound, foldTupleItems, foldUnary } from "./fold-scalar.js";
 import { resolveAlias, rewriteNodeDeps } from "./rewrite.js";
 /**
- * @brief fold constants.
+ * @brief Run the constant and local simplification pass over one graph.
+ * @details The pass keeps an alias table instead of deleting nodes mid-scan.
+ * That gives every later node a stable source id while dependencies are
+ * rewritten to their canonical replacements.
+ * @param graph Input graph to simplify.
+ * @returns Graph with folded nodes and resolved dependency aliases.
  */
 export function foldConstants(graph) {
     const originalLength = graph.nodes.length;
@@ -46,7 +53,14 @@ export function foldConstants(graph) {
     };
 }
 /**
- * @brief fold node.
+ * @brief Dispatch one graph node to the local folding rule for its tag.
+ * @details Structural nodes that cannot be simplified locally are kept intact.
+ * Boolean nodes delegate to algebraic and constraint passes because their
+ * simplification depends on the whole value vector.
+ * @param node Node whose dependencies have already been rewritten.
+ * @param nodes Mutable node table for this folding pass.
+ * @param aliases Mutable alias table for replacement nodes.
+ * @returns Fold result containing the updated node and optional alias.
  */
 function foldNode(node, nodes, aliases) {
     switch (node.tag) {
@@ -93,6 +107,12 @@ function foldNode(node, nodes, aliases) {
             return foldRecordEvery(node, nodes, aliases);
         case NodeTag.DiscriminantDispatch:
             return foldDiscriminantDispatch(node, nodes, aliases);
+        case NodeTag.ObjectShape:
+            return keep(node);
+        case NodeTag.UnionDispatch:
+            return keep(node);
+        case NodeTag.PrimitiveUnion:
+            return keep(node);
         case NodeTag.SchemaCheck:
             return keep(node);
         case NodeTag.And:

package/dist/optimize/index.d.ts

@@ -1,10 +1,18 @@
 /**
  * @file index.ts
  * @brief Public graph optimizer pipeline.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { type Graph } from "../ir/index.js";
 /**
- * @brief optimize graph.
+ * @brief Run the public graph optimization pipeline.
+ * @details Pass order is intentionally conservative: constant folding exposes
+ * local identities, peephole rewriting removes adjacent graph noise, domain
+ * specialization reasons about repeated validation loops, and compaction drops
+ * nodes made unreachable by earlier replacements.
+ * @param graph Frozen or mutable TypeSea graph to optimize.
+ * @returns Frozen graph after all optimizer passes have completed.
  */
 export declare function optimizeGraph(graph: Graph): Graph;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/optimize/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,gBAAgB,CAAC;AAIxB;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAGjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/optimize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGH,KAAK,KAAK,EACb,MAAM,gBAAgB,CAAC;AAMxB;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAGjD"}

package/dist/optimize/index.js

@@ -1,19 +1,34 @@
 /**
  * @file index.ts
  * @brief Public graph optimizer pipeline.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { freezeGraph, isGraphValue } from "../ir/index.js";
 import { compactReachable } from "./compact.js";
+import { specializeDomains } from "./domain.js";
 import { foldConstants } from "./fold.js";
+import { peepholeGraph } from "./peephole.js";
 /**
- * @brief optimize graph.
+ * @brief Run the public graph optimization pipeline.
+ * @details Pass order is intentionally conservative: constant folding exposes
+ * local identities, peephole rewriting removes adjacent graph noise, domain
+ * specialization reasons about repeated validation loops, and compaction drops
+ * nodes made unreachable by earlier replacements.
+ * @param graph Frozen or mutable TypeSea graph to optimize.
+ * @returns Frozen graph after all optimizer passes have completed.
  */
 export function optimizeGraph(graph) {
     const input = readGraph(graph);
-    return freezeGraph(compactReachable(foldConstants(input)));
+    return freezeGraph(compactReachable(specializeDomains(peepholeGraph(foldConstants(input)))));
 }
 /**
- * @brief read graph.
+ * @brief Validate optimizer input before mutating pass-local copies.
+ * @details Public callers may pass arbitrary values through JavaScript module
+ * boundaries. The optimizer fails at the edge rather than letting malformed IR
+ * reach passes that assume node ids and dependency arrays are well formed.
+ * @param value Candidate graph value.
+ * @returns Frozen graph value accepted by the IR validator.
  */
 function readGraph(value) {
     if (!isGraphValue(value)) {

package/dist/optimize/map-node.d.ts

@@ -1,10 +1,12 @@
 /**
  * @file map-node.ts
  * @brief Shared graph node-id mapping utility.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import type { GraphNode, NodeId } from "../ir/index.js";
 /**
- * @brief node id mapper.
+ * @brief Rewrite callback for arena-local node ids.
  * @details Converts one graph node id into the id visible in a rewritten graph.
  * @invariant The caller owns range validation for the returned id.
  */

package/dist/optimize/map-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-node.d.ts","sourceRoot":"","sources":["../../src/optimize/map-node.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,SAAS,EACT,MAAM,EACP,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,GACT,SAAS,CA+LX"}
+{"version":3,"file":"map-node.d.ts","sourceRoot":"","sources":["../../src/optimize/map-node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACR,SAAS,EACT,MAAM,EACT,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAErD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACtB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,GACX,SAAS,CAuOX"}

package/dist/optimize/map-node.js

@@ -1,6 +1,8 @@
 /**
  * @file map-node.ts
  * @brief Shared graph node-id mapping utility.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { NodeTag } from "../kind/index.js";
 /**
@@ -134,7 +136,8 @@ export function mapNodeIds(node, mapId, id) {
                 tag: node.tag,
                 deps: [value],
                 value,
-                item: node.item
+                item: node.item,
+                itemGraph: node.itemGraph
             };
         }
         case NodeTag.TupleItems: {
@@ -144,7 +147,8 @@ export function mapNodeIds(node, mapId, id) {
                 tag: node.tag,
                 deps: [value],
                 value,
-                items: node.items
+                items: node.items,
+                itemGraphs: node.itemGraphs
             };
         }
         case NodeTag.RecordEvery: {
@@ -154,7 +158,8 @@ export function mapNodeIds(node, mapId, id) {
                 tag: node.tag,
                 deps: [value],
                 value,
-                item: node.item
+                item: node.item,
+                itemGraph: node.itemGraph
             };
         }
         case NodeTag.DiscriminantDispatch: {
@@ -167,9 +172,46 @@ export function mapNodeIds(node, mapId, id) {
                 key: node.key,
                 literals: node.literals,
                 schemas: node.schemas,
+                graphs: node.graphs,
                 lookup: node.lookup
             };
         }
+        case NodeTag.ObjectShape: {
+            const value = mapId(node.value);
+            return {
+                id,
+                tag: node.tag,
+                deps: [value],
+                value,
+                entries: node.entries,
+                keys: node.keys,
+                mode: node.mode,
+                allRequired: node.allRequired
+            };
+        }
+        case NodeTag.UnionDispatch: {
+            const value = mapId(node.value);
+            return {
+                id,
+                tag: node.tag,
+                deps: [value],
+                value,
+                options: node.options,
+                graphs: node.graphs,
+                masks: node.masks
+            };
+        }
+        case NodeTag.PrimitiveUnion: {
+            const value = mapId(node.value);
+            return {
+                id,
+                tag: node.tag,
+                deps: [value],
+                value,
+                graphs: node.graphs,
+                masks: node.masks
+            };
+        }
         case NodeTag.SchemaCheck: {
             const value = mapId(node.value);
             return {

package/dist/optimize/peephole.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file peephole.ts
+ * @brief Local graph rewrites that remove dead dispatch arms.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import type { Graph } from "../ir/index.js";
+/**
+ * @brief Run local dispatch compaction over one graph.
+ * @details This pass removes child arms that already fold to false and rewrites
+ * aliases after each replacement so later nodes see the simplified ids.
+ * @param graph Graph to optimize.
+ * @returns Graph with compacted dispatch nodes and resolved aliases.
+ */
+export declare function peepholeGraph(graph: Graph): Graph;
+//# sourceMappingURL=peephole.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"peephole.d.ts","sourceRoot":"","sources":["../../src/optimize/peephole.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAGR,KAAK,EAKR,MAAM,gBAAgB,CAAC;AAKxB;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CA+CjD"}