@sigmx/hono 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Callum Bonnyman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @sigmx/hono
+
+Hono middleware for [sigmx](https://github.com/wrux/sigmx). One `app.use(sigmx())` and every handler gets `c.var.sigmx`: the signals the request carries, and responses the client knows how to apply.
+
+```bash
+npm install sigmx @sigmx/hono
+```
+
+```ts
+import { Hono } from 'hono';
+import { patchElements, patchSignals, sigmx } from '@sigmx/hono';
+import { serveClient } from '@sigmx/hono/node';
+
+const app = new Hono();
+app.use(sigmx());
+app.get('/sigmx.js', serveClient()); // the script-tag build from node_modules; skip it if you bundle
+
+app.get('/api/towns', async (c) => {
+  const { q = '' } = await c.var.sigmx.signals();
+  return c.var.sigmx.events(patchElements(renderTowns(q)), patchSignals({ stale: false }));
+});
+
+app.get('/api/progress', (c) =>
+  c.var.sigmx.stream(async (s) => {
+    for (let step = 1; step <= 10 && !s.closed; step++) {
+      await s.sleep(150);
+      await s.patchSignals({ progress: step * 10 });
+    }
+  }),
+);
+```
+
+## `c.var.sigmx`
+
+| member | |
+|---|---|
+| `isRequest` | true when the sigmx client made the request, so a route can return a partial instead of a whole page |
+| `signals()` | the signals: `sigmx` query parameter on GET and DELETE, JSON body otherwise, form fields for `contentType: 'form'` requests |
+| `signals(schema)` | the same, validated by any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType…) and typed from it |
+| `html(body, { selector, mode, useViewTransition, status })` | HTML the client morphs by id, or into `selector` with `mode`. Plain `c.html()` already works when you morph by id |
+| `json(signals, { onlyIfMissing, status })` | JSON the client merges into its signals |
+| `events(...events)` | several patches in one response, sent at once |
+| `stream(fn)` | a long-lived stream; `fn` gets a `SigmxStream` with `patchElements`, `patchSignals`, `removeElements`, `removeSignals`, `executeScript`, `sleep`, `closed` and `onAbort`. Built on Hono's `streamSSE`, so it stops when the client disconnects |
+
+Event builders (`patchElements`, `patchSignals`, `removeElements`, `removeSignals`, `executeScript`) and `formatEvent` are exported for use with `events()` or your own transport.
+
+## Validation failures
+
+`signals(schema)` throws a `SignalsError` (a Hono `HTTPException`) with the issues. Hono answers it with a JSON body and a 422 (400 when the payload could not be parsed) and logs nothing. To answer differently:
+
+```ts
+app.use(sigmx({ onError: (error, c) => c.text(error.message, 422) }));
+```
+
+If you define your own `app.onError`, return `error.getResponse()` for `HTTPException`s as usual.
+
+## Serving the client
+
+`serveClient()` from `@sigmx/hono/node` reads `sigmx.standalone.js` from the installed `sigmx` package and serves it with an ETag and `cache-control`. It needs a filesystem, so it is a separate entry for Node, Bun and Deno; on Workers, bundle the client with your app instead. Pass `{ file, maxAge }` to serve another file from sigmx's `dist` or change the cache lifetime.
+
+## JSX
+
+Hono's JSX passes namespaced attributes through, and every helper accepts a JSX node wherever it takes markup:
+
+```tsx
+const Counter = () => <button data-on:click="$count++">Clicked <b data-text="$count">0</b> times</button>;
+
+app.get('/', (c) => c.html(<Counter />));
+app.get('/api/rows', async (c) => c.var.sigmx.events(patchElements(<Rows q={String((await c.var.sigmx.signals()).q)} />)));
+```
+
+JSX attribute names may contain colons but not dots, so a modifier with an argument such as `data-on:input__debounce.200ms` is spread from an object: `<input {...{ 'data-on:input__debounce.200ms': "@get('/api/towns')" }} />`.
+
+## Licence
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { type SSEStreamingApi } from 'hono/streaming';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+import { type EventOptions, type ExecuteScriptOptions, type Markup, type PatchElementsOptions, type PatchSignalsOptions, type SchemaIssue, type ServerEvent, type StandardSchema } from 'sigmx/server';
+export { EVENT_PATCH_ELEMENTS, EVENT_PATCH_SIGNALS, type EventOptions, type ExecuteScriptOptions, executeScript, formatEvent, type Markup, type PatchElementsOptions, type PatchMode, type PatchSignalsOptions, patchElements, patchSignals, removeElements, removeSignals, type SchemaIssue, type SchemaResult, type ServerEvent, SIGNALS_KEY, SSE_HEADERS, type StandardSchema, } from 'sigmx/server';
+/**
+ * Thrown by `signals()` when the payload cannot be parsed (400) or fails validation (422). It is an
+ * `HTTPException`, so Hono's default error handling answers with `getResponse()` and logs nothing.
+ */
+export declare class SignalsError extends HTTPException {
+    readonly issues: ReadonlyArray<SchemaIssue>;
+    constructor(message: string, issues?: ReadonlyArray<SchemaIssue>, status?: 400 | 422);
+    getResponse(): Response;
+    response(): Response;
+}
+export interface SigmxOptions {
+    /**
+     * Turn a `SignalsError` thrown by `signals(schema)` into a response.
+     * Default: the error's own JSON body with a 400 or 422 status.
+     */
+    onError?: (error: SignalsError, c: Context) => Response | Promise<Response>;
+}
+export interface SigmxHtmlOptions extends PatchElementsOptions {
+    status?: ContentfulStatusCode;
+}
+export interface SigmxJsonOptions extends PatchSignalsOptions {
+    status?: ContentfulStatusCode;
+}
+/** A live event stream. Every write is awaited so backpressure and disconnects are respected. */
+export declare class SigmxStream {
+    private readonly api;
+    constructor(api: SSEStreamingApi);
+    get closed(): boolean;
+    send(event: ServerEvent): Promise<void>;
+    patchElements(html: Markup, o?: PatchElementsOptions): Promise<void>;
+    removeElements(selector: string, o?: EventOptions): Promise<void>;
+    patchSignals(signals: Record<string, unknown> | string, o?: PatchSignalsOptions): Promise<void>;
+    removeSignals(paths: string[], o?: EventOptions): Promise<void>;
+    executeScript(script: string, o?: ExecuteScriptOptions): Promise<void>;
+    /** Wait, resolving early if the client disconnects. */
+    sleep(ms: number): Promise<unknown>;
+    onAbort(fn: () => void | Promise<void>): void;
+    close(): Promise<void>;
+}
+export interface SigmxContext {
+    /** True when the request was made by the sigmx client. Use it to send a partial instead of a whole page. */
+    readonly isRequest: boolean;
+    /**
+     * The signals the request carries: the `sigmx` query parameter on GET and DELETE, a JSON body otherwise,
+     * or form fields for `contentType: 'form'` requests. With a Standard Schema validator (Zod, Valibot, ArkType…)
+     * the result is typed and invalid payloads become a 422 response.
+     */
+    signals(): Promise<Record<string, any>>;
+    signals<T>(schema: StandardSchema<T>): Promise<T>;
+    /** HTML the client morphs by id, or into `selector` with `mode`. Accepts strings, `html` templates and Hono JSX. */
+    html(body: string | Promise<string>, o?: SigmxHtmlOptions): Response | Promise<Response>;
+    json(signals: Record<string, unknown>, o?: SigmxJsonOptions): Response;
+    events(...events: ServerEvent[]): Response;
+    /** A long-lived stream; the response closes when `fn` resolves or the client disconnects. */
+    stream(fn: (stream: SigmxStream) => Promise<void> | void): Response;
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        sigmx: SigmxContext;
+    }
+}
+/**
+ * Middleware that attaches `c.var.sigmx` to every request. A `SignalsError` escaping a handler is turned
+ * into its JSON response (or whatever `onError` returns); every other error is left to `app.onError`.
+ */
+export declare const sigmx: (o?: SigmxOptions) => MiddlewareHandler;

