@mauroandre/velojs 0.0.55 → 0.0.57

package/dist/channels.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Live loader — server-side runtime (slice 1).
+ *
+ * A route module opts into state synchronization with a sibling `channels`
+ * export (an array of channel names). The framework derives one internal SSE
+ * route per declared channel — `GET /_channel/{moduleId}/{channel}`, the same
+ * family as `/_action` and `/_event` — which inherits the middlewares of the
+ * module's route node and serves the module's loader as a stream of snapshots.
+ *
+ * The app owns the partition policy in `app/channels.ts`, a name → resolver map:
+ *
+ * ```ts
+ * export const channels = {
+ *     teamExpenses: { scope: ({ user }) => `team:${user?.teamId}` },
+ * };
+ * ```
+ *
+ * On subscribe the resolver receives `{ user, params }`: `user` is the
+ * materialized principal (`c.get("user")`, the house key — `undefined` when the
+ * app does not materialize one, so a public channel ignores it and an
+ * authenticated one returns `null`, which denies the subscription with 403) and
+ * `params` are the route params the client declared and the runtime validated
+ * against the module's path (empty for a route without `:params`). The
+ * partition NEVER derives from the query string or from any other client input;
+ * `params` are not input — they are the address the client is already seeing,
+ * validated by shape and then by the scope (ownership/permission).
+ *
+ * `emit(channel, ctx)` resolves the same partition key on the producer side —
+ * the producer builds the same `{ user, params }` shape with the fields its
+ * scope consumes — finds the group of connections in that partition and
+ * re-executes the loader for each connection, with that connection's own
+ * principal and route params, pushing a fresh snapshot down the wire. Emitting
+ * to a channel with no subscribers is a no-op; emitting to a channel with no
+ * entry in the app map throws immediately.
+ *
+ * `emit(module, channel, ctx, slice)` is the second mode, addressed to the
+ * (module, channel) pair: the producer already holds the value, so it travels
+ * as a slice — the connections of that pair in the emitting partition merge it
+ * shallowly by key, and no loader runs. The slice is typed as a `Partial` of
+ * the module's loader return, which is why the module is part of the address:
+ * one channel can be declared by modules with different `Data` (a layout and a
+ * page), and a slice is the shape of exactly one of them.
+ *
+ * A channel's group (channel + partition) has a lifecycle: the first connection
+ * arms it (`onGroupOpen({ partition, params })`) and the last one disarms it
+ * (`onGroupClose({ partition })`), both awaited — that is where a watcher with a
+ * cost of life is armed and disarmed, instead of running forever for an empty
+ * group.
+ *
+ * Every emit logs one line (channel, partition, kind, connections at the
+ * moment of the gesture, timestamp) unless `logEmits: false` is registered,
+ * and invalidations are folded by a coalescing window per (channel, partition)
+ * (`coalesceMs`, default 50, `0` disables). Before delivering anything the
+ * runtime re-derives each connection's partition with the ctx captured on
+ * subscribe: a connection that moved (or whose scope now returns null) is
+ * dropped and closed instead of receiving data of a group it left.
+ */
+import type { Context, Hono, MiddlewareHandler } from "hono";
+import type { LoaderArgs, RouteModule } from "./types.js";
+/** Result of a partition resolver. `null`/`undefined` denies the subscription. */
+export type ChannelScopeResult = string | null | undefined;
+/**
+ * The ctx of a partition resolver — the same shape on both sides.
+ *
+ * On **subscribe** the runtime builds it: `user` is the materialized principal
+ * (`c.get("user")`, the house key — `undefined` when the app does not
+ * materialize one) and `params` are the route params the client declared and
+ * the runtime validated against the module's path (URL strings; empty for a
+ * route without `:params`).
+ *
+ * On **emit** the producer builds the same object with the fields its scope
+ * consumes — `{ params: { id: 7 } }` for a resource channel, `{ user: … }`
+ * for a principal one — and the same `scope` runs against it.
+ */
+export interface ChannelScopeContext {
+    user?: any;
+    params?: Record<string, any>;
+}
+/**
+ * What `onGroupOpen` receives: the partition key of the group that just got its
+ * first connection, and the validated route params of **that** connection.
+ *
+ * The params are identical across the group only when the partition derives
+ * from them (a watcher per resource — the case the hook exists for). A channel
+ * partitioned by principal, declared in a module with `:params`, mixes
+ * resources in the same group and the hook's params are the first connection's
+ * — arbitrary for the rest; such a channel must not consume them here.
+ */
+export interface ChannelGroupOpenContext {
+    partition: string;
+    params: Record<string, string>;
+}
+/** What `onGroupClose` receives: the partition key of the group being torn down. */
+export interface ChannelGroupCloseContext {
+    partition: string;
+}
+/**
+ * One entry of the app's channel map (`app/channels.ts`).
+ *
+ * `scope` receives `{ user, params }` on subscribe and the emitter's object on
+ * emit; returning `null` denies with 403. Omitted → the channel is public
+ * (`() => "all"`).
+ *
+ * `onGroupOpen`/`onGroupClose` are the group lifecycle — armed by the first
+ * connection of a (channel, partition) group, disarmed by the last one — and
+ * may be async: the runtime awaits them (the group is only marked open after
+ * `onGroupOpen` resolves; only discarded after `onGroupClose` resolves). A hook
+ * that throws or rejects is logged loudly and the group continues.
+ */
+export interface ChannelDefinition {
+    scope?: (ctx: ChannelScopeContext) => ChannelScopeResult | Promise<ChannelScopeResult>;
+    onGroupOpen?: (ctx: ChannelGroupOpenContext) => void | Promise<void>;
+    onGroupClose?: (ctx: ChannelGroupCloseContext) => void | Promise<void>;
+}
+/** The `app/channels.ts` map: channel name → partition resolver. */
+export type ChannelMap = Record<string, ChannelDefinition>;
+/** SSE event carrying the loader's current value — it replaces the module's data. */
+export declare const SNAPSHOT_EVENT = "snapshot";
+/** SSE event carrying a slice — the client merges it into the module's current value. */
+export declare const SLICE_EVENT = "slice";
+/** SSE event signaling that the loader re-execution failed on the server. */
+export declare const CHANNEL_ERROR_EVENT = "error";
+/** SSE event signaling a deliberate server-side close. */
+export declare const CHANNEL_CLOSE_EVENT = "close";
+/** Default coalescing window, in milliseconds. */
+export declare const DEFAULT_COALESCE_MS = 50;
+/**
+ * Default idle timeout of a channel connection, in milliseconds: a connection
+ * with no deliveries (snapshot or slice) for this long is closed by the
+ * server. The heartbeat does NOT reset it — idle is about data delivery,
+ * heartbeat is transport. The close makes a live page cycle
+ * (close → EventSource reconnect → snapshot on connect), which repairs the
+ * state, and frees an abandoned page's resources for good.
+ */
+export declare const DEFAULT_IDLE_MS = 300000;
+/** The two modes of `emit`, as they appear in the emit log. */
+export type ChannelEmitKind = "invalidate" | "slice";
+/**
+ * `registerChannels` options.
+ *
+ * `coalesceMs` is the coalescing window of the invalidation mode, per
+ * (channel, partition): every emit inside an open window becomes one
+ * re-execution round, fired when the window closes. `0` disables it (immediate
+ * — the slice-1 behavior). The default is `DEFAULT_COALESCE_MS` in any
+ * registration without options; `createTestApp` registers with `0` for
+ * determinism.
+ *
+ * `logEmits` writes one line per emit gesture (never per consolidated
+ * delivery). Default: on.
+ *
+ * `idleMs` closes a connection that had no deliveries (snapshot or slice) for
+ * that long — a silent connection is closed even though its heartbeat keeps
+ * flowing; heartbeats never reset the idle clock. Default: `DEFAULT_IDLE_MS`
+ * (5 min) in any registration without options; `0` disables it.
+ * `createTestApp` registers with `0` for determinism.
+ *
+ * `heartbeatMs` writes an SSE comment (`: ping`) through the write chain every
+ * interval, keeping proxies and the browser from buffering or closing an idle
+ * stream. A comment generates no client event and never counts as a delivery
+ * (no effect on freshness or idle). Default: `DEFAULT_HEARTBEAT_MS` (20s) in
+ * any registration without options; `0` disables it.
+ */
+export interface ChannelRegistryOptions {
+    coalesceMs?: number;
+    logEmits?: boolean;
+    idleMs?: number;
+    heartbeatMs?: number;
+}
+/**
+ * What `emit(module, channel, ctx, slice)` accepts: the imported route module
+ * (the same object the route tree uses — the Vite plugin has injected its
+ * `metadata`, and its `loader` types the slice).
+ */
+export interface ChannelEmitModule {
+    metadata?: {
+        moduleId?: string;
+    } | undefined;
+    channels?: readonly string[] | undefined;
+    loader?: ((args: LoaderArgs) => unknown) | undefined;
+}
+/**
+ * The slice type of a module: a `Partial` of whatever its loader returns.
+ * `Partial` (plus `exactOptionalPropertyTypes` on the app's tsconfig) is what
+ * makes a wrong key or a wrong value type a compile error instead of a silent
+ * no-op at runtime.
+ */
+export type ChannelSlice<M> = M extends {
+    loader?: (...args: any[]) => infer R;
+} ? Partial<Awaited<R>> : never;
+/**
+ * Registers (replaces) the app's channel map and its options. Idempotent.
+ *
+ * Called without options, the coalescing window is `DEFAULT_COALESCE_MS` — the
+ * window matters wherever emits burst (a job writing N rows), not only in
+ * production.
+ */
+export declare function registerChannels(map: ChannelMap | undefined, options?: ChannelRegistryOptions): void;
+/** The currently registered channel map (read-only use). */
+export declare function getChannelMap(): ChannelMap;
+/** Channel names declared in the app map, in declaration order. */
+export declare function channelNames(): string[];
+/** One live channel connection (an SSE subscription). */
+export interface ChannelConnection {
+    channel: string;
+    /** Partition key resolved at subscribe time — never from client input. */
+    partition: string;
+    moduleId: string;
+    /**
+     * The principal materialized at subscribe (`c.get("user")`), captured for
+     * the partition revalidation of every emit — the scope re-runs against it.
+     */
+    principal: unknown;
+    loader: (args: LoaderArgs) => Promise<unknown>;
+    /** The subscribing request's context — the loader re-runs against it. */
+    c: Context;
+    params: Record<string, string>;
+    query: Record<string, string>;
+    /** Writes one SSE event on this connection. Resolves when it hits the wire. */
+    send: (event: string, data: string) => Promise<void>;
+    /**
+     * Ends this connection: a `close` event on the wire, then the group entry
+     * and the stream. Used when the connection's partition no longer holds —
+     * or when its idle timeout elapsed.
+     */
+    terminate: (reason?: string) => Promise<void>;
+    /**
+     * Epoch ms of this connection's last delivery (snapshot or slice) — the
+     * clock the idle timeout runs on and what the inspector reports. Heartbeat
+     * comments never touch it.
+     */
+    lastDeliveryAt?: number | undefined;
+}
+/** One live group of a channel: the connections of one module in one partition. */
+export interface ChannelInspectGroup {
+    /** The route module holding these connections (`metadata.moduleId`). */
+    moduleId: string;
+    /** The partition key resolved at subscribe time. */
+    partition: string;
+    /** Live connections in this (module, partition) pair. */
+    connections: number;
+    /** ISO timestamp of the last delivery; `null` when none was delivered yet. */
+    lastDeliveryAt: string | null;
+}
+/** One live channel: its groups and its total. */
+export interface ChannelInspectChannel {
+    channel: string;
+    /** Groups identified by (moduleId, partition) — which page holds what. */
+    groups: ChannelInspectGroup[];
+    connections: number;
+}
+/** One open coalescing window: the invalidations not yet delivered. */
+export interface ChannelInspectWindow {
+    channel: string;
+    partition: string;
+}
+/** The full live state of the channel registry, as `inspectChannels()` sees it. */
+export interface ChannelInspectReport {
+    channels: ChannelInspectChannel[];
+    /** Open coalescing windows, per (channel, partition). */
+    openCoalesceWindows: ChannelInspectWindow[];
+    totalConnections: number;
+}
+/**
+ * Server-side snapshot of the live channels: per channel, the groups
+ * identified by (moduleId, partition key), each with its connection count and
+ * the timestamp of its last delivery; the coalescing windows still open; and
+ * the grand totals. Always available — the app decides how (and with what
+ * guard) to expose it; the dev server exposes it as `GET /_channel-inspect`.
+ */
+export declare function inspectChannels(): ChannelInspectReport;
+/** Test-only. Drops every live connection, group and open window. */
+export declare function __resetChannels(): void;
+/**
+ * Executes the connection's loader with the connection's own principal and
+ * pushes the result as a snapshot. Per-connection execution (rather than one
+ * execution per partition) is deliberate: every subscriber always receives the
+ * snapshot computed with its own scope, which makes the homogeneous-partition
+ * rule unnecessary as a security invariant. What a burst of invalidations
+ * amortizes is the number of *rounds*, not the executions inside one — a single
+ * computation serving the whole partition is a later slice.
+ *
+ * A loader that throws reports the failure on the connection (`error` event)
+ * instead of dying silently; a loader that returns a `Response` (a redirect
+ * short-circuit) has no state to send.
+ */
+export declare function pushSnapshot(conn: ChannelConnection): Promise<void>;
+/**
+ * Signals that a channel's partition changed: every connection in that
+ * partition receives a fresh snapshot (its loader re-executed with the
+ * connection's own principal and route params). Connections in other
+ * partitions receive nothing; a channel with no subscribers is a no-op; a
+ * channel with no entry in the app map throws immediately, naming the channel.
+ *
+ * The ctx is the object the same `scope` receives: the producer builds it with
+ * the fields its scope consumes (`{ params: { id: 7 } }` for a resource
+ * channel, `{ user: … }` for a principal one).
+ *
+ * ```ts
+ * import { emit } from "@mauroandre/velojs/server";
+ * await emit("teamExpenses", { user: { teamId: 7 } });
+ * ```
+ */
+export declare function emit(channel: string, ctx?: ChannelScopeContext): Promise<void>;
+/**
+ * Slice mode: pushes the value the producer already holds to the connections
+ * of the (module, channel) pair in the emitting partition — **without**
+ * re-executing the loader. The slice is typed as a `Partial` of what the
+ * module's loader returns, and the merge on arrival is shallow by key.
+ *
+ * ```ts
+ * import * as Expenses from "../app/expenses/Expenses.js";
+ * await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
+ * ```
+ */
+export declare function emit<M extends ChannelEmitModule>(module: M, channel: string, ctx: ChannelScopeContext, slice: ChannelSlice<M>): Promise<void>;
+/**
+ * Serializes the SSE writes of one connection and never lets a failed write
+ * break the chain.
+ *
+ * A write can fail because the client went away mid-event (tab closed, proxy
+ * cut). The connection is cleaned up by the abort handler either way, but the
+ * failure is logged instead of swallowed: a snapshot lost in a dead write must
+ * not be indistinguishable from an emit that never happened.
+ */
+export declare function createChannelWriteChain(channel: string, write: (payload: ChannelWritePayload) => Promise<unknown>): (payload: ChannelWritePayload) => Promise<void>;
+/**
+ * What the write chain carries: an SSE event (`{ event, data }`) or a raw
+ * chunk — the heartbeat is a comment (`": ping\n\n"`), which is no event at
+ * all: no client event fires for it and no delivery clock moves.
+ */
+export type ChannelWritePayload = {
+    event: string;
+    data: string;
+} | string;
+/** Query key carrying the route params the connection declares. */
+export declare const ROUTE_PARAMS_QUERY = "_route";
+/**
+ * The `:param` names a route path declares, in declaration order. A path with
+ * a catch-all (`/docs/*`) declares none: the pattern has no key to extract, so
+ * the connection travels by principal only.
+ */
+export declare function declaredRouteParams(fullPath: string | null | undefined): string[];
+/**
+ * Parses and validates the `?_route=` payload of a channel connection against
+ * the names the module's route path declares.
+ *
+ * The client declares the params of the URL it is already seeing; it is not
+ * free input: a key the module's path does not declare rejects the
+ * subscription with an explicit error, and every value is a URL string. An
+ * absent payload is the empty object — a route without `:params` sends none.
+ */
+export declare function parseRouteParamsQuery(raw: string | undefined | null, declared: readonly string[]): {
+    params: Record<string, string>;
+    error: string | null;
+};
+/**
+ * Registers the internal SSE route of one declared channel:
+ * `GET /_channel/{moduleId}/{channel}`, inheriting the route node's
+ * middlewares (auth policy is declared once per node).
+ *
+ * Guards are loud: a module that declares `channels` without a `loader`, or a
+ * channel with no entry in `app/channels.ts`, is an explicit error — never a
+ * silent inert route.
+ *
+ * The connection carries the client-declared route params (validated here
+ * against the module's path), the principal captured for the partition
+ * revalidation of every emit, and `terminate` lets an emit close a connection
+ * whose partition no longer holds.
+ */
+export declare function registerChannelRoute(app: Hono, path: string, channel: string, module: RouteModule, moduleId: string, middlewares: MiddlewareHandler[]): void;