@jxsuite/runtime 6.2.2 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "6.2.2",
+  "version": "7.0.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -33,11 +33,12 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.5.0",
+    "@jxsuite/schema": "^6.0.0",
     "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
+    "@jxsuite/erase": "^0.3.0",
     "@jxsuite/test-support": "^0.0.0"
   }
 }

package/src/body-eraser.ts

@@ -0,0 +1,265 @@
+/**
+ * The runtime's seam for TypeScript function bodies (`spec.md` §23.1).
+ *
+ * A string `body` may use erasable TypeScript, and only JavaScript can run, so every body the
+ * runtime compiles goes through {@link compileBody}. The runtime carries no stripper: a host hands
+ * it one, eagerly with {@link setBodyEraser} (`eraseBody` from `@jxsuite/erase/browser`), or lazily
+ * with {@link setBodyEraserLoader}, which is fetched only when a document has a body that needs it.
+ * With neither, a body compiles as written, and one that does not compile says what would fix it.
+ *
+ * The same file carries what imports a module written in TypeScript (`spec.md` §23.2), so the same
+ * loader brings it: {@link moduleLoaderFor} is what the runtime asks before importing one.
+ *
+ * @docs framework/concepts/functions
+ */
+import { isFunctionEntry, isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue, JxClassDef, JxDocument } from "@jxsuite/schema/types";
+import type { JxScopeValue } from "./types.ts";
+
+/** Something erasing found. Only `unsupported` stops a body from running. */
+export interface BodyEraserProblem {
+  kind: string;
+  message: string;
+}
+
+/** What `eraseBody` from `@jxsuite/erase/browser` is: TypeScript in, JavaScript out. */
+export type BodyEraser = (text: string) => {
+  code: string;
+  problems: readonly BodyEraserProblem[];
+};
+
+/** What a host tells {@link ModuleLoader} about one import. */
+export interface ModuleLoadOptions {
+  /** The URL a relative specifier, and a document's path in a `jx-script:` one, resolves against. */
+  base?: string | undefined;
+  /** Where the host serves a package, as given to `setNpmModuleResolver`. */
+  resolveNpm?: ((specifier: string) => string) | null | undefined;
+  /** The module's text when the runtime already holds it, so nothing is fetched for it. */
+  text?: string | undefined;
+}
+
+/**
+ * What `loadModule` from `@jxsuite/erase/browser` is: a TypeScript module's URL, or a document
+ * script's `jx-script:` specifier, in and its namespace out (`spec.md` §23.2).
+ */
+export type ModuleLoader = (specifier: string, options: ModuleLoadOptions) => Promise<object>;
+
+/** What importing `@jxsuite/erase/browser` gives. */
+export interface BodyEraserModule {
+  eraseBody: BodyEraser;
+  /** Absent from an eraser built before document scripts; a TypeScript module then cannot load. */
+  loadModule?: ModuleLoader;
+}
+
+/** A compiled body: called with what its caller passes, returning what its body returns. */
+export type CompiledBody = (...args: never[]) => JxScopeValue;
+
+/** Fetches the eraser, once, when a document first needs it. */
+export type BodyEraserLoader = () => Promise<BodyEraserModule>;
+
+let eraser: BodyEraser | null = null;
+let moduleLoader: ModuleLoader | null = null;
+let loader: BodyEraserLoader | null = null;
+let loading: Promise<void> | null = null;
+
+/** Erased bodies by authored text, so a body erases once however often it compiles. */
+const erased = new Map<string, string>();
+
+/**
+ * Install (or with `null`, remove) the function that erases TypeScript from a body.
+ *
+ * @param fn `eraseBody` from `@jxsuite/erase/browser`.
+ */
+export function setBodyEraser(fn: BodyEraser | null): void {
+  eraser = fn;
+  erased.clear();
+  if (!fn) {
+    // Taken away, so a later document that needs one loads it again.
+    loading = null;
+  }
+}
+
+/**
+ * Install (or with `null`, remove) the function that imports a module written in TypeScript: a
+ * `.ts` file a `$src` names, or a document's own client script (`spec.md` §23.2). A host that sets
+ * {@link setBodyEraserLoader} needs no call to this: the loader it fetches brings one.
+ *
+ * @param fn `loadModule` from `@jxsuite/erase/browser`.
+ */
+export function setModuleLoader(fn: ModuleLoader | null): void {
+  moduleLoader = fn;
+  if (!fn) {
+    // Taken away, so a later module that needs one loads it again.
+    loading = null;
+  }
+}
+
+/** Whether this page can import a TypeScript module: a loader is installed, or can be fetched. */
+export function canLoadModules(): boolean {
+  return moduleLoader !== null || loader !== null;
+}
+
+/** Fetch the eraser through the host's loader, once, and install what it gives. */
+function fetchEraser(load: BodyEraserLoader): Promise<void> {
+  loading ??= load().then((module) => {
+    if (loader !== load) {
+      return;
+    }
+    if (!eraser) {
+      setBodyEraser(module.eraseBody);
+    }
+    if (!moduleLoader && module.loadModule) {
+      setModuleLoader(module.loadModule);
+    }
+  });
+  return loading;
+}
+
+/**
+ * What imports a TypeScript module on this page, fetching the eraser for it when the host said how
+ * and nothing is installed yet. Null when the host gave the page neither.
+ */
+export async function moduleLoaderFor(): Promise<ModuleLoader | null> {
+  if (!moduleLoader && loader) {
+    await fetchEraser(loader);
+  }
+  return moduleLoader;
+}
+
+/**
+ * Say how to fetch the eraser when a document needs it, so a page with no typed body downloads
+ * nothing. The runtime installs what the promise gives.
+ *
+ * @param load Typically `() => import("/path/to/erase.js")`, or null to take it away.
+ */
+export function setBodyEraserLoader(load: BodyEraserLoader | null): void {
+  loader = load;
+  loading = null;
+}
+
+/** Whether text parses as a function body, sync or async. Parsed, never called. */
+function compiles(text: string): boolean {
+  for (const source of [text, `return async function () {\n${text}\n}`]) {
+    try {
+      Reflect.construct(Function, [source]);
+      return true;
+    } catch {
+      // Not as this kind of function; the other may still take it.
+    }
+  }
+  return false;
+}
+
+/** `<…>` followed by a call or a tagged template: a generic call, which JavaScript reads otherwise. */
+const GENERIC_CALL = /<[^<>]*>\s*[(`]/u;
+
+/**
+ * Whether a body needs the eraser before it can run as meant: it does not compile as JavaScript, or
+ * it holds what TypeScript reads as a generic call.
+ *
+ * @param text The body as authored.
+ */
+export function bodyNeedsEraser(text: string): boolean {
+  return GENERIC_CALL.test(text) || !compiles(text);
+}
+
+/**
+ * Every function entry's string body in a tree, accessor halves and `string[]` lines included.
+ *
+ * @param value A document, a class definition, or a part of one.
+ * @yields {string} Each body's text.
+ */
+function* bodiesOf(value: JsonValue): Generator<string> {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      yield* bodiesOf(item);
+    }
+    return;
+  }
+  if (!isJsonObject(value)) {
+    return;
+  }
+  const isFunction = isFunctionEntry(value);
+  for (const [key, child] of Object.entries(value)) {
+    if (isFunction && key === "body") {
+      if (isString(child)) {
+        yield child;
+      } else if (Array.isArray(child) && child.every((line) => isString(line))) {
+        yield child.join("\n");
+      } else {
+        yield* bodiesOf(child);
+      }
+    } else if (isFunction && (key === "getter" || key === "setter") && isJsonObject(child)) {
+      if (isString(child.body)) {
+        yield child.body;
+      }
+    } else {
+      yield* bodiesOf(child);
+    }
+  }
+}
+
+/**
+ * Load the eraser first when anything in a document needs it. Called where the runtime already
+ * waits (a fetched document, a fetched class), so nothing that compiles later has to.
+ *
+ * @param doc A document or class definition.
+ */
+export async function prepareBodies(doc: JsonValue | JxDocument | JxClassDef): Promise<void> {
+  const load = loader;
+  if (eraser || !load) {
+    return;
+  }
+  // SAFETY: a Jx document and a class definition are JSON data; their types name what they hold.
+  const tree = doc as JsonValue;
+  if (!bodiesOf(tree).some((body) => bodyNeedsEraser(body))) {
+    return;
+  }
+  await fetchEraser(load);
+}
+
+/** A body's JavaScript, through the eraser when one is installed. */
+function javaScriptOf(body: string, where: string): string {
+  if (!eraser) {
+    return body;
+  }
+  let code = erased.get(body);
+  if (code === undefined) {
+    const result = eraser(body);
+    const refused = result.problems.find((problem) => problem.kind === "unsupported");
+    if (refused) {
+      throw new SyntaxError(`Jx: ${where} cannot run: ${refused.message}`);
+    }
+    ({ code } = result);
+    erased.set(body, code);
+  }
+  return code;
+}
+
+/**
+ * Compile a function body, erasing its TypeScript first when an eraser is installed.
+ *
+ * @param params The parameter names.
+ * @param body The body as authored.
+ * @param where Names the body in an error, as `'save'` or `the constructor of Counter`.
+ * @throws {SyntaxError} When the body does not compile, naming it, and the call that installs an
+ *   eraser when none is.
+ */
+export function compileBody(params: readonly string[], body: string, where: string): CompiledBody {
+  const code = javaScriptOf(body, where);
+  try {
+    /* SAFETY: `new Function` returns an ordinary function of the named parameters; each caller
+       says what it is called with and what it returns. */
+    return new Function(...params, code) as CompiledBody;
+  } catch (error) {
+    if (!(error instanceof SyntaxError) || eraser) {
+      throw error;
+    }
+    throw new SyntaxError(
+      `Jx: ${where} does not compile as JavaScript (${error.message}). A function body may be ` +
+        `TypeScript: give this page an eraser with setBodyEraser(eraseBody), eraseBody from ` +
+        `@jxsuite/erase/browser.`,
+      { cause: error },
+    );
+  }
+}

package/src/css.ts

@@ -284,7 +284,8 @@ export function splitSelectorList(selector: string): string[] {
  * `null` means "do not emit this rule at all", and `::backdrop` is the one thing it is returned
  * for. There is no backdrop pseudo-element outside the top layer; synthesising one would paint a
  * full-canvas scrim over the document being edited, and emitting an inert rule would mark the
- * selector as "styled" in the Style panel while doing nothing. Preview renders it natively.
+ * selector as "styled" in the Style panel while doing nothing. A page in a browser renders it
+ * natively.
  *
  * @param {string} selector - A fully resolved selector, canvas-side
  * @returns {string | null} The selector to emit, or null to emit nothing

package/src/expression.ts

@@ -13,12 +13,15 @@ import {
   INTL_HELPER_PATHS,
   INTL_LOCALE_PARAM,
 } from "@jxsuite/schema/intl";
-import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { isFunction, isNamedFormulaDef, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type {
   CemParameter,
+  JxDocumentValue,
+  JxExpressionDef,
   JxExpressionNode,
   JxExpressionOperand,
   JxRef,
+  JxStateDefinition,
 } from "@jxsuite/schema/types";
 import type { JxScope, JxScopeValue } from "./types.ts";
 import { readPath, refAccessor, refSegments } from "./pointer.ts";
@@ -341,6 +344,19 @@ function withPageLocale(path: string, args: JxScopeValue[], state: JxScope): JxS
   return filled;
 }
 
+/**
+ * The object a `window#/…` ref reads from. A site build prerenders in a process with no `window`,
+ * where the standard library the blessed list names (Math, JSON, Array, …) hangs off the global
+ * object itself, so the read falls back to it and a formula resolves at build as it does in a
+ * page.
+ */
+function windowRoot(): object {
+  /* SAFETY: the DOM lib types `window` as always present; outside a browser the property is simply
+     absent, which is the one fact this read exists to observe. */
+  const root = (globalThis as { window?: object }).window;
+  return root ?? globalThis;
+}
+
 /** Whether a `window#/…` callee ref is on the blessed pure-globals list. */
 export function isBlessedGlobal(ref: string): boolean {
   return ref.startsWith("window#/") && BLESSED_GLOBALS.has(ref.slice("window#/".length));
@@ -354,6 +370,125 @@ export function isMutating(op: string) {
   return MUTATING_OPS.has(op);
 }
 
+// ─── Pure named formulas, and the ones a component inherits ─────────────────
+
+/** Whether an operand, or any node nested in it, carries a mutating operator. */
+function operandMutates(operand: JxExpressionOperand | undefined): boolean {
+  if (Array.isArray(operand)) {
+    return operand.some((item) => operandMutates(item));
+  }
+  if (operand === undefined || !isNodeOperand(operand)) {
+    return false;
+  }
+  return (
+    isMutating(operand.operator) ||
+    [operand.target, operand.value, operand.initial, operand.default].some((part) =>
+      operandMutates(part),
+    ) ||
+    Object.values(operand.cases ?? {}).some((part) => operandMutates(part))
+  );
+}
+
+/**
+ * Whether a state entry is a pure named formula (spec.md §19.4c): an `$expression` with
+ * `parameters` whose body mutates nothing.
+ *
+ * Such an entry is a function, not reactive state. It holds no value, nothing can write it, and
+ * reading it subscribes to nothing, so the entry by itself gives a page nothing to do in the
+ * browser: only a read of it that is left for the client does (compiler.md §3).
+ *
+ * @param {JxDocumentValue | JxStateDefinition | undefined} def
+ * @returns {boolean}
+ */
+export function isPureNamedFormula(
+  def: JxDocumentValue | JxStateDefinition | undefined,
+): def is JxExpressionDef & { parameters: unknown[] } {
+  return isNamedFormulaDef(def) && !operandMutates(def.$expression);
+}
+
+/** The ref schemes a formula body reads that are not the scope it is built in (spec.md §7.4). */
+const OUTSIDE_SCOPE_REF = /^(?:\$args\/|\$reduce\/|\$map\/|window#\/|document#\/|event#\/)/;
+
+/**
+ * Collect into `into` the state key each scope `$ref` in an operand names. A plain-object literal
+ * is a value, not a tree (spec.md §19.2), so nothing inside one is a read.
+ */
+function collectScopeReads(operand: JxExpressionOperand | undefined, into: Set<string>): void {
+  if (Array.isArray(operand)) {
+    for (const item of operand) {
+      collectScopeReads(item, into);
+    }
+    return;
+  }
+  if (operand === undefined || !isNonNullObject(operand)) {
+    return;
+  }
+  if (isRefOperand(operand)) {
+    if (!OUTSIDE_SCOPE_REF.test(operand.$ref)) {
+      // `#/state/x`, `parent#/x` and a bare `x` all resolve in the scope (spec.md §15.4).
+      const path = operand.$ref.replace(/^(?:#\/state\/|parent#\/)/, "");
+      into.add(refSegments(path)[0] ?? "");
+    }
+    return;
+  }
+  if (isNodeOperand(operand)) {
+    const parts = [operand.target, operand.value, operand.initial, operand.default];
+    for (const part of [...parts, ...Object.values(operand.cases ?? {})]) {
+      collectScopeReads(part, into);
+    }
+  }
+}
+
+/**
+ * The state keys a named formula's body reads from the scope it is built in: every `#/state/key`,
+ * `parent#/key` or schemeless `$ref` in it, by the key it names. `$args/`, an iteration context and
+ * a global are not the scope.
+ *
+ * @param {JxExpressionDef} def
+ * @returns {string[]}
+ */
+export function formulaScopeReads(def: JxExpressionDef): string[] {
+  const reads = new Set<string>();
+  collectScopeReads(def.$expression, reads);
+  return [...reads];
+}
+
+/**
+ * The project `state` entries a component inherits (spec.md §13.4): the pure named formulas that
+ * are closed, meaning every scope read in the body names another inherited formula.
+ *
+ * Only a function crosses the component boundary. A formula that reads project data state would
+ * carry that state across with it, so it stays on the page side, and so does anything that calls
+ * it. The project's injected context names (`$site`, `$page`) are never entries of this kind.
+ *
+ * @param {Record<string, JxStateDefinition> | null | undefined} projectState - `project.json`
+ *   `state`
+ * @returns {Record<string, JxStateDefinition>} In the project's order; empty when there are none
+ * @docs framework/concepts/props-and-scope
+ */
+export function inheritableFormulas(
+  projectState: Record<string, JxStateDefinition> | null | undefined,
+): Record<string, JxStateDefinition> {
+  const candidates = new Map<string, JxExpressionDef>();
+  for (const [key, def] of Object.entries(projectState ?? {})) {
+    if (!key.startsWith("$") && isPureNamedFormula(def)) {
+      candidates.set(key, def);
+    }
+  }
+  // Drop what reads outside the set until nothing does: a caller of a dropped formula goes too.
+  let settled = false;
+  while (!settled) {
+    settled = true;
+    for (const [key, def] of candidates) {
+      if (formulaScopeReads(def).some((read) => !candidates.has(read))) {
+        candidates.delete(key);
+        settled = false;
+      }
+    }
+  }
+  return Object.fromEntries(candidates);
+}
+
 // ─── Runtime Evaluation ──────────────────────────────────────────────────────
 
 interface IterCtx {
@@ -526,7 +661,7 @@ function resolveExprRef(ref: string, state: JxScope, event: Event | null, iterCt
     return readPath(state, ref.slice("parent#/".length));
   }
   if (ref.startsWith("window#/")) {
-    return readPath(globalThis.window, ref.slice("window#/".length));
+    return readPath(windowRoot(), ref.slice("window#/".length));
   }
   if (ref.startsWith("document#/")) {
     return readPath(globalThis.document, ref.slice("document#/".length));
@@ -712,14 +847,12 @@ function evaluateNode(
           ...withPageLocale(globalPath, argValues, state),
         );
       }
+      const root = windowRoot();
       /* SAFETY: `isBlessedGlobal` admitted `globalPath`, and every BLESSED_GLOBALS entry without a
          synthetic helper names a standard-library function on `window` (Math.max, JSON.parse, …). */
-      const fn = readPath(globalThis.window, globalPath) as FormulaCallable;
+      const fn = readPath(root, globalPath) as FormulaCallable;
       const lastSlash = globalPath.lastIndexOf("/");
-      const thisArg =
-        lastSlash === -1
-          ? globalThis.window
-          : readPath(globalThis.window, globalPath.slice(0, lastSlash));
+      const thisArg = lastSlash === -1 ? root : readPath(root, globalPath.slice(0, lastSlash));
       return fn.apply(thisArg, argValues);
     }