@nifrajs/web 2.2.0 → 2.3.0

package/dist/fn-state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `@nifrajs/web/fn-state` - the pending/error state around a server-function call.
+ *
+ * Calling a server function needs no binding: the client stub is `(input) => Promise<Output>`, and a
+ * click handler can await it. What a component usually wants on top is whether a call is in flight,
+ * what came back, and what went wrong - which is state, and state is the part every framework spells
+ * differently.
+ *
+ * So the state machine lives here, framework-agnostic, and each adapter contributes only its
+ * subscription primitive. Five copies of "is it pending" would drift, and the drift would be five
+ * subtly different answers to the same question.
+ *
+ * ## Two behaviours worth stating
+ *
+ * **The last call wins.** Concurrent calls are not queued or cancelled; a response that is no longer
+ * the newest is discarded rather than written. Without that, a slow first call landing after a fast
+ * second one would overwrite fresh data with stale - the classic out-of-order bug, and one that only
+ * appears under load, which is to say in production.
+ *
+ * **`call` still rejects.** The error is recorded for rendering AND the promise rejects, so `await`
+ * behaves the way `await` should and a caller who wants to branch can. A caller who only renders from
+ * state should attach a `.catch(() => {})`, the same as `useFetcher`'s `submit`.
+ */
+/** What a component renders from. */
+export interface ServerFnState<Output> {
+    /** A call is in flight. */
+    readonly pending: boolean;
+    /** The most recent successful result, kept across a later pending call so the UI need not flicker. */
+    readonly data: Output | undefined;
+    /** The most recent failure, cleared when a call succeeds. */
+    readonly error: Error | undefined;
+}
+/** A subscribable call site. One per component instance, created by the framework binding. */
+export interface ServerFnStore<Input, Output> {
+    /** Register a listener; returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The current state. The SAME object is returned until something changes, because
+     * `useSyncExternalStore` and its equivalents compare by reference - a fresh object each call is an
+     * infinite render loop.
+     */
+    snapshot(): ServerFnState<Output>;
+    /** Invoke the server function. Records state, and rejects on failure. */
+    call(input: Input): Promise<Output>;
+    /** Back to idle, discarding data and error. */
+    reset(): void;
+}
+/** The idle state, shared so a server render and the first client render agree by reference. */
+export declare function idleServerFnState<Output>(): ServerFnState<Output>;
+/**
+ * Wrap a server function (or any async function) in a subscribable pending/error state.
+ *
+ * Framework-free by design: the adapters call this and subscribe with their own primitive.
+ */
+export declare function createServerFnStore<Input, Output>(fn: (input: Input) => Promise<Output> | Output): ServerFnStore<Input, Output>;
+//# sourceMappingURL=fn-state.d.ts.map

package/dist/fn-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn-state.d.ts","sourceRoot":"","sources":["../src/fn-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qCAAqC;AACrC,MAAM,WAAW,aAAa,CAAC,MAAM;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sGAAsG;IACtG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAA;CAClC;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,MAAM;IAC1C,oDAAoD;IACpD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C;;;;OAIG;IACH,QAAQ,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IACjC,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnC,+CAA+C;IAC/C,KAAK,IAAI,IAAI,CAAA;CACd;AAID,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,KAAK,aAAa,CAAC,MAAM,CAAC,CAEjE;AAKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAC/C,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,GAC7C,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAuC9B"}

package/dist/fn-state.js

