@jxsuite/runtime 6.2.1 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "6.2.1",
+  "version": "6.3.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.4.0",
+    "@jxsuite/schema": "^5.6.0",
     "@vue/reactivity": "3.5.44"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
+    "@jxsuite/erase": "^0.2.0",
     "@jxsuite/test-support": "^0.0.0"
   }
 }

package/src/body-eraser.ts

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ *
+ * @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 importing `@jxsuite/erase/browser` gives. */
+export interface BodyEraserModule {
+  eraseBody: BodyEraser;
+}
+
+/** 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 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;
+  }
+}
+
+/**
+ * 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;
+  }
+  loading ??= load().then((module) => {
+    if (loader === load) {
+      setBodyEraser(module.eraseBody);
+    }
+  });
+  await loading;
+}
+
+/** 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/runtime.ts

@@ -52,7 +52,6 @@ import type {
   JxScopeValue,
 } from "./types.ts";
 import {
-  bodyReturnsValue,
   hasStructuredBody,
   isBoolean,
   isExpressionDef,
@@ -71,11 +70,18 @@ import {
   isString,
   isTagExpression,
   isTemplateString,
-  paramNames,
 } from "@jxsuite/schema/guards";
 import type { TagNameSlot } from "@jxsuite/schema/guards";
+import {
+  classifyFunctionEntries,
+  declaresBodyAndSrc,
+  handlerParamNames,
+} from "@jxsuite/schema/function-role";
+import type { FunctionRole } from "@jxsuite/schema/function-role";
 import { formatSrcset, parseSrcset } from "@jxsuite/schema/asset-paths";
 import { runStatements } from "./statements.ts";
+import { compileBody, prepareBodies } from "./body-eraser.ts";
+
 import { readCookie, serializeCookie } from "./cookie.ts";
 import type {
   CemParameter,
@@ -96,6 +102,14 @@ import type {
 } from "@jxsuite/schema/types";
 import type { EffectScope, Ref } from "@vue/reactivity";
 
+export {
+  bodyNeedsEraser,
+  prepareBodies,
+  setBodyEraser,
+  setBodyEraserLoader,
+} from "./body-eraser.ts";
+export type { BodyEraser, BodyEraserLoader, BodyEraserModule } from "./body-eraser.ts";
+
 // ─── Public API ───────────────────────────────────────────────────────────────
 
 /**
@@ -357,6 +371,7 @@ function responseContentType(res: Partial<Pick<Response, "headers">>): string {
 
 export async function resolve(source: string | JxDocument, ctx?: JxContext): Promise<JxDocument> {
   if (!isString(source)) {
+    await prepareBodies(source);
     return source;
   }
   // A mount's resolver answers for THIS mount and its hit never enters the shared cache.
@@ -367,7 +382,7 @@ export async function resolve(source: string | JxDocument, ctx?: JxContext): Pro
   if (_resolveCache.has(source)) {
     return _resolveCache.get(source)!;
   }
-  const p = fetch(source).then(async (res) => {
+  const fetched = fetch(source).then(async (res) => {
     if (!res.ok) {
       throw new Error(`Jx: failed to fetch ${source} (${res.status})`);
     }
@@ -406,6 +421,11 @@ export async function resolve(source: string | JxDocument, ctx?: JxContext): Pro
        the JSON is that document; the runtime does not schema-validate documents by design. */
     return (await res.json()) as JxDocument;
   });
+  // A body that needs the eraser has it before anything compiles, which happens synchronously.
+  const p = fetched.then(async (doc) => {
+    await prepareBodies(doc);
+    return doc;
+  });
   _resolveCache.set(source, p);
   return p;
 }
@@ -1007,8 +1027,15 @@ export async function buildScope(
     }
   }
 
