@jxsuite/runtime 0.23.2 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -14,19 +14,21 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/runtime.js",
-    "./expression": "./src/expression.js"
+    ".": "./src/runtime.ts",
+    "./expression": "./src/expression.ts",
+    "./types": "./src/types.ts"
   },
   "publishConfig": {
     "provenance": true
   },
   "scripts": {
-    "build": "bun build ./src/runtime.js --outdir dist --target browser --sourcemap=linked",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage",
+    "build": "bun build ./src/runtime.ts --outdir dist --target browser --sourcemap=linked",
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
+    "@jxsuite/schema": "^0.24.0",
     "@vue/reactivity": "^3.5.35"
   },
   "devDependencies": {

package/src/{expression.js → expression.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Jx Declarative Expression Engine (spec §19)
  *
@@ -6,7 +7,17 @@
  * @module expression
  */
 
-/** @typedef {{ operator: string; target: any; value?: any; initial?: any }} ExpressionNode */
+export interface ExpressionNode {
+  operator: string;
+  target: unknown;
+  value?: unknown;
+  initial?: unknown;
+}
+
+interface CompileOpts {
+  statePrefix?: string;
+  eventParam?: string;
+}
 
 const MUTATING_OPS = new Set([
   "=",
@@ -51,54 +62,53 @@ export const BLESSED_OPERATORS = new Set([
  * @param {string} op
  * @returns {boolean}
  */
-export function isMutating(op) {
+export function isMutating(op: string) {
   return MUTATING_OPS.has(op);
 }
 
 // ─── Runtime Evaluation ──────────────────────────────────────────────────────
 
-/**
- * Resolve an operand to its runtime value.
- *
- * @param {any} operand
- * @param {Record<string, any>} state
- * @param {Event | null} event
- * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
- * @returns {any}
- */
-function resolveOperand(operand, state, event, iterCtx) {
+interface IterCtx {
+  acc?: unknown;
+  item?: unknown;
+  index?: number;
+}
+
+/** Resolve an operand to its runtime value. */
+function resolveOperand(
+  operand: unknown,
+  state: Record<string, any>,
+  event: Event | null,
+  iterCtx?: IterCtx,
+): unknown {
   if (operand === null || operand === undefined) return operand;
 
   // Nested expression node
   if (typeof operand === "object" && !Array.isArray(operand) && "operator" in operand) {
-    return evaluateExpression(operand, state, event, iterCtx);
+    return evaluateExpression(operand as ExpressionNode, state, event, iterCtx);
   }
 
   // $ref pointer
   if (typeof operand === "object" && !Array.isArray(operand) && "$ref" in operand) {
-    return resolveExprRef(operand.$ref, state, event, iterCtx);
+    return resolveExprRef((operand as { $ref: string }).$ref, state, event, iterCtx);
   }
 
   // Array of operands (e.g., splice args)
   if (Array.isArray(operand)) {
-    return operand.map((o) => resolveOperand(o, state, event, iterCtx));
+    return operand.map((o: unknown) => resolveOperand(o, state, event, iterCtx));
   }
 
   // Literal
   return operand;
 }
 
-/**
- * Resolve a $ref string within expression context. Handles event#/, $reduce/acc, $map/, #/state/,
- * and other schemes.
- *
- * @param {string} ref
- * @param {Record<string, any>} state
- * @param {Event | null} event
- * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
- * @returns {any}
- */
-function resolveExprRef(ref, state, event, iterCtx) {
+/** Resolve a $ref string within expression context. */
+function resolveExprRef(
+  ref: string,
+  state: Record<string, any>,
+  event: Event | null,
+  iterCtx?: IterCtx,
+) {
   if (ref === "$reduce/acc") {
     return iterCtx?.acc;
   }
@@ -131,16 +141,13 @@ function resolveExprRef(ref, state, event, iterCtx) {
   return state[ref] ?? null;
 }
 
-/**
- * Resolve a $ref to a writable location — returns { obj, key } for assignment.
- *
- * @param {string} ref
- * @param {Record<string, any>} state
- * @param {Event | null} event
- * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
- * @returns {{ obj: any; key: string }}
- */
-function resolveWritableRef(ref, state, event, iterCtx) {
+/** Resolve a $ref to a writable location — returns { obj, key } for assignment. */
+function resolveWritableRef(
+  ref: string,
+  state: Record<string, any>,
+  event: Event | null,
+  iterCtx?: IterCtx,
+) {
   if (ref.startsWith("$map/")) {
     const parts = ref.split("/");
     const key = parts[1];
@@ -152,7 +159,7 @@ function resolveWritableRef(ref, state, event, iterCtx) {
       const pathParts = parts.slice(2);
       const lastKey = pathParts.pop();
       const obj = pathParts.length > 0 ? getPath(base, pathParts.join("/")) : base;
-      return { obj, key: /** @type {string} */ (lastKey) };
+      return { obj, key: lastKey as string };
     }
     return { obj: state.$map ?? state, key: key === "item" ? "$map/item" : "$map/index" };
   }
@@ -164,21 +171,18 @@ function resolveWritableRef(ref, state, event, iterCtx) {
     const lastKey = parts.pop();
     let obj = state;
     for (const p of parts) obj = obj[p];
-    return { obj, key: /** @type {string} */ (lastKey) };
+    return { obj, key: lastKey as string };
   }
   return { obj: state, key: ref };
 }
 
-/**
- * Evaluate an expression node at runtime.
- *
- * @param {ExpressionNode} node
- * @param {Record<string, any>} state
- * @param {Event | null} event
- * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
- * @returns {any}
- */
-export function evaluateExpression(node, state, event, iterCtx) {
+/** Evaluate an expression node at runtime. */
+export function evaluateExpression(
+  node: ExpressionNode,
+  state: Record<string, any>,
+  event: Event | null,
+  iterCtx?: IterCtx,
+): unknown {
   const { operator, target, value, initial } = node;
 
   if (!BLESSED_OPERATORS.has(operator)) {
@@ -187,15 +191,15 @@ export function evaluateExpression(node, state, event, iterCtx) {
 
   // ─── Unary ───
   if (UNARY_OPS.has(operator) && !("value" in node)) {
-    const operand = resolveOperand(target, state, event, iterCtx);
+    const operand: unknown = resolveOperand(target, state, event, iterCtx);
     if (operator === "!") return !operand;
-    if (operator === "-") return -operand;
+    if (operator === "-") return -(operand as number);
   }
 
   // ─── Binary (pure) ───
   if (BINARY_OPS.has(operator)) {
-    const left = resolveOperand(target, state, event, iterCtx);
-    const right = resolveOperand(value, state, event, iterCtx);
+    const left = resolveOperand(target, state, event, iterCtx) as number & string;
+    const right = resolveOperand(value, state, event, iterCtx) as number & string;
     switch (operator) {
       case "+":
         return left + right;
@@ -228,8 +232,13 @@ export function evaluateExpression(node, state, event, iterCtx) {
 
   // ─── Assignment ───
   if (ASSIGNMENT_OPS.has(operator)) {
-    const rhs = resolveOperand(value, state, event, iterCtx);
-    const { obj, key } = resolveWritableRef(target.$ref, state, event, iterCtx);
+    const rhs = resolveOperand(value, state, event, iterCtx) as number;
+    const { obj, key } = resolveWritableRef(
+      (target as { $ref: string }).$ref,
+      state,
+      event,
+      iterCtx,
+    );
     switch (operator) {
       case "=":
         obj[key] = rhs;
@@ -252,7 +261,7 @@ export function evaluateExpression(node, state, event, iterCtx) {
 
   // ─── Array methods ───
   if (ARRAY_METHOD_OPS.has(operator)) {
-    const arr = resolveOperand(target, state, event, iterCtx);
+    const arr: unknown[] = resolveOperand(target, state, event, iterCtx) as unknown[];
     switch (operator) {
       case "push":
         return arr.push(resolveOperand(value, state, event, iterCtx));
@@ -263,65 +272,64 @@ export function evaluateExpression(node, state, event, iterCtx) {
       case "shift":
         return arr.shift();
       case "splice": {
-        const args = resolveOperand(value, state, event, iterCtx);
-        return arr.splice(...args);
+        const args: unknown[] = resolveOperand(value, state, event, iterCtx) as unknown[];
+        return (arr.splice as (...a: unknown[]) => unknown[])(...args);
       }
     }
   }
 
   // ─── Aggregates (pure) ───
   if (AGGREGATE_OPS.has(operator)) {
-    const arr = resolveOperand(target, state, event, iterCtx);
+    const arr: unknown[] = resolveOperand(target, state, event, iterCtx) as unknown[];
     if (operator === "reduce") {
-      const seed = resolveOperand(initial, state, event, iterCtx);
-      return arr.reduce(
-        (/** @type {any} */ acc, /** @type {any} */ item, /** @type {number} */ index) => {
-          return evaluateExpression(value, state, event, { acc, item, index });
-        },
-        seed,
-      );
+      const seed: unknown = resolveOperand(initial, state, event, iterCtx);
+      return arr.reduce((acc: unknown, item: unknown, index: number) => {
+        return evaluateExpression(value as ExpressionNode, state, event, { acc, item, index });
+      }, seed);
     }
     if (operator === "map") {
-      return arr.map((/** @type {any} */ item, /** @type {number} */ index) => {
-        return evaluateExpression(value, state, event, { ...iterCtx, item, index });
+      return arr.map((item: unknown, index: number) => {
+        return evaluateExpression(value as ExpressionNode, state, event, {
+          ...iterCtx,
+          item,
+          index,
+        });
       });
     }
     if (operator === "filter") {
-      return arr.filter((/** @type {any} */ item, /** @type {number} */ index) => {
-        return evaluateExpression(value, state, event, { ...iterCtx, item, index });
+      return arr.filter((item: unknown, index: number) => {
+        return evaluateExpression(value as ExpressionNode, state, event, {
+          ...iterCtx,
+          item,
+          index,
+        });
       });
     }
   }
+
+  return undefined;
 }
 
 // ─── Compiler: Expression → JS Source ────────────────────────────────────────
 
-/** @typedef {{ statePrefix?: string; eventParam?: string }} CompileOpts */
-
-/**
- * Compile an operand to a JS source string.
- *
- * @param {any} operand
- * @param {CompileOpts} opts
- * @returns {string}
- */
-function compileOperand(operand, opts) {
+/** Compile an operand to a JS source string. */
+function compileOperand(operand: unknown, opts: CompileOpts): string {
   if (operand === null) return "null";
   if (operand === undefined) return "undefined";
 
   // Nested expression node
   if (typeof operand === "object" && !Array.isArray(operand) && "operator" in operand) {
-    return compileExpression(operand, opts);
+    return compileExpression(operand as ExpressionNode, opts);
   }
 
   // $ref pointer
   if (typeof operand === "object" && !Array.isArray(operand) && "$ref" in operand) {
-    return compileRef(operand.$ref, opts);
+    return compileRef((operand as { $ref: string }).$ref, opts);
   }
 
   // Array of operands
   if (Array.isArray(operand)) {
-    return operand.map((o) => compileOperand(o, opts)).join(", ");
+    return operand.map((o: unknown) => compileOperand(o, opts)).join(", ");
   }
 
   // Literal
@@ -335,7 +343,7 @@ function compileOperand(operand, opts) {
  * @param {CompileOpts} opts
  * @returns {string}
  */
-function compileRef(ref, opts) {
+function compileRef(ref: string, opts: CompileOpts) {
   const s = opts.statePrefix ?? "state";
   const e = opts.eventParam ?? "event";
 
@@ -371,16 +379,10 @@ function compileRef(ref, opts) {
   return `${s}.${ref}`;
 }
 
-/**
- * Compile a writable $ref target to its JS equivalent (for LHS of assignment).
- *
- * @param {any} target
- * @param {CompileOpts} opts
- * @returns {string}
- */
-function compileTarget(target, opts) {
-  if (typeof target === "object" && "$ref" in target) {
-    return compileRef(target.$ref, opts);
+/** Compile a writable $ref target to its JS equivalent (for LHS of assignment). */
+function compileTarget(target: unknown, opts: CompileOpts): string {
+  if (typeof target === "object" && target !== null && "$ref" in target) {
+    return compileRef((target as { $ref: string }).$ref, opts);
   }
   return compileOperand(target, opts);
 }
@@ -393,33 +395,33 @@ function compileTarget(target, opts) {
  * @param {CompileOpts} [opts]
  * @returns {string}
  */
-export function compileExpression(node, opts = {}) {
+export function compileExpression(node: ExpressionNode, opts: CompileOpts = {}): string {
   const { operator, target, value, initial } = node;
 
   // ─── Unary ───
   if (UNARY_OPS.has(operator) && !("value" in node)) {
-    const operand = compileOperand(target, opts);
+    const operand: string = compileOperand(target, opts);
     if (operator === "!") return `!(${operand})`;
     if (operator === "-") return `-(${operand})`;
   }
 
   // ─── Binary (pure) ───
   if (BINARY_OPS.has(operator)) {
-    const left = compileOperand(target, opts);
-    const right = compileOperand(value, opts);
+    const left: string = compileOperand(target, opts);
+    const right: string = compileOperand(value, opts);
     return `(${left} ${operator} ${right})`;
   }
 
   // ─── Assignment ───
   if (ASSIGNMENT_OPS.has(operator)) {
-    const lhs = compileTarget(target, opts);
-    const rhs = compileOperand(value, opts);
+    const lhs: string = compileTarget(target, opts);
+    const rhs: string = compileOperand(value, opts);
     return `${lhs} ${operator} ${rhs}`;
   }
 
   // ─── Array methods ───
   if (ARRAY_METHOD_OPS.has(operator)) {
-    const arr = compileTarget(target, opts);
+    const arr: string = compileTarget(target, opts);
     switch (operator) {
       case "push":
         return `${arr}.push(${compileOperand(value, opts)})`;
@@ -430,8 +432,8 @@ export function compileExpression(node, opts = {}) {
       case "shift":
         return `${arr}.shift()`;
       case "splice": {
-        const args = Array.isArray(value)
-          ? value.map((o) => compileOperand(o, opts)).join(", ")
+        const args: string = Array.isArray(value)
+          ? value.map((o: unknown) => compileOperand(o, opts)).join(", ")
           : compileOperand(value, opts);
         return `${arr}.splice(${args})`;
       }
@@ -440,10 +442,10 @@ export function compileExpression(node, opts = {}) {
 
   // ─── Aggregates (pure) ───
   if (AGGREGATE_OPS.has(operator)) {
-    const arr = compileOperand(target, opts);
-    const itemExpr = compileExpression(value, opts);
+    const arr: string = compileOperand(target, opts);
+    const itemExpr: string = compileExpression(value as ExpressionNode, opts);
     if (operator === "reduce") {
-      const seed = compileOperand(initial, opts);
+      const seed: string = compileOperand(initial, opts);
       return `${arr}.reduce((_acc, _item, _index) => ${itemExpr}, ${seed})`;
     }
     if (operator === "map") {
@@ -459,11 +461,7 @@ export function compileExpression(node, opts = {}) {
 
 // ─── Utilities ───────────────────────────────────────────────────────────────
 
-/**
- * @param {any} obj
- * @param {string} path
- * @returns {any}
- */
-function getPath(obj, path) {
-  return path.split(/[./]/).reduce((o, k) => /** @type {any} */ (o)?.[k], obj);
+/** Resolve a dotted/slashed path on an object. */
+function getPath(obj: unknown, path: string): unknown {
+  return path.split(/[./]/).reduce((o, k) => (o as Record<string, unknown>)?.[k], obj);
 }