@jxsuite/compiler 6.1.0 → 8.0.0

package/src/targets/compile-client.ts

@@ -27,6 +27,7 @@ import {
   createCompileContext,
   emitFormulaFn,
   emitRequestFetch,
+  emitServerCall,
   escapeHtml,
   isMutating,
   isRefObject,
@@ -36,6 +37,7 @@ import {
   PREFORMATTED_TAGS,
   pureSchemeOf,
   resolveStaticValue,
+  serverCallHelperSource,
   srcImportBinding,
   templateValueSource,
 } from "../shared.ts";
@@ -51,6 +53,7 @@ import {
   isNonNullObject,
   isNumber,
   isPrototypeDef,
+  isServerFnDef,
   isString,
   isTagExpression,
   paramNames,
@@ -62,6 +65,7 @@ import {
   objectKey,
   refAccessor,
   refBindingKey,
+  refReader,
   refSegments,
 } from "@jxsuite/runtime/pointer";
 import type {
@@ -97,6 +101,7 @@ interface HandlerDef {
  *   litHtmlSrc?: string;
  *   modulePath?: string;
  *   projectStyle?: JxStyle | null;
+ *   serverBaseUrl?: string;
  * }} opts
  * @returns {{ html: string; files: { path: string; content: string }[] }}
  */
@@ -110,6 +115,12 @@ export function compileClient(
     projectStyle?: JxStyle | null;
     prePaintScheme?: boolean;
     rewriteSrc?: (specifier: string) => string;
+    /**
+     * The route prefix a `timing: "server"` entry posts to, deployment base included
+     * (`serverRoutePrefix`). The call is written into the module, and no later pass rewrites a
+     * module, so the base has to be known when it is compiled.
+     */
+    serverBaseUrl?: string;
   },
 ) {
   const {
@@ -117,6 +128,7 @@ export function compileClient(
     reactivitySrc = DEFAULT_REACTIVITY_SRC,
     litHtmlSrc = DEFAULT_LIT_HTML_SRC,
     modulePath = "app.js",
+    serverBaseUrl = "/_jx/server",
   } = opts;
 
   const context = createCompileContext(raw, null, raw.state ?? {}, raw.$media ?? {});
@@ -133,6 +145,7 @@ export function compileClient(
   const bindEntries: [string, string][] = []; // [key, bodyExpr]   → bind = {...}
   const onEntries: [string, HandlerDef][] = []; // [key, { args, body }] → on = {...}
   const initBlocks: string[] = []; // Lines emitted after state for prototype init
+  const serverCalls: string[] = []; // One block per `timing: "server"` entry, after the computed block
 
   // Map $src path → Set of function names to import
   const srcImportMap = new Map<string, Set<string>>();
@@ -241,6 +254,13 @@ export function compileClient(
       }
     }
 
+    // `timing: "server"`: null until the site worker's route answers (compiler.md §6.1)
+    if (isServerFnDef(def)) {
+      stateEntries.push([key, null]);
+      serverCalls.push(emitServerCall(key, def, { serverBaseUrl }));
+      continue;
+    }
+
     /*
      * Plain object → reactive state.
      * SAFETY: `raw.state` is parsed JSON, so this entry is structurally a JsonObject; the checks
@@ -272,6 +292,7 @@ export function compileClient(
     bindEntries,
     onEntries,
     initBlocks,
+    serverCalls,
     srcImportMap,
     counter,
     reactivitySrc,
@@ -540,7 +561,7 @@ function buildClientNode(
     const swKey = `_sw${counter.sw}`;
     counter.sw += 1;
     const discriminant = isRefObject(source.$switch)
-      ? `state.${refToBindingKey(source.$switch.$ref)}`
+      ? stateRead(source.$switch.$ref)
       : `\`${String(source.$switch)}\``;
     const cases = source.cases ?? {};
     // Parsed JSON, so a case slot can hold `null` or a bare value the declared type leaves out.
@@ -575,13 +596,9 @@ function buildClientNode(
     const arrayDef = source.children;
 
     // Resolve items source expression
-    let itemsExpr;
-    if (isRefObject(arrayDef.items)) {
-      const path = refToBindingKey(arrayDef.items.$ref);
-      itemsExpr = `state.${path}`;
-    } else {
-      itemsExpr = JSON.stringify(arrayDef.items);
-    }
+    const itemsExpr = isRefObject(arrayDef.items)
+      ? stateRead(arrayDef.items.$ref)
+      : JSON.stringify(arrayDef.items);
 
     // Compile the map template to a lit-html template string
     const litTemplate = emitLitMapTemplate(arrayDef.map);
@@ -845,9 +862,7 @@ function emitChildLit(c: JxMutableNode | JsonPrimitive, preformatted = false): s
  */
 function emitArrayHole(arrayDef: RepeaterSlot): string {
   const { items } = arrayDef;
-  const itemsExpr = isRefObject(items)
-    ? `state.${refToBindingKey(items.$ref)}`
-    : JSON.stringify(items ?? []);
+  const itemsExpr = isRefObject(items) ? stateRead(items.$ref) : JSON.stringify(items ?? []);
   const tpl = emitLitMapTemplate(arrayDef.map);
   return `\${(${itemsExpr} ?? []).map((item, index) => html\`${tpl}\`)}`;
 }
@@ -870,6 +885,7 @@ function mapRefsToLit(str: string) {
  * @param {[string, string][]} bindEntries
  * @param {[string, any][]} onEntries
  * @param {string[]} initBlocks
+ * @param {string[]} serverCalls
  * @param {Map<string, Set<string>>} srcImportMap
  * @param {{
  *   t: number;
@@ -889,6 +905,7 @@ function emitClientModule(
   bindEntries: [string, string][],
   onEntries: [string, HandlerDef][],
   initBlocks: string[],
+  serverCalls: string[],
   srcImportMap: Map<string, Set<string>>,
   counter: {
     t: number;
@@ -930,7 +947,11 @@ function emitClientModule(
   // State — reactive state
   /* The boolean-attribute rule, inlined because this module loads with `@vue/reactivity` and
      nothing else — see `attrHelperSource`. The hydration script below is its only caller. */
-  lines.push("", attrHelperSource(), "", "const state = reactive({");
+  lines.push("", attrHelperSource());
+  if (serverCalls.length > 0) {
+    lines.push("", serverCallHelperSource());
+  }
+  lines.push("", "const state = reactive({");
   for (const [key, val] of stateEntries) {
     /*
      * State keys come from the document, so `{"user.name": 1}` is legal input. Pasting one raw as
@@ -956,6 +977,15 @@ function emitClientModule(
     lines.push("");
   }
 
+  // Server-function calls, after the computed block so a reference to a computed reads its value on
+  // The first run
+  if (serverCalls.length > 0) {
+    for (const block of serverCalls) {
+      lines.push(block);
+    }
+    lines.push("");
+  }
+
   // Bind — DOM getters
   if (bindEntries.length > 0) {
     lines.push("const bind = {");
@@ -1126,6 +1156,18 @@ function mapRefToClientExpr(ref: string) {
   return refAccessor("state", ref);
 }
 
+/**
+ * The read of the state a `$ref` names, for a binding whose value arrives later: a `$switch`
+ * discriminant and a repeater's `items`. A server entry or a `Request` is `null` until it answers,
+ * so `#/state/contact/status` must read `state.contact?.status` rather than throw on the first run,
+ * which inside the hydration loop would end it before any later binding or handler was attached.
+ * The path is the ref's own, never its flattened binding key: `contact/status` is two members, not
+ * `contact_status`.
+ */
+function stateRead(ref: string) {
+  return refReader("state", ref.startsWith("#/state/") ? ref.slice("#/state/".length) : ref);
+}
+
 /**
  * The `bind`/`on` map key for a ref. It is emitted both as an object-literal key and as a
  * `data-bind` attribute value, so it has to survive being a JavaScript identifier and an HTML

package/src/targets/compile-element.ts

@@ -22,9 +22,11 @@ import {
   compileStatements,
   emitFormulaFn,
   emitRequestFetch,
+  emitServerCall,
   escapeHtml,
   isMutating,
   isSchemaOnly,
+  serverCallHelperSource,
   srcExportName,
   srcImportBinding,
   tagNameToClassName,
@@ -42,6 +44,7 @@ import {
   isNumber,
   isPrototypeDef,
   isRef,
+  isServerFnDef,
   isString,
   isTagExpression,
   paramNames,
@@ -62,6 +65,7 @@ import type {
   JxMutableNode,
   JxPrototypeDef,
   JxRef,
+  JxServerFnDef,
   JxStateDefinition,
   JxStyle,
   ProjectConfig,
@@ -89,6 +93,12 @@ export interface CompileElementOptions {
   basePath?: string | null;
   /** Project `defaults`, read for `defaults.shadow` (spec.md §16.6). */
   defaults?: ProjectConfig["defaults"];
+  /**
+   * The route prefix a `timing: "server"` entry posts to, deployment base included
+   * (`serverRoutePrefix`). The call is written into the module and no later pass rewrites a module,
+   * so the base has to be known when it is compiled. Handed to every `$elements` dependency too.
+   */
+  serverBaseUrl?: string;
 }
 
 /**
@@ -185,6 +195,7 @@ export async function compileElement(
       elementImports,
       rewriteSrc ? (spec: string) => rewriteSrc(spec, currentDir) : undefined,
       resolveShadowMode(doc, opts.defaults),
+      opts.serverBaseUrl,
     );
     const outputPath = filePath ? filePath.replace(/\.json$/, ".js") : `${tagName}.js`;
     files.push({ content: jsContent, path: outputPath, tagName });
@@ -284,6 +295,10 @@ function extractInitialValue(def: JxStateDefinition) {
   if (def.$prototype === "Request") {
     return "null";
   }
+  // A `timing: "server"` entry holds nothing until the site worker's route answers (§6.1)
+  if (isServerFnDef(def)) {
+    return "null";
+  }
   // Plain object → treat as initial state value
   return JSON.stringify(def);
 }
@@ -371,6 +386,7 @@ export function emitElementModule(
   elementImports: string[],
   rewriteSrc?: (specifier: string) => string,
   shadow: ShadowMode | null = null,
+  serverBaseUrl = "/_jx/server",
 ) {
   const lines: string[] = ["// Generated by @jxsuite/compiler — do not edit manually"];
 
@@ -434,6 +450,12 @@ export function emitElementModule(
     isPrototypeDef(def) && def.$prototype === "Request" ? [[key, def]] : [],
   );
 
+  // `timing: "server"` entries each call the site worker's route from connectedCallback, after the
+  // Request fetches, and share one module-level helper that reads the response.
+  const serverEntries = Object.entries(defs).flatMap(([key, def]): [string, JxServerFnDef][] =>
+    isServerFnDef(def) ? [[key, def]] : [],
+  );
+
   lines.push(
     `import { reactive, computed, effect, stop } from '@vue/reactivity';`,
     /* `nothing` is what REMOVES an attribute in a lit template, and it is the only way to express a
@@ -442,6 +464,9 @@ export function emitElementModule(
     `import { render, html, nothing } from 'lit-html';`,
     attrHelperSource(),
   );
+  if (serverEntries.length > 0) {
+    lines.push(serverCallHelperSource());
+  }
   /* Light-DOM slot distribution, by the rule the interpreter applies (spec.md §8.5): only a module
      whose template draws a slot carries it, and a shadow component never does — its light children
      ARE the slotted content, and a real `<slot>` distributes them. */
@@ -780,6 +805,18 @@ export function emitElementModule(
       }),
     );
   }
+  // Last, so a `$ref` argument reads the props the parent delivered above, and an effect it starts
+  // Joins the registry `disconnectedCallback` stops.
+  for (const [key, def] of serverEntries) {
+    lines.push(
+      emitServerCall(key, def, {
+        collect: "this.#effects",
+        indent: "    ",
+        serverBaseUrl,
+        statePrefix: "this.state",
+      }),
+    );
+  }
   if (isNonNullObject(doc.style)) {
     const dynamicStyles: [string, string][] = [];
     for (const [prop, value] of Object.entries(doc.style)) {

package/src/targets/compile-server.ts

@@ -1,65 +1,30 @@
 /**
- * Compile-server.js — Hono server handler compilation
+ * Compile-server.js — the site worker
  *
- * Compiles `timing: "server"` entries from a Jx document into a deployable Hono server handler
- * file.
+ * Emits the one Hono worker a site deploys beside its static output: every `timing: "server"` entry
+ * the build collected as a `POST /_jx/server/<export>` route, the extension server mounts, and the
+ * adapter's fallthrough to static assets (compiler.md §6.3).
  */
 
 import { withBase } from "@jxsuite/schema/asset-paths";
-import { dereference } from "@apidevtools/json-schema-ref-parser";
-import { collectServerEntries } from "../shared.ts";
 import { localeNegotiationMiddleware } from "../site/locale-negotiation.ts";
 import type { ResolvedI18n } from "../site/i18n.ts";
-import type { JxDocumentValue, JxElement } from "@jxsuite/schema/types";
+import type { JxDocumentValue } from "@jxsuite/schema/types";
 
 /**
- * Compile a Jx document to a Hono server handler file. The handler exposes each `timing: "server"`
- * entry as a POST endpoint under `/_jx/server/$export`. Returns null if no server entries are
- * found.
+ * The route prefix the site worker registers its server functions under, and a compiled page or
+ * component posts to: the deployment base (site-architecture.md §14.7) in front of `baseUrl`.
  *
- * @example
- *   const server = await compileServer("./dashboard.json");
- *   if (server) fs.writeFileSync("dist/server.js", server);
+ * One function builds it for both sides. The worker IS the origin, so a route left at the bare path
+ * never matches on a site served from a subfolder, and no pass rewrites a module after it is
+ * compiled, so the caller has to be given the same prefix when the module is.
  *
- * @param {string | JxElement} sourcePath - Path to .json file, URL, or raw document
- * @param {object} [opts]
- * @param {string} [opts.baseUrl] - Base path for server endpoints. Default is `'/_jx/server'`
- * @returns {Promise<string | null>} Hono server handler source string, or null
+ * @param {string} base - The deployment base, `""` for a site at an origin root
+ * @param {string} [baseUrl] - Route prefix before the base is applied, `"/_jx/server"` by default
+ * @returns {string}
  */
-export async function compileServer(
-  sourcePath: string | JxElement,
-  opts: {
-    baseUrl?: string;
-  } = {},
-) {
-  const { baseUrl = "/_jx/server" } = opts;
-  /* SAFETY: the parameter is a Jx element document or the path of one, and `dereference` only
-     replaces each `$ref` node with the value it points to, so the result is that same document
-     with its references inlined. A file read from disk is not re-validated here. */
-  const doc = (await dereference(sourcePath)) as JxElement;
-  const entries = collectServerEntries(doc);
-  if (entries.length === 0) {
-    return null;
-  }
-
-  const imports = entries
-    .map(({ exportName, src }) => `import { ${exportName} } from '${src}'`)
-    .join("\n");
-
-  const routes = entries.map(({ exportName }) => buildRoute(exportName, baseUrl)).join("\n");
-
-  return `// Generated by @jxsuite/compiler — do not edit manually
-// Deploy as a Cloudflare Worker, Node server, or Bun process.
-// Requires: npm install hono
-
-import { Hono } from 'hono'
-${imports}
-
-const app = new Hono()
-${routes}
-
-export default app
-`;
+export function serverRoutePrefix(base: string, baseUrl = "/_jx/server"): string {
+  return withBase(base, baseUrl);
 }
 
 /**
@@ -131,7 +96,7 @@ export function compileSiteServer(
    * everything behind it routes on the bare path. Each is internally consistent: production serves
    * exactly one URL space, while `jx dev` deliberately answers both.
    */
-  const baseUrl = withBase(base, opts.baseUrl ?? "/_jx/server");
+  const baseUrl = serverRoutePrefix(base, opts.baseUrl);
   if (entries.length === 0 && mounts.length === 0 && !adapter) {
     return null;
   }
@@ -217,7 +182,7 @@ function buildRoute(exportName: string, baseUrl: string) {
 app.post('${baseUrl}/${exportName}', async (c) => {
   const args = await c.req.json().catch(() => ({}))
   try {
-    return c.json(await ${exportName}(args, c.env))
+    return c.json((await ${exportName}(args, c.env)) ?? null)
   } catch (e) {
     return c.json({ ok: false, error: e?.message ?? 'Server error' }, 500)
   }