@zubra/actions 0.0.0-stage → 5.3.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Mikey Nichols
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @zubra/actions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Serve Zubra components' `'use server'` functions over plain form posts. The same form works without JavaScript (a post and a redirect back) and with it (a `fetch`, no navigation, an `action` event on the form).
+
+```js
+import { createActions } from '@zubra/actions';
+const actions = await createActions({ components: 'components' });
+
+if (await actions.handle(req, res)) return;     // Node's http
+const response = await actions.fetch(request);  // fetch-style servers; null if not ours
+```
+
+Adapters: `@zubra/actions/hono`, `@zubra/actions/express`, `@zubra/actions/fastify`. Put `actions.script()` on pages with action forms.
+
+The contract, the security rules and the no-JavaScript path are in [docs/actions.md](https://github.com/journey-to-code-org/zubra/blob/main/docs/actions.md).

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@zubra/actions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.3.0",
+  "description": "Serve Zubra components' 'use server' functions over plain form posts, enhanced to fetch when JavaScript loads.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./client": {
+      "types": "./src/client.d.ts",
+      "default": "./src/client.js"
+    },
+    "./express": "./src/express.js",
+    "./fastify": "./src/fastify.js",
+    "./hono": "./src/hono.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "peerDependencies": {
+    "@zubra/compiler": "^5.3.0",
+    "@zubra/server": "^5.3.0"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "file:../compiler",
+    "@zubra/runtime": "file:../runtime",
+    "@zubra/server": "file:../server",
+    "express": "5.3.0",
+    "fastify": "5.12.8",
+    "hono": "4.13.17",
+    "playwright": "1.63.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/journey-to-code-org/zubra.git",
+    "directory": "actions"
+  }
+}

package/src/client.d.ts

@@ -0,0 +1,11 @@
+/** Enhance the action forms under `root`. The document is enhanced when the module loads. */
+export function enhance(root: Document | ShadowRoot | Element): void;
+
+declare global {
+  interface HTMLElementEventMap {
+    /** Before an action form's request; cancel it with `preventDefault()`. */
+    beforeaction: CustomEvent<{ formData: FormData }>;
+    /** After an action form's request. */
+    action: CustomEvent<{ value: unknown } | { error: string; status: number }>;
+  }
+}

package/src/client.js

@@ -0,0 +1,70 @@
+// @zubra/actions in the browser: a form that posts to a 'use server' function is sent with fetch
+// instead, so the page stays put. Without this script (or without JavaScript), the same form posts
+// normally and the server redirects back. Everything here is the platform's: a `submit` listener,
+// FormData, fetch, `aria-busy`, and two DOM events on the form.
+//
+//   beforeaction  cancelable; before the request (detail: { formData })
+//   action        after it (detail: { value } or { error, status })
+//
+//   <form action={save} onaction={(event) => (saved = event.detail.value)}>
+//
+// A form opts out with `data-zb-native`. Forms inside a shadow root: call `enhance(shadowRoot)`.
+const MOUNT = '/_zb/action/';
+
+function target(form, submitter) {
+  const action = submitter?.getAttribute('formaction') ?? form.getAttribute('action') ?? '';
+  const method = (submitter?.getAttribute('formmethod') ?? form.getAttribute('method') ?? 'get').toLowerCase();
+  return method === 'post' && action.startsWith(MOUNT) ? action : null;
+}
+
+async function submit(event) {
+  const form = event.target;
+  if (!(form instanceof HTMLFormElement) || event.defaultPrevented || form.hasAttribute('data-zb-native')) return;
+  const action = target(form, event.submitter);
+  if (!action) return;
+  event.preventDefault();
+  const formData = new FormData(form, event.submitter ?? undefined);
+  const before = new CustomEvent('beforeaction', { bubbles: true, cancelable: true, detail: { formData } });
+  if (!form.dispatchEvent(before)) return;
+  form.setAttribute('aria-busy', 'true');
+  let detail;
+  try {
+    const response = await fetch(action, { method: 'POST', body: formData, headers: { accept: 'application/json' } });
+    const next = response.headers.get('zb-location');
+    if (next) {
+      go(next);
+      return;
+    }
+    if (response.redirected) {
+      location.assign(response.url);
+      return;
+    }
+    const type = response.headers.get('content-type') ?? '';
+    const value = type.includes('application/json') ? await response.json() : null;
+    detail = response.ok ? { value } : { error: value?.error ?? response.statusText, status: response.status };
+  } catch (error) {
+    detail = { error: error.message, status: 0 };
+  } finally {
+    form.removeAttribute('aria-busy');
+  }
+  form.dispatchEvent(new CustomEvent('action', { bubbles: true, detail }));
+}
+
+/**
+ * Navigate after a redirect. Back to this same page with only a different #fragment (the usual
+ * "post, then show the page again") is a hash change to the browser, which doesn't reload: reload,
+ * so the page shows what the post changed.
+ */
+function go(next) {
+  const url = new URL(next, location.href);
+  const same = url.origin === location.origin && url.pathname === location.pathname && url.search === location.search;
+  location.assign(url);
+  if (same) location.reload();
+}
+
+/** Enhance the forms under `root` (the document already is; pass a shadow root for its forms). */
+export function enhance(root) {
+  root.addEventListener('submit', submit);
+}
+
+enhance(document);