-  // Third pass: $prototype: "Function" entries
+  // Third pass: $prototype: "Function" entries. One verdict per entry, from the document: the same
+  // One every compiled target reads (spec.md §5.3 4b, 4d).
+  const roles = classifyFunctionEntries(doc);
   for (const [key, def] of Object.entries(defs)) {
+    /* Refused ahead of the structured-body branch, so a structured body beside a `$src` is caught
+       too, and by presence, so `body: ""` is (spec.md §5.3 4d). */
+    if (isFunctionDef(def) && declaresBodyAndSrc(def)) {
+      throw new Error(`Jx: '${key}' declares both body and $src — these are mutually exclusive`);
+    }
     if (hasStructuredBody(def)) {
       // Structured body (spec §20): with parameters → a callable mapping positional args onto
       // $args names (invoked via the call operator); without → an event handler.
@@ -1029,7 +1056,7 @@ export async function buildScope(
         state[key] = handler;
       }
     } else if (isFunctionDef(def)) {
-      state[key] = await resolveFunction(def, state, key, base);
+      state[key] = await resolveFunction(def, state, key, roles.get(key) ?? "callable", base);
     }
   }
 
@@ -1589,21 +1616,25 @@ type ScopeFunction = (...args: JxScopeValue[]) => JxScopeValue;
 /**
  * Resolve a $prototype: "Function" entry into a function or computed.
  *
- * Functions receive state as their first parameter at call time. Functions with a return statement
- * in their body are wrapped in computed() for reactive evaluation.
+ * Functions receive state as their first parameter at call time. A `computed` role (decided by
+ * `classifyFunctionEntries` from the document) is wrapped in computed() for reactive evaluation.
  *
  * @param {JxFunctionDef} def - State entry with $prototype: "Function"
  * @param {JxScope} state - Reactive scope proxy
  * @param {string} key - Def key name
+ * @param {FunctionRole} role - The document's verdict for this entry
  * @param {string} [base] - Base URL for resolving $src imports
  * @returns {Promise<JxScopeValue>}
  */