package/dist/index.js

@@ -0,0 +1,126 @@
+import { createMiddleware } from 'hono/factory';
+import { HTTPException } from 'hono/http-exception';
+import { streamSSE } from 'hono/streaming';
+import { executeScript, formatEvent, patchElements, patchSignals, removeElements, removeSignals, SIGNALS_KEY, SSE_HEADERS, validateSignals, } from 'sigmx/server';
+export { EVENT_PATCH_ELEMENTS, EVENT_PATCH_SIGNALS, executeScript, formatEvent, patchElements, patchSignals, removeElements, removeSignals, SIGNALS_KEY, SSE_HEADERS, } from 'sigmx/server';
+/**
+ * Thrown by `signals()` when the payload cannot be parsed (400) or fails validation (422). It is an
+ * `HTTPException`, so Hono's default error handling answers with `getResponse()` and logs nothing.
+ */
+export class SignalsError extends HTTPException {
+    issues;
+    constructor(message, issues = [], status = 422) {
+        super(status, { message });
+        this.name = 'SignalsError';
+        this.issues = issues;
+    }
+    getResponse() {
+        return Response.json({ error: this.message, issues: this.issues }, { status: this.status });
+    }
+    response() {
+        return this.getResponse();
+    }
+}
+/** A live event stream. Every write is awaited so backpressure and disconnects are respected. */
+export class SigmxStream {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    get closed() {
+        return this.api.closed || this.api.aborted;
+    }
+    send(event) {
+        if (this.closed)
+            return Promise.resolve();
+        return this.api.writeSSE({ event: event.event, data: event.lines.join('\n'), id: event.id, retry: event.retry });
+    }
+    patchElements(html, o) {
+        return this.send(patchElements(html, o));
+    }
+    removeElements(selector, o) {
+        return this.send(removeElements(selector, o));
+    }
+    patchSignals(signals, o) {
+        return this.send(patchSignals(signals, o));
+    }
+    removeSignals(paths, o) {
+        return this.send(removeSignals(paths, o));
+    }
+    executeScript(script, o) {
+        return this.send(executeScript(script, o));
+    }
+    /** Wait, resolving early if the client disconnects. */
+    sleep(ms) {
+        return this.api.sleep(ms);
+    }
+    onAbort(fn) {
+        this.api.onAbort(fn);
+    }
+    close() {
+        return this.api.close();
+    }
+}
+const readSignals = async (c, schema) => {
+    let raw;
+    const method = c.req.method.toUpperCase();
+    const type = c.req.header('content-type') ?? '';
+    try {
+        if (method === 'GET' || method === 'DELETE') {
+            const q = c.req.query(SIGNALS_KEY);
+            raw = q ? JSON.parse(q) : {};
+        }
+        else if (type.includes('application/json')) {
+            const text = await c.req.text();
+            raw = text ? JSON.parse(text) : {};
+        }
+        else if (type.includes('form')) {
+            raw = await c.req.parseBody();
+        }
+        else {
+            raw = {};
+        }
+    }
+    catch (e) {
+        throw new SignalsError(`could not parse signals: ${e.message}`, [], 400);
+    }
+    try {
+        return await validateSignals(raw, schema);
+    }
+    catch (e) {
+        const err = e;
+        throw new SignalsError(err.message, err.issues ?? [], 422);
+    }
+};
+const contextFor = (c) => ({
+    isRequest: c.req.header('sigmx-request') === 'true',
+    signals: (schema) => readSignals(c, schema),
+    html: (body, o = {}) => {
+        if (o.selector)
+            c.header('sigmx-selector', o.selector);
+        if (o.mode)
+            c.header('sigmx-mode', o.mode);
+        if (o.useViewTransition)
+            c.header('sigmx-use-view-transition', 'true');
+        return c.html(body, o.status ?? 200);
+    },
+    json: (signals, o = {}) => {
+        if (o.onlyIfMissing)
+            c.header('sigmx-only-if-missing', 'true');
+        return c.json(signals, o.status ?? 200);
+    },
+    events: (...events) => c.body(events.map(formatEvent).join(''), 200, SSE_HEADERS),
+    stream: (fn) => streamSSE(c, async (api) => {
+        await fn(new SigmxStream(api));
+    }),
+});
+/**
+ * Middleware that attaches `c.var.sigmx` to every request. A `SignalsError` escaping a handler is turned
+ * into its JSON response (or whatever `onError` returns); every other error is left to `app.onError`.
+ */
+export const sigmx = (o = {}) => createMiddleware(async (c, next) => {
+    c.set('sigmx', contextFor(c));
+    await next();
+    if (c.error instanceof SignalsError)
+        c.res = o.onError ? await o.onError(c.error, c) : c.error.response();
+});