@@ -0,0 +1,77 @@
+/**
+ * `@nifrajs/web/fn-state` - the pending/error state around a server-function call.
+ *
+ * Calling a server function needs no binding: the client stub is `(input) => Promise<Output>`, and a
+ * click handler can await it. What a component usually wants on top is whether a call is in flight,
+ * what came back, and what went wrong - which is state, and state is the part every framework spells
+ * differently.
+ *
+ * So the state machine lives here, framework-agnostic, and each adapter contributes only its
+ * subscription primitive. Five copies of "is it pending" would drift, and the drift would be five
+ * subtly different answers to the same question.
+ *
+ * ## Two behaviours worth stating
+ *
+ * **The last call wins.** Concurrent calls are not queued or cancelled; a response that is no longer
+ * the newest is discarded rather than written. Without that, a slow first call landing after a fast
+ * second one would overwrite fresh data with stale - the classic out-of-order bug, and one that only
+ * appears under load, which is to say in production.
+ *
+ * **`call` still rejects.** The error is recorded for rendering AND the promise rejects, so `await`
+ * behaves the way `await` should and a caller who wants to branch can. A caller who only renders from
+ * state should attach a `.catch(() => {})`, the same as `useFetcher`'s `submit`.
+ */
+const IDLE = { pending: false, data: undefined, error: undefined };
+/** The idle state, shared so a server render and the first client render agree by reference. */
+export function idleServerFnState() {
+    return IDLE;
+}
+const asError = (cause) => cause instanceof Error ? cause : new Error(String(cause), { cause });
+/**
+ * Wrap a server function (or any async function) in a subscribable pending/error state.
+ *
+ * Framework-free by design: the adapters call this and subscribe with their own primitive.
+ */
+export function createServerFnStore(fn) {
+    const listeners = new Set();
+    let state = idleServerFnState();
+    /** Identifies the newest call, so an older one landing later cannot write over it. */
+    let generation = 0;
+    const set = (next) => {
+        state = next;
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        snapshot: () => state,
+        async call(input) {
+            const mine = ++generation;
+            // `data` is deliberately kept while pending: dropping it makes a list blank on every refetch.
+            set({ pending: true, data: state.data, error: undefined });
+            try {
+                const data = await fn(input);
+                if (mine === generation)
+                    set({ pending: false, data, error: undefined });
+                return data;
+            }
+            catch (cause) {
+                const error = asError(cause);
+                if (mine === generation)
+                    set({ pending: false, data: state.data, error });
+                throw error;
+            }
+        },
+        reset() {
+            // Bump the generation so a call already in flight cannot resurrect the state it was reset from.
+            generation += 1;
+            set(idleServerFnState());
+        },
+    };
+}
+//# sourceMappingURL=fn-state.js.map

