@jxsuite/runtime 4.0.3 → 5.1.0

package/src/statements.ts

@@ -10,6 +10,7 @@
  * `dispatchEvent` with `CustomEventInit` members, `stopPropagation` and `preventDefault`.
  */
 
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
 import {
   compileExpression,
   compileOperandSource,
@@ -17,13 +18,19 @@ import {
   evaluateOperand,
 } from "./expression.ts";
 
-import type { JxStatement } from "@jxsuite/schema/types";
-import type { CompileOpts, ExpressionNode, IterCtx } from "./expression.ts";
+import type {
+  JxDispatchStatement,
+  JxExpressionNode,
+  JxIfStatement,
+  JxStatement,
+  JxSwitchStatement,
+} from "@jxsuite/schema/types";
+import type { CompileOpts, IterCtx } from "./expression.ts";
 import type { JxScope } from "./types.ts";
 
 interface RunOpts {
   /** Named-formula-style arguments bound for $args/<name> refs in the body. */
-  args?: Record<string, unknown>;
+  args?: IterCtx["args"];
   /**
    * Dispatch target for dispatchEvent statements when there is no event to read `currentTarget`
    * from — a parameterised body invoked through `call`, or a lifecycle hook. A thunk is read at
@@ -32,31 +39,49 @@ interface RunOpts {
   target?: EventTarget | null | (() => EventTarget | null);
 }
 
-type StatementKind =
-  | "expression"
-  | "if"
-  | "switch"
-  | "dispatch"
-  | "stopPropagation"
-  | "preventDefault";
+/*
+ * Statement bodies come from documents that are not schema-validated at runtime, so the branch
+ * arrays the schema requires may still be absent; these views say so and keep the fallbacks
+ * honest.
+ */
+interface UncheckedIfStatement extends Omit<JxIfStatement, "then"> {
+  then?: JxStatement[];
+}
+
+interface UncheckedSwitchStatement extends Omit<JxSwitchStatement, "cases"> {
+  cases?: JxSwitchStatement["cases"];
+}
 
-function statementKind(statement: JxStatement): StatementKind {
+type ClassifiedStatement =
+  | { kind: "expression"; node: JxExpressionNode }
+  | { kind: "if"; node: UncheckedIfStatement }
+  | { kind: "switch"; node: UncheckedSwitchStatement }
+  | { kind: "dispatch"; node: JxDispatchStatement }
+  | { kind: "stopPropagation" }
+  | { kind: "preventDefault" };
+
+function classifyStatement(statement: JxStatement): ClassifiedStatement {
   if ("operator" in statement) {
-    return "expression";
+    return { kind: "expression", node: statement };
   }
   if ("if" in statement) {
-    return "if";
+    return { kind: "if", node: statement };
   }
   if ("$switch" in statement) {
-    return "switch";
+    return { kind: "switch", node: statement };
   }
   if ("stopPropagation" in statement) {
-    return "stopPropagation";
+    return { kind: "stopPropagation" };
   }
   if ("preventDefault" in statement) {
-    return "preventDefault";
+    return { kind: "preventDefault" };
   }
-  return "dispatch";
+  return { kind: "dispatch", node: statement };
+}
+
+/** A value `await` would adopt: anything with a callable `then` (ECMA-262 thenable). */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (isNonNullObject(value) || isFunction(value)) && "then" in value && isFunction(value.then);
 }
 
 /**
@@ -72,16 +97,18 @@ export async function runStatements(
 ): Promise<void> {
   const iterCtx: IterCtx | undefined = opts.args ? { args: opts.args } : undefined;
   for (const statement of statements) {
-    switch (statementKind(statement)) {
+    const classified = classifyStatement(statement);
+    switch (classified.kind) {
       case "expression": {
-        const result = evaluateExpression(statement as ExpressionNode, state, event, iterCtx);
-        if (result && typeof (result as PromiseLike<unknown>).then === "function") {
-          await (result as PromiseLike<unknown>);
+        const result = evaluateExpression(classified.node, state, event, iterCtx);
+        if (isThenable(result)) {
+          // Awaited for its ordering alone: the next statement runs once this one settles.
+          void (await result);
         }
         break;
       }
       case "if": {
-        const branch = statement as { if: unknown; then: JxStatement[]; else?: JxStatement[] };
+        const branch = classified.node;
         const taken = evaluateOperand(branch.if, state, event, iterCtx) ? branch.then : branch.else;
         if (Array.isArray(taken)) {
           await runStatements(taken, state, event, opts);
@@ -89,11 +116,7 @@ export async function runStatements(
         break;
       }
       case "switch": {
-        const branch = statement as {
-          $switch: unknown;
-          cases: Record<string, JxStatement[]>;
-          default?: JxStatement[];
-        };
+        const branch = classified.node;
         const key = String(evaluateOperand(branch.$switch, state, event, iterCtx));
         const cases = branch.cases ?? {};
         const taken = Object.hasOwn(cases, key) ? cases[key] : branch.default;
@@ -103,14 +126,9 @@ export async function runStatements(
         break;
       }
       case "dispatch": {
-        const dispatch = statement as {
-          dispatchEvent: string;
-          detail?: unknown;
-          bubbles?: boolean;
-          composed?: boolean;
-        };
+        const dispatch = classified.node;
         // An event's own target wins; the option is the fallback for bodies run without one.
-        const fallback = typeof opts.target === "function" ? opts.target() : opts.target;
+        const fallback = isFunction(opts.target) ? opts.target() : opts.target;
         const target = event?.currentTarget ?? fallback;
         if (!target) {
           break;
@@ -164,13 +182,14 @@ export function compileStatements(
   const indent = opts.indent ?? "";
   const lines: string[] = [];
   for (const statement of statements) {
-    switch (statementKind(statement)) {
+    const classified = classifyStatement(statement);
+    switch (classified.kind) {
       case "expression": {
-        lines.push(`${indent}${compileExpression(statement as ExpressionNode, opts)};`);
+        lines.push(`${indent}${compileExpression(classified.node, opts)};`);
         break;
       }
       case "if": {
-        const branch = statement as { if: unknown; then: JxStatement[]; else?: JxStatement[] };
+        const branch = classified.node;
         const test = compileOperandSource(branch.if, opts);
         const inner = { ...opts, indent: `${indent}  ` };
         lines.push(`${indent}if (${test}) {`, compileStatements(branch.then ?? [], inner));
@@ -181,11 +200,7 @@ export function compileStatements(
         break;
       }
       case "switch": {
-        const branch = statement as {
-          $switch: unknown;
-          cases: Record<string, JxStatement[]>;
-          default?: JxStatement[];
-        };
+        const branch = classified.node;
         const disc = compileOperandSource(branch.$switch, opts);
         const inner = { ...opts, indent: `${indent}    ` };
         lines.push(`${indent}switch (String(${disc})) {`);
@@ -208,12 +223,7 @@ export function compileStatements(
         break;
       }
       case "dispatch": {
-        const dispatch = statement as {
-          dispatchEvent: string;
-          detail?: unknown;
-          bubbles?: boolean;
-          composed?: boolean;
-        };
+        const dispatch = classified.node;
         const eventName = opts.eventParam ?? "event";
         const target = opts.dispatchTarget ?? `(${eventName} && ${eventName}.currentTarget)`;
         const init: string[] = [];

package/src/types.ts

@@ -1,17 +1,101 @@
 /// <reference lib="dom" />
-import type { JxDocument, JxElement, JxPath } from "@jxsuite/schema/types";
+import type { JxDocument, JxDocumentValue, JxElement, JxPath } from "@jxsuite/schema/types";
+import type { Ref } from "@vue/reactivity";
 
 export type { JxPath } from "@jxsuite/schema/types";
 
 /**
- * The live reactive scope: a prototype-chained object whose keys are user-defined state names.
- * Values are runtime JS values (signals, functions, JSON data) and must be narrowed at use — this
- * alias marks the dynamic boundary by name.
+ * What one member of a {@link JxScope} holds: every kind of value the runtime puts into a scope or
+ * hands to a document's code.
+ *
+ * - A document's own values (`JxDocumentValue`): JSON, and the typed shapes a naked `state` entry, a
+ *   `$`-local or a literal `$props` value copies in (spec.md §5.3).
+ * - `undefined`, for a member or an argument that is absent.
+ * - Arrays and records of scope values: reactive objects, host records, `$props`, and the instance an
+ *   external class constructs (spec.md §12.3), every one of them read by member name.
+ * - Functions ({@link JxScopeFunction}): handlers, formulas, `$src` exports, server-function proxies
+ *   and a host's own functions.
+ * - Refs: the computed and data-source entries the reactive proxy unwraps on read.
+ * - The `$map` context a mapped row renders under ({@link JxRowContext}).
+ * - DOM objects: event targets (nodes, the window, the document) and events, which `window#/`,
+ *   `document#/` and `event#/` references read.
+ * - The platform objects a `$prototype` entry resolves to (spec.md §11.2): `Map`, `Set`, `FormData`,
+ *   `Blob`, and the `IDBObjectStore` an `IndexedDB` entry's `getStore()` yields.
+ * - A promise of any of those: a computed entry over an `async` function settles later.
+ *
+ * Narrow it with the guards in `@jxsuite/schema/guards`, which work on the union.
  */
-export type JxScope = Record<string, unknown>;
+export type JxScopeValue = JxSettledValue | Promise<JxSettledValue>;
+
+/**
+ * A scope member that is not a promise: what a {@link JxScopeValue} settles to. A promise never
+ * fulfils with another promise, which is what lets an `await` on a scope member end.
+ */
+export type JxSettledValue =
+  | JxDocumentValue
+  | undefined
+  | JxScopeValue[]
+  | readonly JxScopeValue[]
+  | JxScope
+  | JxScopeFunction
+  | Ref<JxScopeValue>
+  | JxRowContext
+  | EventTarget
+  | Event
+  | ReadonlyMap<JxScopeValue, JxScopeValue>
+  | ReadonlySet<JxScopeValue>
+  | FormData
+  | Blob
+  | IDBObjectStore;
+
+/**
+ * The live reactive scope (spec.md §15): a prototype-chained record of state entries, `$props`, a
+ * host's members and the runtime's `$` vocabulary, each read and written by name.
+ */
+export interface JxScope {
+  [name: string]: JxScopeValue;
+}
+
+/**
+ * A function a scope holds, as the scope sees it: a handler, a formula, a `$src` export, a
+ * server-function proxy or a host's own function. JavaScript checks neither the arguments a call
+ * passes nor what it returns, so this is every function; a call site narrows it to the signature it
+ * calls with, and a result it reads is a scope member by the contract of whatever stored the
+ * function (a computed entry, a formula, a server call).
+ */
+export type JxScopeFunction = (...args: never[]) => void;
+
+/**
+ * The `$map` context a mapped row renders under (spec.md §10.2): the row's item, and its index in
+ * the list. Both are written in place when the row is reused.
+ */
+export interface JxRowContext {
+  index: number;
+  item: JxScopeValue;
+}
+
+/**
+ * A value a host hands the runtime, held to {@link JxScopeValue} member by member.
+ *
+ * A host declares its scope with interfaces, and TypeScript gives an interface no implicit index
+ * signature, so a host's record is never assignable to {@link JxScope}, however its members are
+ * typed. This walks the declared type instead: a scope value stays as it is, a `bigint` or a
+ * `symbol` is refused (neither is a scope value), a function is held to what it returns, and
+ * anything else — an array, a record — is held member by member.
+ */
+export type JxHostValue<T> = T extends JxScopeValue
+  ? T
+  : T extends bigint | symbol
+    ? never
+    : T extends (...args: infer A) => infer R
+      ? (...args: A) => JxHostValue<R>
+      : { [K in keyof T]: JxHostValue<T[K]> };
+
+/** A host's scope, held to {@link JxScopeValue} member by member (see {@link JxHostValue}). */
+export type JxHostScope<S> = { [K in keyof S]: JxHostValue<S[K]> };
 
 /** An event handler stored in the scope: `(scope, event) => void`. */
-export type JxEventHandler = (scope: JxScope, event: Event) => unknown;
+export type JxEventHandler = (scope: JxScope, event: Event) => void;
 
 /**
  * A host-supplied document source consulted before the network. Returning `undefined` means "not
@@ -42,14 +126,17 @@ export interface JxContext {
   skipAutoRequests?: boolean;
 }
 
-/** Options for {@link mount}: the host's half of the embedding contract (specs/embedding.md). */
-export interface JxMountOptions {
+/**
+ * Options for {@link mount}: the host's half of the embedding contract (specs/embedding.md). `S` is
+ * the host's own scope type, which `mount` holds to {@link JxHostScope}.
+ */
+export interface JxMountOptions<S = JxScope> {
   /**
    * Host members merged into the document's scope before its own `state` is built: reactive
    * records, refs, computeds and plain functions. A document `state` entry of the same name wins.
    * Keys beginning with `$` or `#` are runtime vocabulary and are refused.
    */
-  scope?: Record<string, unknown>;
+  scope?: S;
   base?: string;
   media?: Record<string, string>;
   resolver?: DocumentResolver;
@@ -71,7 +158,7 @@ export interface JxMount {
    * touches.
    */
   readonly elements: ReadonlySet<string>;
-  /** Stops every effect, calls `onUnmount`, removes the root. Idempotent. */
+  /** Removes the root, stops every effect, then calls `onUnmount`. Idempotent. */
   readonly dispose: () => void;
 }
 
@@ -112,8 +199,22 @@ export interface JxRenderOptions {
   onNodeMoved?: (node: HTMLElement | Text, path: JxPath) => void;
 }
 
+/**
+ * A method body compiled by `new Function` from a `.class.json` method definition. Only document
+ * code calls it, so its arguments and result are opaque to TypeScript.
+ */
+export type DynamicMethod = (...args: never[]) => void;
+
+/** The prototype of a {@link DynamicClass}: instance methods attached by name. */
+export type DynamicPrototype = Record<string, DynamicMethod>;
+
+/**
+ * A class built at runtime from a `.class.json` definition. Its static side carries the static
+ * methods attached by name beside the prototype; an instance holds the constructor `config` values
+ * under its field names.
+ */
 export interface DynamicClass {
-  new (config?: Record<string, unknown>): Record<string, unknown>;
-  [key: string]: unknown;
-  prototype: Record<string, unknown>;
+  new (config?: JxScope): JxScope;
+  [member: string]: DynamicMethod | DynamicPrototype;
+  prototype: DynamicPrototype;
 }