package/dist/node.d.ts

@@ -0,0 +1,13 @@
+import type { Handler } from 'hono';
+export interface ServeClientOptions {
+    /** File inside sigmx's `dist` to serve (default `sigmx.standalone.js`, every plugin, minified). */
+    file?: string;
+    /** `max-age` in seconds for the `cache-control` header (default one hour); an ETag handles the rest. */
+    maxAge?: number;
+}
+/**
+ * A route handler that serves the client from `node_modules/sigmx` with an ETag, so no bundler is needed:
+ *
+ *     app.get('/sigmx.js', serveClient())
+ */
+export declare const serveClient: (o?: ServeClientOptions) => Handler;

package/dist/node.js

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+/**
+ * A route handler that serves the client from `node_modules/sigmx` with an ETag, so no bundler is needed:
+ *
+ *     app.get('/sigmx.js', serveClient())
+ */
+export const serveClient = (o = {}) => {
+    let cached;
+    const load = () => {
+        cached ??= (async () => {
+            const require = createRequire(import.meta.url);
+            const dist = join(dirname(require.resolve('sigmx/package.json')), 'dist');
+            const body = await readFile(join(dist, o.file ?? 'sigmx.standalone.js'), 'utf8');
+            const etag = `"${createHash('sha1').update(body).digest('base64url').slice(0, 16)}"`;
+            return { body, etag };
+        })();
+        return cached;
+    };
+    return async (c) => {
+        const { body, etag } = await load();
+        if (c.req.header('if-none-match') === etag)
+            return c.body(null, 304);
+        return c.body(body, 200, {
+            'content-type': 'text/javascript; charset=utf-8',
+            etag,
+            'cache-control': `public, max-age=${o.maxAge ?? 3600}`,
+        });
+    };
+};