package/dist/fn-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn-state.js","sourceRoot":"","sources":["../src/fn-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA4BH,MAAM,IAAI,GAAyB,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;AAExF,gGAAgG;AAChG,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAA6B,CAAA;AACtC,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,KAAc,EAAS,EAAE,CACxC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;AAEtE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,EAA8C;IAE9C,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IACvC,IAAI,KAAK,GAA0B,iBAAiB,EAAU,CAAA;IAC9D,sFAAsF;IACtF,IAAI,UAAU,GAAG,CAAC,CAAA;IAElB,MAAM,GAAG,GAAG,CAAC,IAA2B,EAAQ,EAAE;QAChD,KAAK,GAAG,IAAI,CAAA;QACZ,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,EAAE,CAAA;IAC9C,CAAC,CAAA;IAED,OAAO;QACL,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC5B,CAAC,CAAA;QACH,CAAC;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;QACrB,KAAK,CAAC,IAAI,CAAC,KAAK;YACd,MAAM,IAAI,GAAG,EAAE,UAAU,CAAA;YACzB,8FAA8F;YAC9F,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;YAC1D,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,CAAA;gBAC5B,IAAI,IAAI,KAAK,UAAU;oBAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAA;gBACxE,OAAO,IAAI,CAAA;YACb,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC5B,IAAI,IAAI,KAAK,UAAU;oBAAE,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;gBACzE,MAAM,KAAK,CAAA;YACb,CAAC;QACH,CAAC;QACD,KAAK;YACH,gGAAgG;YAChG,UAAU,IAAI,CAAC,CAAA;YACf,GAAG,CAAC,iBAAiB,EAAU,CAAC,CAAA;QAClC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/fn.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `@nifrajs/web/fn` - server functions: write a function, call it from a component.
+ *
+ * ## Every server function is a public endpoint
+ *
+ * This is the first thing to internalise, because the API deliberately reads like a local call. A
+ * mounted function is an HTTP route anyone can POST to, with arguments entirely under the caller's
+ * control. Its id has to be in the client bundle for the browser to call it, so there is no obscurity
+ * to lean on. Treat one exactly as you would a hand-written `app.post`.
+ *
+ * What follows from that, and what this module does about it:
+ *
+ *   - **Input is validated, always.** `input` is not optional decoration; without a schema a function
+ *     takes no arguments at all. Unvalidated arguments on a public endpoint are mass assignment.
+ *   - **`application/json` only.** A cross-origin HTML form can only send urlencoded, multipart or
+ *     text/plain, so requiring JSON forces a CORS preflight the browser blocks. Both alternatives were
+ *     measured rather than assumed: a body schema alone still accepts a cross-origin urlencoded form
+ *     (200, attacker-controlled fields), and `c.boundedJson` alone accepts the `text/plain` trick where
+ *     a form's `name=value` is crafted to parse as JSON. Neither is sufficient by itself.
+ *   - **Same-origin only.** A present `Origin` must match the request's own host. Defence in depth
+ *     behind the JSON requirement, and it costs one comparison. Server functions exist for your own
+ *     frontend; a different origin calling your backend is the typed-client story, not this one.
+ *   - **No closures.** A function is a module-level export taking explicit arguments. Next serialises
+ *     closed-over variables to the browser and back, which it now has to encrypt; refusing the feature
+ *     removes the whole class rather than defending it.
+ *
+ * ## The client half
+ *
+ * A `*.fn.ts` module is never bundled for the browser. The client build replaces it with one stub per
+ * export, each POSTing to the route below, so the bodies and everything they import stay on the server.
+ *
+ * One pipeline cannot do this: `nifra dev --bun`. Bun's dev-server bundler accepts no plugins - a
+ * runtime `Bun.plugin` onLoad does not reach it, which was measured rather than assumed - so a `*.fn`
+ * module there would ship WHOLE, secrets included. That command refuses to start on an app containing
+ * one, the same way it already refuses CSS Modules. `nifra build` and `nifra dev` (Vite) are unaffected.
+ *
+ * ## Why this is not a new lane
+ *
+ * A mounted function registers through the ordinary public `register()`, so it is a route like any
+ * other and inherits the body cap, schema validation, capability declarations, the effect ledger, and
+ * `nifra assure`. Nothing here touches the kernel or the request path, so an app that mounts none of
+ * them pays exactly nothing - which is the whole reason to build it this way rather than as a
+ * bespoke dispatcher.
+ */
+import { type Context, type RouteSchema, type StandardSchemaV1 } from "@nifrajs/core/server";
+/** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
+export declare const SERVER_FN_PREFIX = "/_nifra/fn";
+type MaybePromise<T> = T | Promise<T>;
+/** What a server function declares about itself. */
+export interface ServerFnConfig<Input> {
+    /**
+     * Validates the single argument. Omit it and the function takes no argument - never "any argument":
+     * the caller controls this value completely, so an unvalidated one is an open door.
+     */
+    readonly input?: StandardSchemaV1<unknown, Input>;
+    /** Effect tokens, forwarded to the route so `nifra assure` and the effect ledger see them. */
+    readonly capabilities?: readonly string[];
+}
+/**
+ * A declared server function. Callable directly on the server (the same value your own server-side
+ * code can await); on the client, phase 2's build transform replaces this module with typed stubs
+ * that POST to the mounted route.
+ *
+ * This is the SERVER declaration type, so context is required. Client builds replace the module with
+ * a one-argument {@link ClientServerFn}; UI bindings accept either shape and adapt at that boundary.
+ * Keeping the types separate prevents a direct server call from type-checking while handing the
+ * declaration `undefined` for a context its implementation requires.
+ */
+export interface ServerFn<Input, Output> {
+    (input: Input, context: Context): MaybePromise<Output>;
+    readonly [SERVER_FN]: ServerFnConfig<Input>;
+}
+/** The one-argument callable emitted into a client bundle for a {@link ServerFn}. */
+export type ClientServerFn<Input, Output> = (input: Input) => MaybePromise<Output>;
+/** A UI binding boundary: source declarations and generated client stubs are both accepted. */
+export type ServerFnReference<Input, Output> = ServerFn<Input, Output> | ClientServerFn<Input, Output>;
+/** Brand identifying a value produced by {@link serverFn}, so mounting cannot pick up stray exports. */
+export declare const SERVER_FN: unique symbol;
+/**
+ * Declare a server function.
+ *
+ *     export const addTodo = serverFn(
+ *       { input: t.object({ text: t.string({ minLength: 1 }) }), capabilities: ["db.write"] },
+ *       async ({ text }, c) => db.todos.insert({ text }),
+ *     )
+ *
+ * The second argument receives the validated input and the ordinary nifra `Context` - `c.env`,
+ * `c.clientIp`, `c.budget`, cookies, and the capability guard are all present, because this is a route.
+ */
+export declare function serverFn<Input = void, Output = unknown>(config: ServerFnConfig<Input>, fn: (input: Input, context: Context) => MaybePromise<Output>): ServerFn<Input, Output>;
+/** The minimum a server needs to expose for functions to be mounted onto it. */
+export interface ServerFnHost {
+    register(method: "POST", path: string, schema: RouteSchema | undefined, handler: (context: never) => unknown): void;
+}
+/** Every server function a module exports, keyed by export name. */
+export type ServerFnModule = Readonly<Record<string, unknown>>;
+/**
+ * Mount a module's server functions under `namespace`, returning a plugin for `app.use(...)`.
+ *
+ *     import * as todos from "./actions/todos.fn"
+ *     app.use(serverFunctions("todos", todos))   // -> POST /_nifra/fn/todos/addTodo
+ *
+ * The namespace is explicit rather than derived from the file path: a path-derived one would put the
+ * build machine's layout in a public URL, and this keeps the route readable in logs and greppable in
+ * the codebase. Phase 2's transform supplies it automatically from the file's location in the project.
+ *
+ * Exports that are not server functions are ignored, so `export type` and helpers can live alongside.
+ */
+export declare function serverFunctions<S extends ServerFnHost>(namespace: string, module: ServerFnModule): (app: S) => S;
+export {};
+//# sourceMappingURL=fn.d.ts.map

