@jxsuite/schema 5.6.0 → 6.0.2

package/src/jxn/virtual-types.ts

@@ -19,19 +19,27 @@
  *
  * @docs framework/concepts/functions
  */
-import { classifyFunctionEntries } from "../function-role";
+import { isJsonObject } from "../guards";
 import {
-  isBoolean,
-  isExpressionDef,
-  isFunctionDef,
-  isJsonObject,
-  isNumber,
-  isServerFnDef,
-  isString,
-  paramNames,
-  hasSchemaKeywords,
-} from "../guards";
-import type { JsonValue, JxElement } from "../../types";
+  boundEvents,
+  eventLines,
+  eventType,
+  itemType,
+  EXCEPT,
+  heritageOf,
+  membersOf,
+  readsRow,
+  rootSite,
+  siteInto,
+} from "./document-scopes";
+import type { Site, StateScope } from "./document-scopes";
+import { definitionParts, definitionsOf, pointerInto, propertyName, written } from "./schema-types";
+import { declaredParameters, stateIndex, typeOfEntry } from "./state-types";
+import type { OutsideState } from "./state-types";
+import type { JsonObject, JsonValue, JxElement } from "../../types";
+
+export { givenByProject, outsideAt } from "./state-types";
+export type { OutsideState, ProjectGives } from "./state-types";
 
 /** Where a body sits in a document. */
 export type VirtualTarget =