package/dist/wire.d.ts

@@ -0,0 +1,67 @@
+/** Query-string key that carries signals on GET/DELETE requests. */
+export declare const SIGNALS_KEY = "sigmx";
+export declare const EVENT_PATCH_ELEMENTS = "sigmx-patch-elements";
+export declare const EVENT_PATCH_SIGNALS = "sigmx-patch-signals";
+export declare const SSE_HEADERS: {
+    readonly 'content-type': "text/event-stream";
+    readonly 'cache-control': "no-cache";
+    readonly connection: "keep-alive";
+};
+/** HTML as a string, or anything that renders to one such as a Hono JSX node or an `html` template. */
+export type Markup = string | {
+    toString(): string;
+};
+export type PatchMode = 'outer' | 'inner' | 'replace' | 'prepend' | 'append' | 'before' | 'after' | 'remove';
+export interface ServerEvent {
+    event: string;
+    /** Data lines, each `key value`. */
+    lines: string[];
+    id?: string;
+    retry?: number;
+}
+export interface EventOptions {
+    id?: string;
+    retry?: number;
+}
+export interface PatchElementsOptions extends EventOptions {
+    selector?: string;
+    mode?: PatchMode;
+    useViewTransition?: boolean;
+}
+export interface PatchSignalsOptions extends EventOptions {
+    onlyIfMissing?: boolean;
+}
+export interface ExecuteScriptOptions extends EventOptions {
+    /** Remove the script element after it runs (default true). */
+    autoRemove?: boolean;
+    attributes?: Record<string, string>;
+}
+/** Patch HTML into the page. Without a selector, top-level elements are morphed by id. */
+export declare const patchElements: (html: Markup, o?: PatchElementsOptions) => ServerEvent;
+export declare const removeElements: (selector: string, o?: EventOptions) => ServerEvent;
+/** Merge signals (JSON merge-patch: null removes). Accepts an object or pre-serialised JSON. */
+export declare const patchSignals: (signals: Record<string, unknown> | string, o?: PatchSignalsOptions) => ServerEvent;
+/** Remove signals by dotted path. */
+export declare const removeSignals: (paths: string[], o?: EventOptions) => ServerEvent;
+/** Run JavaScript in the page by appending a script element to the body. */
+export declare const executeScript: (script: string, o?: ExecuteScriptOptions) => ServerEvent;
+/** Serialise one event in `text/event-stream` format. */
+export declare const formatEvent: (e: ServerEvent) => string;
+/** Minimal Standard Schema (standardschema.dev) so any compliant validator works without a dependency. */
+export interface StandardSchema<Output = unknown> {
+    readonly '~standard': {
+        readonly validate: (value: unknown) => SchemaResult<Output> | Promise<SchemaResult<Output>>;
+    };
+}
+export type SchemaIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }>;
+};
+export type SchemaResult<T> = {
+    readonly value: T;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<SchemaIssue>;
+};