package/dist/fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn.d.ts","sourceRoot":"","sources":["../src/fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAA;AAE7B,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAE5C,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC,oDAAoD;AACpD,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACjD,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ,CAAC,KAAK,EAAE,MAAM;IACrC,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;IACtD,QAAQ,CAAC,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAA;CAC5C;AAED,qFAAqF;AACrF,MAAM,MAAM,cAAc,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,CAAC,MAAM,CAAC,CAAA;AAElF,+FAA+F;AAC/F,MAAM,MAAM,iBAAiB,CAAC,KAAK,EAAE,MAAM,IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GACvB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEjC,wGAAwG;AACxG,eAAO,MAAM,SAAS,EAAE,OAAO,MAA6C,CAAA;AAE5E;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,KAAK,GAAG,IAAI,EAAE,MAAM,GAAG,OAAO,EACrD,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,EAC7B,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,KAAK,YAAY,CAAC,MAAM,CAAC,GAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAEzB;AAiBD,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,OAAO,GACnC,IAAI,CAAA;CACR;AAED,oEAAoE;AACpE,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE9D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EACpD,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,GACrB,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CA4Cf"}

package/dist/fn.js

@@ -0,0 +1,125 @@
+/**
+ * `@nifrajs/web/fn` - server functions: write a function, call it from a component.
+ *
+ * ## Every server function is a public endpoint
+ *
+ * This is the first thing to internalise, because the API deliberately reads like a local call. A
+ * mounted function is an HTTP route anyone can POST to, with arguments entirely under the caller's
+ * control. Its id has to be in the client bundle for the browser to call it, so there is no obscurity
+ * to lean on. Treat one exactly as you would a hand-written `app.post`.
+ *
+ * What follows from that, and what this module does about it:
+ *
+ *   - **Input is validated, always.** `input` is not optional decoration; without a schema a function
+ *     takes no arguments at all. Unvalidated arguments on a public endpoint are mass assignment.
+ *   - **`application/json` only.** A cross-origin HTML form can only send urlencoded, multipart or
+ *     text/plain, so requiring JSON forces a CORS preflight the browser blocks. Both alternatives were
+ *     measured rather than assumed: a body schema alone still accepts a cross-origin urlencoded form
+ *     (200, attacker-controlled fields), and `c.boundedJson` alone accepts the `text/plain` trick where
+ *     a form's `name=value` is crafted to parse as JSON. Neither is sufficient by itself.
+ *   - **Same-origin only.** A present `Origin` must match the request's own host. Defence in depth
+ *     behind the JSON requirement, and it costs one comparison. Server functions exist for your own
+ *     frontend; a different origin calling your backend is the typed-client story, not this one.
+ *   - **No closures.** A function is a module-level export taking explicit arguments. Next serialises
+ *     closed-over variables to the browser and back, which it now has to encrypt; refusing the feature
+ *     removes the whole class rather than defending it.
+ *
+ * ## The client half
+ *
+ * A `*.fn.ts` module is never bundled for the browser. The client build replaces it with one stub per
+ * export, each POSTing to the route below, so the bodies and everything they import stay on the server.
+ *
+ * One pipeline cannot do this: `nifra dev --bun`. Bun's dev-server bundler accepts no plugins - a
+ * runtime `Bun.plugin` onLoad does not reach it, which was measured rather than assumed - so a `*.fn`
+ * module there would ship WHOLE, secrets included. That command refuses to start on an app containing
+ * one, the same way it already refuses CSS Modules. `nifra build` and `nifra dev` (Vite) are unaffected.
+ *
+ * ## Why this is not a new lane
+ *
+ * A mounted function registers through the ordinary public `register()`, so it is a route like any
+ * other and inherits the body cap, schema validation, capability declarations, the effect ledger, and
+ * `nifra assure`. Nothing here touches the kernel or the request path, so an app that mounts none of
+ * them pays exactly nothing - which is the whole reason to build it this way rather than as a
+ * bespoke dispatcher.
+ */
+import { isSameOriginRequest, } from "@nifrajs/core/server";
+/** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
+export const SERVER_FN_PREFIX = "/_nifra/fn";
+/** Brand identifying a value produced by {@link serverFn}, so mounting cannot pick up stray exports. */
+export const SERVER_FN = Symbol.for("@nifrajs/web/server-fn");
+/**
+ * Declare a server function.
+ *
+ *     export const addTodo = serverFn(
+ *       { input: t.object({ text: t.string({ minLength: 1 }) }), capabilities: ["db.write"] },
+ *       async ({ text }, c) => db.todos.insert({ text }),
+ *     )
+ *
+ * The second argument receives the validated input and the ordinary nifra `Context` - `c.env`,
+ * `c.clientIp`, `c.budget`, cookies, and the capability guard are all present, because this is a route.
+ */
+export function serverFn(config, fn) {
+    return Object.assign(fn, { [SERVER_FN]: config });
+}
+const isServerFn = (value) => typeof value === "function" && SERVER_FN in value;
+/** A namespace segment: lowercase, dot/dash separated. Constrained so a mount cannot invent a path. */
+const NAMESPACE = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+/** An export name that is safe in a URL path without escaping. */
+const EXPORT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * Same-origin, from `@nifrajs/core` so this seam and the WebSocket handshake cannot answer differently
+ * for one request. Host must match; the Origin's scheme may be equal or stronger, never weaker - which
+ * is what keeps a TLS-terminating proxy working without reading a forwarded header.
+ */
+const sameOrigin = isSameOriginRequest;
+/**
+ * Mount a module's server functions under `namespace`, returning a plugin for `app.use(...)`.
+ *
+ *     import * as todos from "./actions/todos.fn"
+ *     app.use(serverFunctions("todos", todos))   // -> POST /_nifra/fn/todos/addTodo
+ *
+ * The namespace is explicit rather than derived from the file path: a path-derived one would put the
+ * build machine's layout in a public URL, and this keeps the route readable in logs and greppable in
+ * the codebase. Phase 2's transform supplies it automatically from the file's location in the project.
+ *
+ * Exports that are not server functions are ignored, so `export type` and helpers can live alongside.
+ */
+export function serverFunctions(namespace, module) {
+    if (!NAMESPACE.test(namespace)) {
+        throw new Error(`[nifra/fn] invalid server-function namespace ${JSON.stringify(namespace)} - use lowercase dot/dash segments (it becomes a URL path).`);
+    }
+    const mounted = Object.entries(module).filter((entry) => isServerFn(entry[1]));
+    const apply = (app) => {
+        for (const [name, fn] of mounted) {
+            if (!EXPORT_NAME.test(name)) {
+                throw new Error(`[nifra/fn] server function ${JSON.stringify(name)} in namespace ${JSON.stringify(namespace)} is not a valid identifier.`);
+            }
+            const config = fn[SERVER_FN];
+            const schema = {
+                ...(config.input !== undefined ? { body: config.input } : {}),
+                ...(config.capabilities !== undefined ? { capabilities: config.capabilities } : {}),
+            };
+            app.register("POST", `${SERVER_FN_PREFIX}/${namespace}/${name}`, schema, ((c) => {
+                // Ordered cheapest-first, and BEFORE the declared function runs. The body has already been
+                // parsed by the schema layer, but parsing is not a side effect - nothing the caller asked for
+                // has happened yet, so rejecting here is a complete refusal.
+                const request = c.req;
+                const contentType = request.headers.get("content-type") ?? "";
+                if (!contentType.includes("application/json")) {
+                    // A form cannot send this content type cross-origin without a preflight. Rejecting anything
+                    // else is what makes form-driven CSRF against a server function impossible rather than
+                    // merely unlikely.
+                    return c.json({ ok: false, error: "unsupported_media_type" }, 415);
+                }
+                const origin = request.headers.get("origin");
+                if (origin !== null && !sameOrigin(origin, request)) {
+                    return c.json({ ok: false, error: "forbidden_origin" }, 403);
+                }
+                return fn(config.input === undefined ? undefined : c.body, c);
+            }));
+        }
+        return app;
+    };
+    return Object.assign(apply, { pluginName: `nifra:server-fn:${namespace}` });
+}
+//# sourceMappingURL=fn.js.map