package/src/express.js

@@ -0,0 +1,23 @@
+// Express middleware: answers the action endpoints and the client script, and sets the result of
+// a no-JavaScript post as `res.locals.zubraAction` (null otherwise). Mount it before any body
+// parser (express.urlencoded, multer): the action reads the body itself.
+//
+//   import { actions } from '@zubra/actions/express';
+//   app.use(await actions({ components: 'components' }));
+import { createActions } from './index.js';
+
+export async function actions(options) {
+  const instance = await createActions(options);
+  const middleware = (req, res, next) => {
+    instance
+      .handle(req, res)
+      .then((answered) => {
+        if (answered) return;
+        res.locals.zubraAction = instance.result(req, (name, value) => res.append(name, value));
+        next();
+      })
+      .catch(next);
+  };
+  middleware.actions = instance;
+  return middleware;
+}

package/src/fastify.js

@@ -0,0 +1,16 @@
+// Fastify plugin: answers the action endpoints (before Fastify parses the body) and the client
+// script, and sets the result of a no-JavaScript post as `request.zubraAction` (null otherwise).
+//
+//   import { actions } from '@zubra/actions/fastify';
+//   await app.register(actions, { components: 'components' });
+import { createActions } from './index.js';
+
+export async function actions(app, options) {
+  const instance = await createActions(options);
+  app.decorateRequest('zubraAction', null);
+  app.addHook('onRequest', async (request, reply) => {
+    if (await instance.handle(request.raw, reply.raw)) return reply.hijack();
+    request.zubraAction = instance.result(request.raw, (name, value) => reply.header(name, value));
+  });
+}
+actions[Symbol.for('skip-override')] = true;

package/src/hono.js

@@ -0,0 +1,18 @@
+// Hono middleware: answers the action endpoints and the client script, and sets the result of a
+// no-JavaScript post as `c.get('zubraAction')` (null otherwise) for the page to render.
+//
+//   import { actions } from '@zubra/actions/hono';
+//   app.use(await actions({ components: 'components' }));
+import { createActions } from './index.js';
+
+export async function actions(options) {
+  const instance = await createActions(options);
+  const middleware = async (c, next) => {
+    const response = await instance.fetch(c.req.raw, { c });
+    if (response) return response;
+    c.set('zubraAction', instance.result(c.req.raw, (name, value) => c.header(name, value, { append: true })));
+    await next();
+  };
+  middleware.actions = instance;
+  return middleware;
+}

