@jxsuite/compiler 0.23.2 → 0.25.0

package/src/targets/{compile-class.js → compile-class.ts}

@@ -5,6 +5,8 @@
  * Schema 2020-12 class definition.
  */
 
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
 /**
  * Compile a .class.json schema to a JavaScript ES module string.
  *
@@ -12,18 +14,17 @@
  * @param {Record<string, unknown>} [_opts]
  * @returns {string} JavaScript module source code
  */
-export function compileClassJson(classDef, _opts = {}) {
+export function compileClassJson(classDef: JxMutableNode, _opts: Record<string, unknown> = {}) {
   const className = classDef.title;
   if (!className) throw new Error("compileClassJson: missing title (class name)");
 
   const baseClass = resolveBaseClass(classDef.extends);
-  const defs = /** @type {Record<string, unknown> | undefined} */ (classDef.$defs);
-  const fields = /** @type {Record<string, JxMutableNode>} */ (defs?.fields ?? {});
-  const ctor = /** @type {JxMutableNode | undefined} */ (defs?.constructor);
-  const methods = /** @type {Record<string, JxMutableNode>} */ (defs?.methods ?? {});
+  const defs = classDef.$defs as Record<string, unknown> | undefined;
+  const fields = (defs?.fields ?? {}) as Record<string, JxMutableNode>;
+  const ctor = defs?.constructor as JxMutableNode | undefined;
+  const methods = (defs?.methods ?? {}) as Record<string, JxMutableNode>;
 
-  /** @type {string[]} */
-  const lines = [];
+  const lines: string[] = [];
   lines.push("// Generated by @jxsuite/compiler from .class.json — do not edit manually");
   if (classDef.$id) lines.push(`// Source: ${classDef.$id}`);
   lines.push("");
@@ -34,7 +35,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Static fields
   for (const [key, field] of Object.entries(fields)) {
-    const f = /** @type {JxMutableNode} */ (field);
+    const f = field as JxMutableNode;
     if (f.scope !== "static") continue;
     const name = f.identifier ?? key;
     const prefix = f.access === "private" ? "#" : "";
@@ -49,7 +50,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Instance field declarations (private)
   for (const [key, field] of Object.entries(fields)) {
-    const f = /** @type {JxMutableNode} */ (field);
+    const f = field as JxMutableNode;
     if (f.scope === "static") continue;
     if (f.access !== "private") continue;
     const name = f.identifier ?? key;
@@ -67,7 +68,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Initialize instance fields from config or defaults
   for (const [key, field] of Object.entries(fields)) {
-    const f = /** @type {JxMutableNode} */ (field);
+    const f = field as JxMutableNode;
     if (f.scope === "static") continue;
     const name = f.identifier ?? key;
     const prefix = f.access === "private" ? "#" : "";
@@ -93,7 +94,7 @@ export function compileClassJson(classDef, _opts = {}) {
 
   // Methods
   for (const [key, method] of Object.entries(methods)) {
-    const m = /** @type {JxMutableNode} */ (method);
+    const m = method as JxMutableNode;
     const name = m.identifier ?? key;
     const isStatic = m.scope === "static";
     const isPrivate = m.access === "private";
@@ -101,7 +102,7 @@ export function compileClassJson(classDef, _opts = {}) {
     const staticPrefix = isStatic ? "static " : "";
     const asyncPrefix =
       m.returnType?.$ref?.includes("Promise") ||
-      isMethodAsync(/** @type {{ body?: string | string[] }} */ (/** @type {unknown} */ (m)))
+      isMethodAsync(m as unknown as { body?: string | string[] })
         ? "async "
         : "";
 
@@ -148,10 +149,10 @@ export function compileClassJson(classDef, _opts = {}) {
  * @param {unknown} ext
  * @returns {string}
  */
-function resolveBaseClass(ext) {
+function resolveBaseClass(ext: unknown) {
   if (!ext) return "Object";
   if (typeof ext === "string") return ext;
-  const e = /** @type {JxMutableNode} */ (ext);
+  const e = ext as JxMutableNode;
   if (e.$ref) {
     const ref = e.$ref;
     const match = ref.match(/([A-Za-z0-9_]+)\.class\.json/);
@@ -166,10 +167,10 @@ function resolveBaseClass(ext) {
  * @param {unknown[]} params
  * @returns {string}
  */
-function resolveParams(params) {
+function resolveParams(params: unknown[]) {
   return params
     .map((p) => {
-      const param = /** @type {JxMutableNode} */ (p);
+      const param = p as JxMutableNode;
       if (param.$ref) return param.$ref.split("/").pop();
       return param.identifier ?? param.name ?? "arg";
     })
@@ -182,10 +183,10 @@ function resolveParams(params) {
  * @param {unknown} body
  * @returns {string[]}
  */
-function resolveBody(body) {
+function resolveBody(body: unknown) {
   if (!body) return [""];
   if (Array.isArray(body)) return body;
-  return [/** @type {string} */ (body)];
+  return [body as string];
 }
 
 /**
@@ -194,7 +195,7 @@ function resolveBody(body) {
  * @param {{ body?: string | string[] }} method
  * @returns {boolean}
  */
-function isMethodAsync(method) {
+function isMethodAsync(method: { body?: string | string[] }) {
   const body = Array.isArray(method.body) ? method.body.join("\n") : (method.body ?? "");
   return body.includes("await ");
 }

package/src/targets/{compile-client.js → compile-client.ts}

@@ -25,7 +25,9 @@ import {
   DEFAULT_LIT_HTML_SRC,
   compileExpression,
   isMutating,
-} from "../shared.js";
+} from "../shared.ts";
+import type { ExpressionNode } from "../shared.ts";
+import type { JxStyle, JxMutableNode } from "@jxsuite/schema/types";
 
 /**
  * Compile a Jx document to pre-rendered HTML + reactive JS module.
@@ -34,43 +36,38 @@ import {
  * @param {Record<string, unknown>} opts
  * @returns {{ html: string; files: { path: string; content: string }[] }}
  */
-export function compileClient(raw, opts) {
+export function compileClient(
+  raw: JxMutableNode | Record<string, any>,
+  opts: Record<string, unknown>,
+) {
   const {
     title,
     reactivitySrc = DEFAULT_REACTIVITY_SRC,
     litHtmlSrc = DEFAULT_LIT_HTML_SRC,
     modulePath = "app.js",
-  } = /** @type {JxMutableNode} */ (opts);
+  } = opts as JxMutableNode;
 
   const context = createCompileContext(raw, null, raw.state ?? {}, raw.$media ?? {});
   const styleBlock = compileStyles(
     raw,
     raw.$media ?? {},
-    /** @type {JxStyle | null} */ (opts.projectStyle ?? null),
+    (opts.projectStyle ?? null) as JxStyle | null,
   );
 
   // Collectors for bindings and handlers
   const counter = { t: 0, s: 0, h: 0, m: 0, sw: 0, l: 0, needsLit: false };
-  /** @type {Map<string, string>} */
-  const bindings = new Map(); // key → expression string
-  /** @type {Map<string, any>} */
-  const handlers = new Map(); // key → { body, args }
+  const bindings: Map<string, string> = new Map(); // key → expression string
+  const handlers: Map<string, any> = new Map(); // key → { body, args }
 
   // Classify state entries into reactive state, computed, bind, on, and init blocks
-  /** @type {[string, any][]} */
-  const stateEntries = []; // [key, initValue]  → reactive({...})
-  /** @type {[string, string][]} */
-  const computedEntries = []; // [key, bodyExpr]   → state.key = computed(...)
-  /** @type {[string, string][]} */
-  const bindEntries = []; // [key, bodyExpr]   → bind = {...}
-  /** @type {[string, any][]} */
-  const onEntries = []; // [key, { args, body }] → on = {...}
-  /** @type {string[]} */
-  const initBlocks = []; // lines emitted after state for prototype init
+  const stateEntries: [string, any][] = []; // [key, initValue]  → reactive({...})
+  const computedEntries: [string, string][] = []; // [key, bodyExpr]   → state.key = computed(...)
+  const bindEntries: [string, string][] = []; // [key, bodyExpr]   → bind = {...}
+  const onEntries: [string, any][] = []; // [key, { args, body }] → on = {...}
+  const initBlocks: string[] = []; // lines emitted after state for prototype init
 
   // Map $src path → Set of function names to import
-  /** @type {Map<string, Set<string>>} */
-  const srcImportMap = new Map();
+  const srcImportMap: Map<string, Set<string>> = new Map();
 
   const defs = raw.state ?? {};
   for (const [key, def] of Object.entries(defs)) {
@@ -85,11 +82,11 @@ export function compileClient(raw, opts) {
       continue;
     }
 
-    const d = /** @type {JxMutableNode} */ (def);
+    const d = def as JxMutableNode;
 
     // $expression: Shape 5
     if ("$expression" in d) {
-      const node = /** @type {any} */ (d).$expression;
+      const node = (d as Record<string, unknown>).$expression as ExpressionNode;
       if (isMutating(node.operator)) {
         const compiled = compileExpression(node, { statePrefix: "state", eventParam: "e" });
         onEntries.push([key, { args: ["state", "e"], body: compiled }]);
@@ -105,7 +102,7 @@ export function compileClient(raw, opts) {
       const args = d.parameters ?? d.arguments;
       if (d.$src) {
         if (!srcImportMap.has(d.$src)) srcImportMap.set(d.$src, new Set());
-        /** @type {Set<string>} */ (srcImportMap.get(d.$src)).add(key);
+        (srcImportMap.get(d.$src) as Set<string>).add(key);
 
         // $src functions always produce computed entries (they return values)
         computedEntries.push([key, "() => { return " + key + "(state); }"]);
@@ -232,7 +229,14 @@ ${importmapEntries.join(",\n")}
  * }} counter
  * @returns {string}
  */
-function buildClientNode(def, raw, context, bindings, handlers, counter) {
+function buildClientNode(
+  def: JxMutableNode,
+  raw: JxMutableNode,
+  context: any,
+  bindings: Map<string, string>,
+  handlers: Map<string, any>,
+  counter: { t: number; s: number; h: number; m: number; sw: number; l: number; needsLit: boolean },
+) {
   // String children are text nodes
   if (typeof def === "string") {
     return escapeHtml(def);
@@ -255,13 +259,11 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
 
   // textContent bindings
   if (def.textContent !== undefined) {
-    const tc = /** @type {JxMutableNode} */ (
-      /** @type {unknown} */ (raw?.textContent ?? def.textContent)
-    );
+    const tc = raw?.textContent ?? (def.textContent as unknown as JxMutableNode);
     if (isRefObject(tc)) {
-      const key = refToBindingKey(/** @type {string} */ (tc.$ref));
+      const key = refToBindingKey((tc as JxMutableNode).$ref as string);
       bindAttrs.push(`:text-content="${key}"`);
-      addRefBinding(bindings, key, /** @type {string} */ (tc.$ref));
+      addRefBinding(bindings, key, (tc as JxMutableNode).$ref as string);
       needsBind = true;
     } else if (isTemplateString(tc)) {
       const key = `_t${counter.t++}`;
@@ -276,15 +278,11 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
     if (!prop.startsWith("on") || prop === "observedAttributes") continue;
     const eventName = prop.slice(2).toLowerCase();
     if (isRefObject(val)) {
-      const key = refToBindingKey(/** @type {string} */ (/** @type {JxMutableNode} */ (val).$ref));
+      const key = refToBindingKey((val as JxMutableNode).$ref as string);
       bindAttrs.push(`@${eventName}="${key}"`);
       needsBind = true;
-    } else if (
-      val &&
-      typeof val === "object" &&
-      /** @type {JxMutableNode} */ (val).$prototype === "Function"
-    ) {
-      const v = /** @type {JxMutableNode} */ (val);
+    } else if (val && typeof val === "object" && (val as JxMutableNode).$prototype === "Function") {
+      const v = val as JxMutableNode;
       const key = `_h${counter.h++}`;
       bindAttrs.push(`@${eventName}="${key}"`);
       handlers.set(key, { args: v.parameters ?? v.arguments ?? ["state", "event"], body: v.body });
@@ -292,10 +290,13 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
     } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ (val)) {
       const key = `_h${counter.h++}`;
       bindAttrs.push(`@${eventName}="${key}"`);
-      const compiled = compileExpression(/** @type {any} */ (val).$expression, {
-        statePrefix: "state",
-        eventParam: "e",
-      });
+      const compiled = compileExpression(
+        (val as Record<string, unknown>).$expression as ExpressionNode,
+        {
+          statePrefix: "state",
+          eventParam: "e",
+        },
+      );
       handlers.set(key, { args: ["state", "e"], body: compiled });
       needsBind = true;
     }
@@ -326,15 +327,9 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
   if (def.attributes && typeof def.attributes === "object") {
     for (const [attr, val] of Object.entries(def.attributes)) {
       if (isRefObject(val)) {
-        const key = refToBindingKey(
-          /** @type {string} */ (/** @type {JxMutableNode} */ (val).$ref),
-        );
+        const key = refToBindingKey((val as JxMutableNode).$ref as string);
         bindAttrs.push(`:attr.${attr}="${key}"`);
-        addRefBinding(
-          bindings,
-          key,
-          /** @type {string} */ (/** @type {JxMutableNode} */ (val).$ref),
-        );
+        addRefBinding(bindings, key, (val as JxMutableNode).$ref as string);
         needsBind = true;
       } else if (isTemplateString(val)) {
         const key = `_t${counter.t++}`;
@@ -362,9 +357,9 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
     )
       continue;
     if (isRefObject(val)) {
-      const key = refToBindingKey(/** @type {string} */ (/** @type {JxMutableNode} */ (val).$ref));
+      const key = refToBindingKey((val as JxMutableNode).$ref as string);
       bindAttrs.push(`:${camelToKebab(prop)}="${key}"`);
-      addRefBinding(bindings, key, /** @type {string} */ (/** @type {JxMutableNode} */ (val).$ref));
+      addRefBinding(bindings, key, (val as JxMutableNode).$ref as string);
       needsBind = true;
     } else if (isTemplateString(val)) {
       const key = `_t${counter.t++}`;
@@ -391,18 +386,17 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
   } else if (source.innerHTML) {
     // resolveStaticValue may return null if innerHTML contains `${` from rendered content
     // (e.g., code examples) that isn't an actual template expression. Fall back to raw value.
-    inner = /** @type {string} */ (resolveStaticValue(source.innerHTML, nextContext.scope)) ??
-    source.innerHTML;
+    inner = (resolveStaticValue(source.innerHTML, nextContext.scope) as string) ?? source.innerHTML;
   } else if (
     source.children &&
     typeof source.children === "object" &&
     !Array.isArray(source.children) &&
-    /** @type {JxMutableNode} */ (source.children).$prototype === "Array"
+    (source.children as JxMutableNode).$prototype === "Array"
   ) {
     // ─── Mapped array → lit-html render binding ───
     counter.needsLit = true;
     const listKey = `_list${counter.l++}`;
-    const arrayDef = /** @type {JxMutableNode} */ (source.children);
+    const arrayDef = source.children as JxMutableNode;
 
     // Resolve items source expression
     let itemsExpr;
@@ -436,8 +430,8 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
       .map((c, i) => {
         const childRaw = rawChildren?.[i] ?? c;
         return buildClientNode(
-          /** @type {JxMutableNode} */ (/** @type {unknown} */ (c)),
-          /** @type {JxMutableNode} */ (/** @type {unknown} */ (childRaw)),
+          c as unknown as JxMutableNode,
+          childRaw as unknown as JxMutableNode,
           nextContext,
           bindings,
           handlers,
@@ -465,7 +459,7 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
  * @param {JxMutableNode} def
  * @returns {string}
  */
-function emitLitMapTemplate(def) {
+function emitLitMapTemplate(def: JxMutableNode) {
   if (!def) return "";
   const tag = def.tagName ?? "div";
   let attrs = "";
@@ -486,8 +480,7 @@ function emitLitMapTemplate(def) {
 
   // style → inline CSS
   if (def.style && typeof def.style === "object") {
-    /** @type {string[]} */
-    const parts = [];
+    const parts: string[] = [];
     for (const [k, v] of Object.entries(def.style)) {
       if (
         k.startsWith(":") ||
@@ -515,20 +508,19 @@ function emitLitMapTemplate(def) {
     if (!prop.startsWith("on") || prop === "observedAttributes") continue;
     const eventName = prop.slice(2).toLowerCase();
     if (isRefObject(val)) {
-      const key = refToBindingKey(/** @type {string} */ (/** @type {JxMutableNode} */ (val).$ref));
+      const key = refToBindingKey((val as JxMutableNode).$ref as string);
       attrs += " @" + eventName + "=${(e) => { state.$map = { item, index }; on." + key + "(e); }}";
-    } else if (
-      val &&
-      typeof val === "object" &&
-      /** @type {JxMutableNode} */ (val).$prototype === "Function"
-    ) {
-      const body = mapRefsToLit(/** @type {string} */ (/** @type {JxMutableNode} */ (val).body));
+    } else if (val && typeof val === "object" && (val as JxMutableNode).$prototype === "Function") {
+      const body = mapRefsToLit((val as JxMutableNode).body as string);
       attrs += " @" + eventName + "=${(e) => { " + body + " }}";
     } else if (val && typeof val === "object" && "$expression" in /** @type {any} */ (val)) {
-      const compiled = compileExpression(/** @type {any} */ (val).$expression, {
-        statePrefix: "state",
-        eventParam: "e",
-      });
+      const compiled = compileExpression(
+        (val as Record<string, unknown>).$expression as ExpressionNode,
+        {
+          statePrefix: "state",
+          eventParam: "e",
+        },
+      );
       attrs += " @" + eventName + "=${(e) => { state.$map = { item, index }; " + compiled + "; }}";
     }
   }
@@ -545,11 +537,7 @@ function emitLitMapTemplate(def) {
     if (isTemplateString(tc)) {
       inner = mapRefsToLit(tc);
     } else if (isRefObject(def.textContent)) {
-      const path = refToBindingKey(
-        /** @type {string} */ (
-          /** @type {JxMutableNode} */ (/** @type {unknown} */ (def.textContent)).$ref
-        ),
-      );
+      const path = refToBindingKey((def.textContent as unknown as JxMutableNode).$ref as string);
       inner = "${state." + path + "}";
     } else {
       inner = escapeHtml(tc);
@@ -559,9 +547,7 @@ function emitLitMapTemplate(def) {
   } else if (Array.isArray(def.children)) {
     inner =
       "\n      " +
-      def.children
-        .map((c) => emitLitMapTemplate(/** @type {JxMutableNode} */ (c)))
-        .join("\n      ") +
+      def.children.map((c) => emitLitMapTemplate(c as JxMutableNode)).join("\n      ") +
       "\n    ";
   }
 
@@ -576,7 +562,7 @@ function emitLitMapTemplate(def) {
  * @param {string} str
  * @returns {string}
  */
-function mapRefsToLit(str) {
+function mapRefsToLit(str: string) {
   return str.replace(/\$map\./g, "");
 }
 
@@ -602,17 +588,16 @@ function mapRefsToLit(str) {
  * @returns {string}
  */
 function emitClientModule(
-  stateEntries,
-  computedEntries,
-  bindEntries,
-  onEntries,
-  initBlocks,
-  srcImportMap,
-  counter,
-  _reactivitySrc,
+  stateEntries: [string, any][],
+  computedEntries: [string, string][],
+  bindEntries: [string, string][],
+  onEntries: [string, any][],
+  initBlocks: string[],
+  srcImportMap: Map<string, Set<string>>,
+  counter: { t: number; s: number; h: number; m: number; sw: number; l: number; needsLit: boolean },
+  _reactivitySrc: string,
 ) {
-  /** @type {string[]} */
-  const lines = [];
+  const lines: string[] = [];
   const needsLit = counter.needsLit;
   const needsComputed = computedEntries.length > 0;
 
@@ -676,9 +661,7 @@ function emitClientModule(
     lines.push("const on = {");
     for (const [key, def] of onEntries) {
       const argNames = def.args ?? ["state"];
-      const callArgs = argNames
-        .map((/** @type {string} */ a) => (a === "state" ? "state" : "e"))
-        .join(", ");
+      const callArgs = argNames.map((a: string) => (a === "state" ? "state" : "e")).join(", ");
       lines.push(
         "  " +
           key +
@@ -738,7 +721,7 @@ function emitClientModule(
  * @param {JxMutableNode} def
  * @returns {string}
  */
-function emitRequestInit(key, def) {
+function emitRequestInit(key: string, def: JxMutableNode) {
   const url = def.url;
   const method = def.method ?? "GET";
   const isTemplateUrl = isTemplateString(url);
@@ -747,8 +730,7 @@ function emitRequestInit(key, def) {
     return "// " + key + ": manual Request — fetch triggered by user action";
   }
 
-  /** @type {string[]} */
-  const lines = [];
+  const lines: string[] = [];
   lines.push("// " + key + ": auto-fetch from " + (isTemplateUrl ? "(dynamic URL)" : url));
   lines.push("effect(() => {");
 
@@ -759,8 +741,7 @@ function emitRequestInit(key, def) {
     lines.push("  const url = " + JSON.stringify(url) + ";");
   }
 
-  /** @type {string[]} */
-  const fetchOpts = [];
+  const fetchOpts: string[] = [];
   if (method !== "GET") fetchOpts.push("method: " + JSON.stringify(method));
   if (def.headers) fetchOpts.push("headers: " + JSON.stringify(def.headers));
   if (def.body) {
@@ -788,9 +769,8 @@ function emitRequestInit(key, def) {
  * @param {unknown} defaultVal
  * @returns {string}
  */
-function emitStorageInit(key, storeName, storageKey, defaultVal) {
-  /** @type {string[]} */
-  const lines = [];
+function emitStorageInit(key: string, storeName: string, storageKey: string, defaultVal: unknown) {
+  const lines: string[] = [];
   lines.push("// " + key + ": " + storeName + ' (key: "' + storageKey + '")');
   lines.push("try {");
   lines.push("  const _s = " + storeName + ".getItem(" + JSON.stringify(storageKey) + ");");
@@ -818,9 +798,8 @@ function emitStorageInit(key, storeName, storageKey, defaultVal) {
  * @param {unknown} defaultVal
  * @returns {string}
  */
-function emitCookieInit(key, cookieName, defaultVal) {
-  /** @type {string[]} */
-  const lines = [];
+function emitCookieInit(key: string, cookieName: string, defaultVal: unknown) {
+  const lines: string[] = [];
   lines.push("// " + key + ': Cookie (name: "' + cookieName + '")');
   lines.push("{");
   lines.push(
@@ -844,7 +823,7 @@ function emitCookieInit(key, cookieName, defaultVal) {
  * @param {string} ref
  * @returns {string}
  */
-function refToBindingKey(ref) {
+function refToBindingKey(ref: string) {
   if (ref.startsWith("#/state/")) {
     return ref.slice("#/state/".length).replace(/\//g, "_");
   }
@@ -856,7 +835,7 @@ function refToBindingKey(ref) {
  * @param {string} key
  * @param {string} ref
  */
-function addRefBinding(bindings, key, ref) {
+function addRefBinding(bindings: Map<string, string>, key: string, ref: string) {
   if (bindings.has(key)) return;
   if (ref.startsWith("#/state/")) {
     const path = ref.slice("#/state/".length);