package/dist/fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fn.js","sourceRoot":"","sources":["../src/fn.ts"],"names":[],"mappings":"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"}

package/dist/fonts-google.d.ts

@@ -1,12 +1,12 @@
 /**
- * Build-time Google Fonts automation — the `next/font/google` equivalent. At **build time** (never on
+ * Build-time Google Fonts automation - the `next/font/google` equivalent. At **build time** (never on
  * the request path) it: builds the Google Fonts CSS2 URL, downloads the stylesheet, parses the
  * `@font-face` rules, downloads each `.woff2`, content-hashes it, writes it next to your assets, and
  * hands back a **self-hosted** `@font-face` stylesheet + the matching `<link rel="preload">`s. The
- * result is identical to dropping the files in yourself and calling {@link fontFace} — no runtime CDN
+ * result is identical to dropping the files in yourself and calling {@link fontFace} - no runtime CDN
  * hotlink, no layout shift, hashed filenames for immutable caching.
  *
- *   // fonts.build.ts — run once at build time (e.g. a prebuild step)
+ *   // fonts.build.ts - run once at build time (e.g. a prebuild step)
  *   import { loadGoogleFont } from "@nifrajs/web/fonts"
  *   const inter = await loadGoogleFont(
  *     { family: "Inter", weights: [400, 700], subsets: ["latin"] },
@@ -16,7 +16,7 @@
  *   // inter.preloads → spread into a root layout's `meta.link`
  *
  * Security: this fetches remote content and writes it to disk, so every input is validated and the
- * font-file host is **allowlisted to `fonts.gstatic.com` over https** — a tampered/MITM'd stylesheet
+ * font-file host is **allowlisted to `fonts.gstatic.com` over https** - a tampered/MITM'd stylesheet
  * cannot make the build fetch an arbitrary URL (SSRF) or write an attacker-chosen blob. Downloads are
  * size-capped. Filenames are derived only from validated tokens + a content hash (no path traversal).
  */