@@ -66,164 +74,73 @@ export interface VirtualBody {
  */
 export const UNRESOLVED_MODULE_CODES: ReadonlySet<number> = new Set([2307, 2792, 7016]);
 
-/** The most levels of an object's shape written out before it is `any`. */
-const MAX_NESTING = 4;
-
-/** The most distinct item types an array's type is built from. */
-const MAX_ITEM_TYPES = 6;
-
-/** Whether a key can be written as a bare property name. */
-const IDENTIFIER = /^[A-Za-z_$][\w$]*$/u;
-
-/** A property name as TypeScript writes it. */
-function propertyName(key: string): string {
-  return IDENTIFIER.test(key) ? key : JSON.stringify(key);
-}
-
-/** The type a value's shape gives it, widened the way a mutable binding widens. */
-function typeOfValue(value: JsonValue | undefined, depth: number): string {
-  if (isString(value)) {
-    return "string";
-  }
-  if (isNumber(value)) {
-    return "number";
-  }
-  if (isBoolean(value)) {
-    return "boolean";
-  }
-  if (Array.isArray(value)) {
-    const types = [...new Set(value.map((item) => typeOfValue(item, depth + 1)))];
-    if (types.length === 0 || types.length > MAX_ITEM_TYPES || types.includes("any")) {
-      return "any[]";
-    }
-    return types.length === 1 ? `${types[0]}[]` : `(${types.join(" | ")})[]`;
-  }
-  if (isJsonObject(value) && depth < MAX_NESTING) {
-    const members = Object.entries(value).map(
-      ([key, item]) => `${propertyName(key)}: ${typeOfValue(item, depth + 1)}`,
-    );
-    return members.length === 0 ? "Record<string, any>" : `{ ${members.join("; ")} }`;
-  }
-  return "any";
-}
-
-/** The type a JSON Schema `type` keyword names. */
-function typeOfKeyword(type: JsonValue | undefined): string {
-  switch (type) {
-    case "string": {
-      return "string";
-    }
-    case "number":
-    case "integer": {
-      return "number";
-    }
-    case "boolean": {
-      return "boolean";
-    }
-    case "array": {
-      return "any[]";
-    }
-    default: {
-      return "any";
-    }
-  }
-}
-
-/** The type of one `state` entry, by the shapes of `spec.md` §5. */
-function typeOfEntry(
-  entry: JsonValue | undefined,
-  role: "computed" | "callable" | undefined,
-): string {
-  if (isString(entry)) {
-    // A template is a computed value of a type the document does not give.
-    return entry.includes("${") ? "any" : "string";
-  }
-  if (!isJsonObject(entry)) {
-    return typeOfValue(entry, 0);
-  }
-  if (isFunctionDef(entry)) {
-    return role === "computed" ? "any" : "(...args: any[]) => any";
-  }
-  if (isString(entry.$prototype) || isExpressionDef(entry) || isServerFnDef(entry)) {
-    return "any";
-  }
-  if ("default" in entry) {
-    const { default: initial } = entry;
-    return initial === null ? typeOfKeyword(entry.type) : typeOfValue(initial, 0);
-  }
-  return hasSchemaKeywords(entry) ? typeOfKeyword(entry.type) : typeOfValue(entry, 0);
-}
-
-/** The `state` object of an element, when it has one. */
-function stateOf(node: JsonValue | undefined): Record<string, JsonValue> | null {
-  return isJsonObject(node) && isJsonObject(node.state) ? node.state : null;
+/** What a target names: the function entry, and what surrounds the element that holds it. */
+interface Located {
+  definition: JsonValue | undefined;
+  /** The type of the event the body is given. */
+  event: string;
+  site: Site;
 }
 
-/**
- * The elements whose `state` a body can read, outermost first: the root, then each element on the
- * way down to the one holding the handler. A nested element's scope extends its parent's.
- */
-function scopeChain(doc: JxElement, path: readonly (string | number)[]): JsonValue[] {
-  // SAFETY: a document is JSON data; its types name what it holds.
-  let current: JsonValue | undefined = doc as JsonValue;
-  const chain: JsonValue[] = [current];
-  for (const segment of path) {
-    current = Array.isArray(current)
-      ? current[Number(segment)]
-      : isJsonObject(current)
-        ? current[String(segment)]
-        : undefined;
-    if (stateOf(current)) {
-      // SAFETY: `stateOf` only answers for an object.
-      chain.push(current as JsonValue);
-    }
-  }
-  return chain;
-}
-
-/** The function entry a target names. */
-function definitionOf(doc: JxElement, target: VirtualTarget): JsonValue | undefined {
-  // SAFETY: a document is JSON data; its types name what it holds.
-  const root = doc as JsonValue;
+/** Find a target in a document. */
+function locate(doc: JsonObject, target: VirtualTarget): Located {
+  let site = rootSite(doc);
   if (target.kind === "state") {
-    return stateOf(root)?.[target.key];
+    const event = boundEvents(doc).get(pointerInto("/state", target.key)) ?? "any";
+    return { definition: isJsonObject(doc.state) ? doc.state[target.key] : undefined, event, site };
   }
-  let owner: JsonValue | undefined = root;
+  let owner: JsonValue | undefined = doc;
+  let pointer = "";
   for (const segment of target.path) {
-    owner = Array.isArray(owner)
+    const child: JsonValue | undefined = Array.isArray(owner)
       ? owner[Number(segment)]
       : isJsonObject(owner)
         ? owner[String(segment)]
         : undefined;
+    pointer = pointerInto(pointer, segment);
+    site = siteInto(site, owner, segment, child, pointer);
+    owner = child;
   }
-  return isJsonObject(owner) ? owner[target.eventKey] : undefined;
-}
-
-/** The names a function is called with: `state` first, then the declared names (`spec.md` §5.3). */
-function parametersOf(definition: JsonValue | undefined): string[] {
-  if (!isJsonObject(definition)) {
-    return ["state"];
-  }
-  const declared = Array.isArray(definition.parameters)
-    ? // SAFETY: `parameters` holds bare names or CEM parameter objects, the form `paramNames` reads.
-      paramNames(definition.parameters as Parameters<typeof paramNames>[0])
-    : (Array.isArray(definition.arguments) ? definition.arguments : []).filter(
-        (name): name is string => isString(name),
-      );
-  return declared[0] === "state" ? declared : ["state", ...declared];
+  return isJsonObject(owner)
+    ? { definition: owner[target.eventKey], event: eventType(owner, target.eventKey, site), site }
+    : { definition: undefined, event: "any", site };
 }
 
-/** The members of `State`, each from the innermost element that declares it. */
-function stateMembers(chain: readonly JsonValue[]): Map<string, string> {
-  const members = new Map<string, string>();
-  for (const node of chain) {
-    // SAFETY: a document is JSON data, and the chain holds only elements that carry state.
-    const roles = classifyFunctionEntries(node as JxElement);
-    for (const [key, entry] of Object.entries(stateOf(node) ?? {})) {
-      members.set(propertyName(key), typeOfEntry(entry, roles.get(key)));
+/**
+ * Write the `State` a body reads: one interface for each element on the way down that has `state`,
+ * each under the one around it, and over them the row of the map the body is drawn in.
+ */
+function stateLines(site: Site, index: string, defs: boolean): string[] {
+  const chain: StateScope[] = [];
+  for (let at: StateScope | null = site.scope; at; at = at.parent) {
+    chain.unshift(at);
+  }
+  const inRow = site.row !== null && readsRow(site.scope);
+  // The innermost is `State` itself, unless the row is written over it.
+  const nameOf = (scope: StateScope): string =>
+    scope === site.scope && !inRow ? "State" : `State$${chain.indexOf(scope)}`;
+  // The helper is declared only where a scope reads through it: an unused one is a finding.
+  const lines: string[] = chain.some((scope) => membersOf(scope).shadowed.length > 0)
+    ? [EXCEPT]
+    : [];
+  for (const scope of chain) {
+    const { own, shadowed } = membersOf(scope);
+    const around = scope.parent ? nameOf(scope.parent) : null;
+    const heritage = around === null ? "" : ` extends ${heritageOf(around, shadowed)}`;
+    lines.push(`interface ${nameOf(scope)}${heritage} {`);
+    for (const { entry, key, role } of own) {
+      lines.push(`  ${propertyName(key)}: ${typeOfEntry(entry, role, defs)};`);
     }
+    lines.push(...(around === null ? [`  ${index}`, "}"] : ["}"]));
   }
-  return members;
+  if (site.row && inRow) {
+    lines.push(
+      `interface State extends ${nameOf(site.scope)} {`,
+      `  $map: { item: ${itemType(site.row, nameOf)}; index: number };`,
+      "}",
+    );
+  }
+  return lines;
 }
 
 /**
@@ -233,30 +150,38 @@ function stateMembers(chain: readonly JsonValue[]): Map<string, string> {
  * @param target Which body: a root `state` entry, or an inline handler on an element.
  * @param body The body's text, which need not be the text the document holds yet (an editor's
  *   buffer is checked as typed).
+ * @param outside What the document's project gives it, which makes `State` open. Nothing, when the
+ *   reader knows of no project.
  * @returns The file to check, and where the body sits in it.
  */
 export function generateBodyTypes(
   doc: JxElement,
   target: VirtualTarget,
   body: string,
+  outside: OutsideState = {},
 ): VirtualBody {
-  const params = parametersOf(definitionOf(doc, target));
-  const chain = scopeChain(doc, target.kind === "event" ? target.path : []);
-  const members = [...stateMembers(chain)].map(([name, type]) => `  ${name}: ${type};`);
-  /* A page with a layout inherits state the page does not name, so its `State` is open. Without
-     one, only the `$` members the host adds (`$media`, `$props`) are. */
-  members.push(doc.$layout === undefined ? "  [key: `$${string}`]: any;" : "  [key: string]: any;");
-  const signature = params.map((name) => `${name}: ${name === "state" ? "State" : "any"}`);
+  // SAFETY: a document is JSON data; its types name what it holds.
+  const data = doc as JsonObject;
+  const located = locate(data, target);
+  const defs = definitionsOf(data);
+  const declared = declaredParameters(located.definition, { defs: defs !== null, pointer: "" });
+  const params = declared.map((parameter) => parameter.name);
   /* The event a handler receives is bound to a name only when the entry declares one, though the
      runtime passes it and `window.event` holds it. Not declaring it would call a working handler
-     an error, so it is `any` wherever it is not a parameter. */
+     an error, so it is declared wherever it is not a parameter. */
+  const event = eventLines(located.event, params);
+  /* A handler is called with its state and the event, in that order (`spec.md` §5.3), and a
+     parameter that declares a type is that type, the event's place included (§23.3). */
+  const signature = declared.map((parameter, at) => {
+    const untyped = at === 1 ? event.parameter : "any";
+    const type = parameter.type === null ? untyped : written(parameter.type);
+    return `${parameter.name}: ${at === 0 ? "State" : type}`;
+  });
   const head = [
     "export {};",
-    "interface State {",
-    ...members,
-    "}",
-    "declare const event: any;",
-    `async function body(${["this: any", ...signature].join(", ")}) {`,
+    ...(defs ? [written(definitionParts(defs, false))] : []),
+    ...stateLines(located.site, stateIndex(doc, outside), defs !== null),
+    `${event.head}async function body(${["this: any", ...signature].join(", ")}) {`,
     "",
   ].join("\n");
   return {

package/src/schema.ts

@@ -408,6 +408,28 @@ export async function generateSchema() {
         examples: ["./layouts/base.json"],
         oneOf: [{ type: "string" }, { const: false, type: "boolean" }],
       },
+      $script: {
+        additionalProperties: false,
+        description:
+          "This document's own modules, as TypeScript module text (spec.md §23.2). " +
+          'A state entry names an export of one with `$src: "#client"` or `$src: "#server"`. ' +
+          "`client` runs in the browser; `server` runs only on the server and is never sent to one.",
+        properties: {
+          client: {
+            description:
+              'The module the browser runs. A Function entry with `$src: "#client"` is one of ' +
+              "its exports.",
+            type: "string",
+          },
+          server: {
+            description:
+              'The module the server runs. A `timing: "server"` entry with `$src: "#server"` is ' +
+              "one of its exports, called with `(args, env)`.",
+            type: "string",
+          },
+        },
+        type: "object",
+      },
       $shadow: {
         description:
           "Render this component into a shadow root instead of the light DOM (spec.md §16.6). " +

package/types.ts

@@ -385,6 +385,20 @@ export interface JxMappedArray {
   key?: JxRef;
 }
 
+/**
+ * A document's own modules, as `$script` holds them: TypeScript module text for each side.
+ *
+ * A type alias rather than an interface, because a document member has to be a `JxDocumentValue`,
+ * and only an alias is given the implicit index signature that makes an object type one.
+ */
+// oxlint-disable-next-line typescript/consistent-type-definitions -- See above.
+export type JxDocumentScripts = {
+  /** The module the browser runs. Its exports are what `$src: "#client"` entries name. */
+  client?: string;
+  /** The module the server runs. Its exports are what `$src: "#server"` entries name. */
+  server?: string;
+};
+
 export interface JxDocument extends JxElement {
   /**
    * The custom element's NAME, always a literal.
@@ -397,6 +411,8 @@ export interface JxDocument extends JxElement {
   tagName?: string;
   state?: Record<string, JxStateDefinition>;
   $layout?: string | false;
+  /** This document's own client and server modules (spec.md §23.2). */
+  $script?: JxDocumentScripts;
   /** This page's identity across languages, overriding the one its path implies (§13.5). */
   $translationKey?: string;
   $paths?: JxPathsDef;