package/dist/wire.js

@@ -0,0 +1,73 @@
+// The sigmx wire format: event builders and the signal-reading contract. Framework-neutral.
+/** Query-string key that carries signals on GET/DELETE requests. */
+export const SIGNALS_KEY = 'sigmx';
+export const EVENT_PATCH_ELEMENTS = 'sigmx-patch-elements';
+export const EVENT_PATCH_SIGNALS = 'sigmx-patch-signals';
+export const SSE_HEADERS = {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+};
+/** Patch HTML into the page. Without a selector, top-level elements are morphed by id. */
+export const patchElements = (html, o = {}) => {
+    const lines = [];
+    if (o.selector)
+        lines.push(`selector ${o.selector}`);
+    if (o.mode && o.mode !== 'outer')
+        lines.push(`mode ${o.mode}`);
+    if (o.useViewTransition)
+        lines.push('useViewTransition true');
+    for (const l of String(html).trim().split('\n'))
+        lines.push(`elements ${l}`);
+    return { event: EVENT_PATCH_ELEMENTS, lines, id: o.id, retry: o.retry };
+};
+export const removeElements = (selector, o = {}) => ({
+    event: EVENT_PATCH_ELEMENTS,
+    lines: [`selector ${selector}`, 'mode remove'],
+    ...o,
+});
+/** Merge signals (JSON merge-patch: null removes). Accepts an object or pre-serialised JSON. */
+export const patchSignals = (signals, o = {}) => ({
+    event: EVENT_PATCH_SIGNALS,
+    lines: [
+        ...(o.onlyIfMissing ? ['onlyIfMissing true'] : []),
+        `signals ${typeof signals === 'string' ? signals : JSON.stringify(signals)}`,
+    ],
+    id: o.id,
+    retry: o.retry,
+});
+/** Remove signals by dotted path. */
+export const removeSignals = (paths, o = {}) => {
+    const patch = {};
+    for (const p of paths) {
+        const keys = p.split('.');
+        const last = keys.pop();
+        let cur = patch;
+        for (const k of keys)
+            cur = cur[k] ??= {};
+        cur[last] = null;
+    }
+    return patchSignals(patch, o);
+};
+/** Run JavaScript in the page by appending a script element to the body. */
+export const executeScript = (script, o = {}) => {
+    const attrs = { ...((o.autoRemove ?? true) ? { 'data-init': 'el.remove()' } : {}), ...o.attributes };
+    const attrText = Object.entries(attrs)
+        .map(([k, v]) => ` ${k}="${v.replace(/"/g, '"')}"`)
+        .join('');
+    return patchElements(`<script${attrText}>${script}</script>`, {
+        selector: 'body',
+        mode: 'append',
+        id: o.id,
+        retry: o.retry,
+    });
+};
+/** Serialise one event in `text/event-stream` format. */
+export const formatEvent = (e) => `${[
+    e.id !== undefined && `id: ${e.id}`,
+    e.retry !== undefined && `retry: ${e.retry}`,
+    `event: ${e.event}`,
+    ...e.lines.map((l) => `data: ${l}`),
+]
+    .filter(Boolean)
+    .join('\n')}\n\n`;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@sigmx/hono",
+  "version": "0.1.0",
+  "description": "Hono middleware for sigmx: read signals from the request, answer with HTML, JSON or a stream of patches, serve the client.",
+  "keywords": [
+    "hono",
+    "hono-middleware",
+    "sigmx",
+    "hypermedia",
+    "sse"
+  ],
+  "author": "Callum Bonnyman",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wrux/sigmx.git",
+    "directory": "sdks/hono"
+  },
+  "homepage": "https://github.com/wrux/sigmx#readme",
+  "bugs": {
+    "url": "https://github.com/wrux/sigmx/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "prepublishOnly": "npm test",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "hono": "^4.13.7",
+    "sigmx": "file:../..",
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "hono": ">=4.6.0",
+    "sigmx": "^0.1.0"
+  }
+}