package/src/index.d.ts

@@ -0,0 +1,54 @@
+export const MOUNT: '/_zb/action/';
+export const SCRIPT_PATH: '/_zb/actions.js';
+export const COOKIE: '__zb_result';
+
+export interface ActionsOptions {
+  /** The folder of `.zb` files. Default: `components`. */
+  components?: string;
+  /** Where the components' server halves are written. Default: `node_modules/.cache/zubra-actions`. */
+  cacheDir?: string;
+  /** Other origins allowed to post, beyond the request's own. */
+  origins?: string[];
+  /** Called when a server function throws. The client gets a generic error either way. */
+  onError?: (error: unknown, request: Request) => void;
+  /**
+   * What else a server function gets beside `request`, per request: the signed-in user, a
+   * database handle. `req` is Node's request (Node, Express, Fastify); `c` is Hono's context.
+   */
+  context?: (from: { request: Request; req?: import('node:http').IncomingMessage; c?: unknown }) => object | Promise<object>;
+}
+
+export interface ActionResult<T = unknown> {
+  /** The action's URL, `/_zb/action/<tag>/<name>`. */
+  action: string;
+  value: T;
+}
+
+export interface Actions {
+  /** A Response for an action or the client script; null for any other request. */
+  fetch(request: Request, extra?: { req?: import('node:http').IncomingMessage; c?: unknown }): Promise<Response | null>;
+  /** Node's http: answers ours and resolves true, else false without reading the body. */
+  handle(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse): Promise<boolean>;
+  /** After a no-JavaScript post, its result, once; `setHeader` gets the header that clears it. */
+  result<T = unknown>(
+    request: Request | import('node:http').IncomingMessage,
+    setHeader?: (name: string, value: string) => void,
+  ): ActionResult<T> | null;
+  /** Every action's URL. */
+  routes(): string[];
+  /** The `<script type="module">` that enhances action forms. */
+  script(): string;
+  /** A `Set-Cookie` value that clears the result cookie. */
+  clearCookie: string;
+}
+
+/** What a server function receives besides its FormData. */
+export interface ActionContext {
+  request: Request;
+  /** And whatever `context()` returned. */
+  [key: string]: unknown;
+}
+
+export function createActions(options?: ActionsOptions): Promise<Actions>;
+export function toRequest(req: import('node:http').IncomingMessage): Request;
+export function send(response: Response, res: import('node:http').ServerResponse): Promise<void>;

package/src/index.js