-async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string, base?: string) {
-  if (def.body && def.$src) {
-    throw new Error(`Jx: '${key}' declares both body and $src — these are mutually exclusive`);
-  }
+async function resolveFunction(
+  def: JxFunctionDef,
+  state: JxScope,
+  key: string,
+  role: FunctionRole,
+  base?: string,
+) {
   if (!def.body && !def.$src) {
-    const params = resolveParamNames(def);
+    const params = handlerParamNames(def);
     const noop = new Function(...params, "");
     Object.defineProperty(noop, "name", {
       configurable: true,
@@ -1615,10 +1646,10 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
   let fn: ScopeFunction;
 
   if (isString(def.body)) {
-    const params = resolveParamNames(def);
+    const params = handlerParamNames(def);
     /* SAFETY: `new Function` returns an ordinary function of the named parameters, `state` first.
        A call never checks its arguments, and what the body returns is one more scope member. */
-    fn = new Function(...params, def.body) as ScopeFunction;
+    fn = compileBody(params, def.body, `'${key}'`) as ScopeFunction;
     Object.defineProperty(fn, "name", {
       configurable: true,
       value: def.name ?? key,
@@ -1649,16 +1680,8 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
     fn = candidate as ScopeFunction;
   }
 
-  // Detect computed: body contains a return statement, or $src function introspection.
-  // Functions with parameters (event handlers, callbacks) are never computed.
-  const hasParams = (def.parameters ?? def.arguments ?? []).length > 0;
-  let isComputed = false;
-  if (!hasParams) {
-    isComputed = isString(def.body)
-      ? bodyReturnsValue(def.body)
-      : fn.length <= 1 && bodyReturnsValue(fn.toString());
-  }
-  if (isComputed) {
+  // The role comes from the document (spec.md §5.3 4b, 4d), never from the import's arity or source.
+  if (role === "computed") {
     return computed(() => fn(state));
   }
 
@@ -1667,19 +1690,6 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
 
 // ─── Step 3: Render ───────────────────────────────────────────────────────────
 
-/**
- * Extract parameter names from a function definition. Supports both legacy "arguments" (string
- * array) and CEM-compatible "parameters" (object array). Always ensures "state" is the first
- * parameter.
- *
- * @param {JxFunctionDef | JxPrototypeDef} def
- * @returns {string[]}
- */
-function resolveParamNames(def: JxFunctionDef | JxPrototypeDef) {
-  const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
-  return names.length > 0 && names[0] === "state" ? names : ["state", ...names];
-}
-
 /**
  * Reserved Jx keys — never set as DOM properties.
  *
@@ -2121,6 +2131,11 @@ function bindHandler(
     }
     return true;
   }
+  if (isFunctionDef(val) && declaresBodyAndSrc(val)) {
+    throw new Error(
+      `Jx: inline '${key}' handler declares both body and $src — these are mutually exclusive`,
+    );
+  }
   if (hasStructuredBody(val)) {
     const { body } = val;
     el.addEventListener(type, (e) => {
@@ -2129,10 +2144,10 @@ function bindHandler(
     return true;
   }
   if (isFunctionDef(val) && isString(val.body)) {
-    const params = resolveParamNames(val);
+    const params = handlerParamNames(val);
     /* SAFETY: `new Function` returns an ordinary function of the named parameters, `state` first;
        the listener calls it with the scope and the event, and discards what it returns. */
-    const fn = new Function(...params, val.body) as JxEventHandler;
+    const fn = compileBody(params, val.body, `the ${type} handler`) as JxEventHandler;
     el.addEventListener(type, (e) => fn(scope, e));
     return true;
   }
@@ -3867,6 +3882,7 @@ async function resolveClassJson(def: JxPrototypeDef, state: JxScope, key: string
     // Fall back to dev proxy (server will handle .class.json resolution)
     return resolveViaDevProxy(def, state, key, base);
   }
+  await prepareBodies(classDef);
 
   // Hybrid mode: $implementation points to the real JS module
   if (classDef.$implementation) {
@@ -3934,6 +3950,7 @@ function classFromSchema(classDef: JxClassDef) {
   const rawCtor = classDef.$defs?.constructor;
   const ctor = isCtorDef(rawCtor) ? rawCtor : undefined;
   const methods = classDef.$defs?.methods ?? {};
+  const className = classDef.title ?? "a class";
 
   // oxlint-disable-next-line typescript/no-extraneous-class -- methods are attached to the prototype dynamically below
   class DynClass {
@@ -3961,7 +3978,10 @@ function classFromSchema(classDef: JxClassDef) {
         /* SAFETY: `new Function` returns an ordinary function of the one named parameter; `call`
            runs it with the instance under construction as `this`, which is the constructor
            body's contract. */
-        const init = new Function("config", bodyStr) as (this: DynClass, config: JxScope) => void;
+        const init = compileBody(["config"], bodyStr, `the constructor of ${className}`) as (
+          this: DynClass,
+          config: JxScope,
+        ) => void;
         init.call(this, config);
       }
     }
@@ -3986,7 +4006,11 @@ function classFromSchema(classDef: JxClassDef) {
       if (typedMethod.getter) {
         /* SAFETY: `new Function` returns an ordinary function; as a getter it is called with no
            arguments and the instance as `this`, and what it returns is the property's value. */
-        descriptor.get = new Function(typedMethod.getter.body ?? "") as () => JxScopeValue;
+        descriptor.get = compileBody(
+          [],
+          typedMethod.getter.body ?? "",
+          `the getter ${name} of ${className}`,
+        ) as () => JxScopeValue;
       }
       if (typedMethod.setter) {
         const sp = (typedMethod.setter.parameters ?? []).map(
@@ -3994,18 +4018,20 @@ function classFromSchema(classDef: JxClassDef) {
         );
         /* SAFETY: `new Function` returns an ordinary function of the named parameters; as a setter
            it receives the assigned value as its one argument, and its return is discarded. */
-        descriptor.set = new Function(...sp, typedMethod.setter.body ?? "") as (
-          v: JxScopeValue,
-        ) => void;
+        descriptor.set = compileBody(
+          sp,
+          typedMethod.setter.body ?? "",
+          `the setter ${name} of ${className}`,
+        ) as (v: JxScopeValue) => void;
       }
       Object.defineProperty(DynClass.prototype, name, {
         ...descriptor,
         configurable: true,
       });
     } else if (typedMethod.scope === "static") {
-      DynClass[name] = new Function(...params, bodyStr);
+      DynClass[name] = compileBody(params, bodyStr, `${name} of ${className}`);
     } else {
-      DynClass.prototype[name] = new Function(...params, bodyStr);
+      DynClass.prototype[name] = compileBody(params, bodyStr, `${name} of ${className}`);
     }
   }