@@ -26,7 +26,7 @@ import type { LinkDescriptor } from "./manifest.js";
 export interface GoogleFontOptions {
     /** Family name exactly as Google lists it, e.g. `"Inter"`, `"Open Sans"`, `"Roboto Mono"`. */
     readonly family: string;
-    /** Weights to request — numbers (`400`), numeric strings, a variable range (`"100 900"`), or the
+    /** Weights to request - numbers (`400`), numeric strings, a variable range (`"100 900"`), or the
      * keywords `"normal"`/`"bold"`. Defaults to `[400]`. */
     readonly weights?: readonly (number | string)[];
     /** Styles to request. Defaults to `["normal"]`. */
@@ -38,7 +38,7 @@ export interface GoogleFontOptions {
     /** `font-display` strategy for the generated faces. Defaults to `"swap"`. */
     readonly display?: FontDisplay;
     /** Glyph subsetting: request only the glyphs needed to render exactly this text (Google's `&text=`).
-     * Ideal for a logo/heading font — produces one tiny file. */
+     * Ideal for a logo/heading font - produces one tiny file. */
     readonly text?: string;
     /** CLS metric overrides forwarded to every generated `@font-face` (the layout-shift fix). */
     readonly sizeAdjust?: string;
@@ -77,7 +77,7 @@ export interface LoadGoogleFontResult {
     readonly css: string;
     /** Every file written to `outDir`. */
     readonly assets: readonly FontAsset[];
-    /** `fontPreload()` link-attribute sets — spread the ones you want into a layout's `meta.link`.
+    /** `fontPreload()` link-attribute sets - spread the ones you want into a layout's `meta.link`.
      * Preloading *every* weight/subset is wasteful; usually preload just the primary subset + weight. */
     readonly preloads: readonly LinkDescriptor[];
 }
@@ -93,13 +93,13 @@ export interface LoadGoogleFontIO {
     /** Per-file download cap in bytes. Defaults to 5 MB (real woff2 are well under 1 MB). */
     readonly maxBytesPerFile?: number;
 }
-/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL — the only host we'll download from. */
+/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL - the only host we'll download from. */
 export declare function isAllowedFontUrl(raw: string): boolean;
 /** Build the Google Fonts CSS2 request URL. Pure + fully validated, so it's safe to feed a dynamic
  * family/weights/text. Exported for advanced callers who fetch + parse the stylesheet themselves. */
 export declare function googleFontsCssUrl(options: GoogleFontOptions): string;
 /** Parse Google's stylesheet into structured faces, capturing the `/* subset *​/` label that precedes
- * each `@font-face`. Pure — exported so callers can run their own download/write pipeline. */
+ * each `@font-face`. Pure - exported so callers can run their own download/write pipeline. */
 export declare function parseGoogleFontCss(css: string): ParsedFontFace[];
 /**
  * Download a Google font, self-host it, and return a CLS-safe `@font-face` stylesheet + preloads.

package/dist/fonts-google.js

@@ -1,12 +1,12 @@
 /**
- * Build-time Google Fonts automation — the `next/font/google` equivalent. At **build time** (never on
+ * Build-time Google Fonts automation - the `next/font/google` equivalent. At **build time** (never on
  * the request path) it: builds the Google Fonts CSS2 URL, downloads the stylesheet, parses the
  * `@font-face` rules, downloads each `.woff2`, content-hashes it, writes it next to your assets, and
  * hands back a **self-hosted** `@font-face` stylesheet + the matching `<link rel="preload">`s. The
- * result is identical to dropping the files in yourself and calling {@link fontFace} — no runtime CDN
+ * result is identical to dropping the files in yourself and calling {@link fontFace} - no runtime CDN
  * hotlink, no layout shift, hashed filenames for immutable caching.
  *
- *   // fonts.build.ts — run once at build time (e.g. a prebuild step)
+ *   // fonts.build.ts - run once at build time (e.g. a prebuild step)
  *   import { loadGoogleFont } from "@nifrajs/web/fonts"
  *   const inter = await loadGoogleFont(
  *     { family: "Inter", weights: [400, 700], subsets: ["latin"] },
@@ -16,7 +16,7 @@
  *   // inter.preloads → spread into a root layout's `meta.link`
  *
  * Security: this fetches remote content and writes it to disk, so every input is validated and the
- * font-file host is **allowlisted to `fonts.gstatic.com` over https** — a tampered/MITM'd stylesheet
+ * font-file host is **allowlisted to `fonts.gstatic.com` over https** - a tampered/MITM'd stylesheet
  * cannot make the build fetch an arbitrary URL (SSRF) or write an attacker-chosen blob. Downloads are
  * size-capped. Filenames are derived only from validated tokens + a content hash (no path traversal).
  */
@@ -39,7 +39,7 @@ const VALID_DISPLAY = new Set([
     "fallback",
     "optional",
 ]);
-/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL — the only host we'll download from. */
+/** `true` iff `raw` is an `https://fonts.gstatic.com/…` URL - the only host we'll download from. */
 export function isAllowedFontUrl(raw) {
     let url;
     try {
@@ -63,7 +63,7 @@ function validateFamily(family) {
 function normalizeWeight(weight) {
     if (typeof weight === "number") {
         if (!Number.isInteger(weight) || weight < 1 || weight > 1000) {
-            throw new Error(`loadGoogleFont: invalid weight ${weight} (1–1000)`);
+            throw new Error(`loadGoogleFont: invalid weight ${weight} (1-1000)`);
         }
         return String(weight);
     }
@@ -134,7 +134,7 @@ function declOf(body, prop) {
     return m?.[1]?.trim();
 }
 /** Parse Google's stylesheet into structured faces, capturing the `/* subset *​/` label that precedes
- * each `@font-face`. Pure — exported so callers can run their own download/write pipeline. */
+ * each `@font-face`. Pure - exported so callers can run their own download/write pipeline. */
 export function parseGoogleFontCss(css) {
     const faces = [];
     for (const match of css.matchAll(FACE_RE)) {
@@ -165,7 +165,7 @@ export function parseGoogleFontCss(css) {
     }
     return faces;
 }
-/** First 16 hex chars of the SHA-256 of the bytes — a content hash for an immutable, cache-busting
+/** First 16 hex chars of the SHA-256 of the bytes - a content hash for an immutable, cache-busting
  * filename. Web Crypto, so it runs identically on Bun/Node/edge build hosts. `Uint8Array<ArrayBuffer>`
  * (not the generic `ArrayBufferLike`) to satisfy WebCrypto's `BufferSource` under TS 5.7+ generics. */
 async function contentHash(bytes) {
@@ -180,7 +180,7 @@ const slug = (s) => s
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "");
-/** Host of a URL for error messages — we never echo the full untrusted URL+path. */
+/** Host of a URL for error messages - we never echo the full untrusted URL+path. */
 const hostOf = (raw) => {
     try {
         return new URL(raw).host;
@@ -229,7 +229,7 @@ export async function loadGoogleFont(options, io) {
     if (faces.length === 0) {
         throw new Error(`loadGoogleFont: Google returned no @font-face rules for ${JSON.stringify(family)}`);
     }
-    // Filter to requested named subsets — but only when not glyph-subsetting (text mode labels faces
+    // Filter to requested named subsets - but only when not glyph-subsetting (text mode labels faces
     // `[0]`, `[1]`, … which carry no subset name).
     if (wantedSubsets && wantedSubsets.length > 0 && options.text === undefined) {
         faces = faces.filter((f) => wantedSubsets.includes(f.subset));

package/dist/fonts.d.ts

@@ -1,17 +1,17 @@
 /**
- * Font optimization primitives — generate a **CLS-safe `@font-face`** rule and the matching
+ * Font optimization primitives - generate a **CLS-safe `@font-face`** rule and the matching
  * **preload `<link>`** for a self-hosted font. The two fixes that matter most (the ones `next/font`
  * automates) are right here: `font-display: swap` (text paints immediately, no invisible-text FOIT)
  * plus a preload so the file downloads with the document, and optional metric overrides
  * (`size-adjust`/`ascent-override`/…) so swapping from the fallback to the web font doesn't shift layout.
  *
- * Self-host the file (drop a `.woff2` in your assets — never hotlink Google's CDN), then:
+ * Self-host the file (drop a `.woff2` in your assets - never hotlink Google's CDN), then:
  *
- *   // fonts.css (imported by your app — the CSS pipeline bundles + links it)
+ *   // fonts.css (imported by your app - the CSS pipeline bundles + links it)
  *   import { fontFace } from "@nifrajs/web"
  *   export default fontFace({ family: "Inter", src: [{ url: "/fonts/inter.woff2" }], weight: "100 900" })
  *
- *   // a root layout's meta — becomes a <link rel="preload" as="font"> in <head>
+ *   // a root layout's meta - becomes a <link rel="preload" as="font"> in <head>
  *   export const meta = { link: [fontPreload({ href: "/fonts/inter.woff2" })] }
  */
 import type { LinkDescriptor } from "./manifest.js";
@@ -32,7 +32,7 @@ export interface FontFace {
     readonly style?: "normal" | "italic" | "oblique";
     /** Defaults to `"swap"` (no flash of invisible text). */
     readonly display?: FontDisplay;
-    /** Restrict the glyphs this face covers, e.g. `"U+0000-00FF"` — lets the browser skip the download
+    /** Restrict the glyphs this face covers, e.g. `"U+0000-00FF"` - lets the browser skip the download
      * for pages without those characters. */
     readonly unicodeRange?: string;
     /** Metric overrides that eliminate layout shift when the fallback swaps to the web font (the
@@ -53,13 +53,13 @@ export interface FontPreloadInput {
     readonly href: string;
     /** MIME type (`font/woff2`, …). Inferred from the extension when omitted. */
     readonly type?: string;
-    /** `crossorigin` mode — defaults to `"anonymous"`. Fonts are always fetched in CORS mode, and a
+    /** `crossorigin` mode - defaults to `"anonymous"`. Fonts are always fetched in CORS mode, and a
      * preload whose `crossorigin` doesn't match the actual fetch is **wasted** (downloaded twice), so
      * this is on by default. */
     readonly crossOrigin?: "anonymous" | "use-credentials";
 }
 /**
- * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` — nifra injects it
+ * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` - nifra injects it
  * into `<head>` (`<link rel="preload" as="font" type="font/woff2" crossorigin="anonymous">`). Values are
  * escaped at injection by the head renderer. Preloading the font file removes a render-blocking round
  * trip (the browser would otherwise discover the font only after parsing the CSS).

package/dist/fonts.js

@@ -69,7 +69,7 @@ export function fontFace(face) {
     return `@font-face {\n  ${declarations.join(";\n  ")};\n}`;
 }
 /**
- * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` — nifra injects it
+ * Build a font preload as a `<link>` attribute set for a route/layout's `meta.link` - nifra injects it
  * into `<head>` (`<link rel="preload" as="font" type="font/woff2" crossorigin="anonymous">`). Values are
  * escaped at injection by the head renderer. Preloading the font file removes a render-blocking round
  * trip (the browser would otherwise discover the font only after parsing the CSS).