@@ -0,0 +1,212 @@
+// @zubra/actions: serve a component's 'use server' functions, over plain form posts.
+//
+//   import { createActions } from '@zubra/actions';
+//   const actions = await createActions({ components: 'components' });
+//
+//   actions.fetch(request)     // fetch-style servers (Hono, Bun, Deno): a Response, or null if not ours
+//   actions.handle(req, res)   // Node's http: true if it answered
+//   actions.result(request)    // after a no-JavaScript post: { action, value } once, else null
+//   actions.script()           // <script> for the page: enhances those forms into fetch requests
+//
+// The contract (plan/actions-design.md):
+// - A form posts to /_zb/action/<tag>/<name> with its own encoding; the function gets the FormData.
+// - `Accept: application/json` (the enhanced path) gets the return value as JSON.
+// - Anything else (the browser's own post) gets 303 See Other back to the page it came from, with
+//   the return value in a one-use cookie, so the page can render it (`result()`).
+// - A cross-site post is refused (Origin / Sec-Fetch-Site), so forms on other sites can't call it.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findCompiler } from '@zubra/server';
+
+findCompiler();
+const compiler = await import('@zubra/compiler');
+
+export const MOUNT = '/_zb/action/';
+export const SCRIPT_PATH = '/_zb/actions.js';
+export const COOKIE = '__zb_result';
+const SOURCE = /\.zb(?:\.[jt]sx)?$/;
+const CLIENT = readFileSync(new URL('./client.js', import.meta.url), 'utf8');
+
+/**
+ * `context({ request, req, c })`: what else a server function gets beside `request`, per request
+ * (the signed-in user, a database handle). `req` is Node's request (Node, Express, Fastify), `c`
+ * Hono's context. It may be async; what it returns is spread into the function's second argument.
+ *
+ * `components`: the folder of `.zb` files. `cacheDir`: where the server halves are written
+ * (bare imports resolve from there, so keep it inside the project). `origins`: other origins
+ * allowed to post (behind a proxy that rewrites Origin, say). `onError(error, request)`: called
+ * when a function throws; the client gets a generic error, never the message or stack.
+ */
+export async function createActions({
+  components = 'components',
+  cacheDir = join(process.cwd(), 'node_modules', '.cache', 'zubra-actions'),
+  origins = [],
+  onError = (error) => console.error(error),
+  context = () => ({}),
+} = {}) {
+  const root = resolve(components);
+  if (!existsSync(root)) throw new Error(`@zubra/actions: no components folder at ${root}`);
+  mkdirSync(cacheDir, { recursive: true });
+
+  // URL → function, from every component's server half.
+  const routes = new Map();
+  for (const path of sources(root)) {
+    const response = compiler.request({ emit: 'server', path, files: compiler.sources(path) });
+    if (!response.ok) throw new Error(response.error);
+    if (!/^export (async )?function /m.test(response.output)) continue;
+    const module = join(cacheDir, `${relative(root, path).split(sep).join('__').replace(SOURCE, '')}.server.mjs`);
+    writeFileSync(module, absoluteImports(response.output, dirname(path)));
+    const { actions } = await import(`${pathToFileURL(module).href}?t=${Date.now()}`);
+    for (const [url, fn] of Object.entries(actions)) {
+      if (routes.has(url)) throw new Error(`@zubra/actions: two components define ${url}`);
+      routes.set(url, fn);
+    }
+  }
+
+  const allowed = (request) => {
+    const site = request.headers.get('sec-fetch-site');
+    if (site) return site === 'same-origin' || site === 'none';
+    const origin = request.headers.get('origin');
+    if (!origin) return true; // not a browser (curl, a test): CSRF needs a browser
+    return origin === new URL(request.url).origin || origins.includes(origin);
+  };
+
+  /** The page to go back to: the referring page on this origin, else the site root. */
+  const back = (request) => {
+    const referer = request.headers.get('referer');
+    try {
+      const url = new URL(referer, request.url);
+      if (url.origin === new URL(request.url).origin) return url.pathname + url.search;
+    } catch {}
+    return '/';
+  };
+
+  async function fetch(request, extra = {}) {
+    const url = new URL(request.url);
+    if (request.method === 'GET' && url.pathname === SCRIPT_PATH) {
+      return new Response(CLIENT, { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+    }
+    if (!url.pathname.startsWith(MOUNT)) return null;
+    if (request.method !== 'POST') return text(405, 'Method Not Allowed', { allow: 'POST' });
+    if (!allowed(request)) return text(403, 'Cross-site form posts are refused');
+    const fn = routes.get(url.pathname);
+    if (!fn) return text(404, 'Not Found');
+    const wantsJson = (request.headers.get('accept') ?? '').includes('application/json');
+    let value;
+    let failed = false;
+    try {
+      const more = await context({ request, ...extra });
+      value = await fn(await request.formData(), { ...more, request });
+    } catch (error) {
+      onError(error, request);
+      failed = true;
+      value = { error: 'Something went wrong' };
+    }
+    if (value instanceof Response) {
+      // A redirect after success: the enhanced path is told where to go rather than following it,
+      // so the page navigates once, with the location's #fragment kept (fetch drops it).
+      const location = value.headers.get('location');
+      if (wantsJson && location && value.status >= 300 && value.status < 400) {
+        const headers = new Headers({ 'zb-location': location });
+        for (const cookie of value.headers.getSetCookie()) headers.append('set-cookie', cookie);
+        return new Response(null, { status: 204, headers });
+      }
+      return value;
+    }
+    if (wantsJson) {
+      return new Response(JSON.stringify(value ?? null), {
+        status: failed ? 500 : 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+    const headers = new Headers({ location: back(request) });
+    const cookie = encodeURIComponent(JSON.stringify({ action: url.pathname, value: value ?? null }));
+    // A cookie holds about 4 KB; a bigger result reaches only the enhanced path.
+    if (cookie.length < 3800) {
+      headers.append('set-cookie', `${COOKIE}=${cookie}; Path=/; HttpOnly; SameSite=Lax; Max-Age=60`);
+    }
+    return new Response(null, { status: 303, headers });
+  }
+
+  /**
+   * After a no-JavaScript post: `{ action, value }` once, else null. `request` is a fetch Request
+   * or a Node request; `setHeader(name, value)` is given the header that clears the cookie.
+   */
+  function result(request, setHeader) {
+    const header = (typeof request.headers.get === 'function' ? request.headers.get('cookie') : request.headers.cookie) ?? '';
+    const match = header.split(/;\s*/).find((part) => part.startsWith(`${COOKIE}=`));
+    if (!match) return null;
+    setHeader?.('set-cookie', CLEAR);
+    try {
+      return JSON.parse(decodeURIComponent(match.slice(COOKIE.length + 1)));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Node's http: answers ours and returns true, or returns false without reading the body. */
+  async function handle(req, res) {
+    if (!req.url.startsWith(MOUNT) && !req.url.startsWith(SCRIPT_PATH)) return false;
+    const response = await fetch(toRequest(req), { req });
+    if (!response) return false;
+    await send(response, res);
+    return true;
+  }
+
+  return {
+    fetch,
+    handle,
+    result,
+    routes: () => [...routes.keys()],
+    script: () => `<script type="module" src="${SCRIPT_PATH}"></script>`,
+    clearCookie: CLEAR,
+  };
+}
+
+const CLEAR = `${COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`;
+
+function text(status, body, headers = {}) {
+  return new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8', ...headers } });
+}
+
+function sources(dir, out = []) {
+  for (const entry of readdirSync(dir).sort()) {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      if (entry !== 'node_modules' && !entry.startsWith('.')) sources(path, out);
+    } else if (SOURCE.test(entry)) out.push(path);
+  }
+  return out;
+}
+
+/** The server half lives in the cache folder, so its relative imports point back at the source. */
+function absoluteImports(code, from) {
+  return code.replace(/(\bfrom\s*|\bimport\s*)(['"])(\.{1,2}\/[^'"]+)\2/g, (_, keyword, quote, specifier) =>
+    `${keyword}${quote}${pathToFileURL(resolve(from, specifier)).href}${quote}`);
+}
+
+/** A Node request as a fetch Request (the body streams; nothing is read until it's ours). */
+export function toRequest(req) {
+  const host = req.headers.host ?? 'localhost';
+  const protocol = req.socket?.encrypted ? 'https' : 'http';
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) value.forEach((each) => headers.append(name, each));
+    else if (value !== undefined) headers.set(name, value);
+  }
+  const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : req;
+  return new Request(`${protocol}://${host}${req.url}`, { method: req.method, headers, body, duplex: 'half' });
+}
+
+/** Write a fetch Response to a Node response. */
+export async function send(response, res) {
+  res.statusCode = response.status;
+  for (const [name, value] of response.headers) {
+    if (name === 'set-cookie') continue;
+    res.setHeader(name, value);
+  }
+  const cookies = response.headers.getSetCookie?.() ?? [];
+  if (cookies.length) res.setHeader('set-cookie', cookies);
+  res.end(response.body ? Buffer.from(await response.arrayBuffer()) : undefined);
+}