@mauroandre/velojs 0.0.60 → 0.0.61

package/dist/channels.d.ts

@@ -7,6 +7,14 @@
  * 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 tab-facing twin is the live action: a module declares
+ * `liveActions = { actionName: [channel, …] }` and the framework derives
+ * `GET /_live/{moduleId}/{actionName}` — a subscription whose args travel in
+ * `?_args=` and whose source is the action itself (a parameterized read,
+ * re-executed with those args). The subscription enters the SAME groups by
+ * (channel, partition): one `emit` by name wakes the loader connections and
+ * the live subscriptions of the partition, each re-executing its own source.
+ *
  * The app owns the partition policy in `app/channels.ts`, a name → resolver map:
  *
  * ```ts
@@ -15,7 +23,8 @@
  * };
  * ```
  *
- * On subscribe the resolver receives `{ user, params }`: `user` is the
+ * On subscribe the resolver receives `{ user, params }` (a loader connection)
+ * or `{ user, args }` (a live action subscription): `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
@@ -56,7 +65,7 @@
  * 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";
+import type { ActionArgs, LoaderArgs, RouteModule } from "./types.js";
 import { type TelemetryStatus, type TelemetryTrace } from "./telemetry.js";
 /** Result of a partition resolver. `null`/`undefined` denies the subscription. */
 export type ChannelScopeResult = string | null | undefined;
@@ -76,6 +85,12 @@ export type ChannelScopeResult = string | null | undefined;
 export interface ChannelScopeContext {
     user?: any;
     params?: Record<string, any>;
+    /**
+     * The declared arguments of a **live action** subscription (`kind: "live"`).
+     * The tab-facing twin of `params`: the address the subscription itself
+     * declared, not something the route declares.
+     */
+    args?: Record<string, any> | undefined;
 }
 /**
  * What `onGroupOpen` receives: the partition key of the group that just got its
@@ -86,14 +101,27 @@ export interface ChannelScopeContext {
  * 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.
+ *
+ * `args` is the live-action half of the same address: when the connection that
+ * opened the group is a live action subscription, they are the args that
+ * subscription declared (with the same arbitrariness caveat when the partition
+ * does not derive from them).
  */
 export interface ChannelGroupOpenContext {
     partition: string;
     params: Record<string, string>;
+    /** The declared args of the connection that opened the group (live actions). */
+    args?: Record<string, unknown> | undefined;
 }
-/** What `onGroupClose` receives: the partition key of the group being torn down. */
+/**
+ * What `onGroupClose` receives: the partition key of the group being torn
+ * down and, when the group was opened by a live action subscription, the args
+ * of that connection — the same fields `onGroupOpen` saw.
+ */
 export interface ChannelGroupCloseContext {
     partition: string;
+    /** The declared args of the connection that opened the group (live actions). */
+    args?: Record<string, unknown> | undefined;
 }
 /**
  * One entry of the app's channel map (`app/channels.ts`).
@@ -206,13 +234,31 @@ export interface ChannelConnection {
     /** Partition key resolved at subscribe time — never from client input. */
     partition: string;
     moduleId: string;
+    /**
+     * Which surface the connection feeds: `"loader"` (the page's live-loader
+     * connection — the default) or `"live"` (a live action subscription, the
+     * tab-facing twin).
+     */
+    kind?: "loader" | "live";
     /**
      * 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. */
+    /** The module's loader — the data source of a `"loader"` connection. */
+    loader?: (args: LoaderArgs) => Promise<unknown>;
+    /** The live action — the data source of a `"live"` connection. */
+    action?: (args: ActionArgs<any>) => Promise<unknown>;
+    /** The action name without the `action_` prefix (`"live"` connections). */
+    actionName?: string | undefined;
+    /** The subscription's declared args (`"live"` connections) — the tab's address. */
+    args?: Record<string, unknown> | undefined;
+    /**
+     * Identifies one live action subscription across the N group entries it
+     * holds (one per declared channel) — the inspector's key.
+     */
+    liveId?: string | undefined;
+    /** The subscribing request's context — the loader/action re-runs against it. */
     c: Context;
     params: Record<string, string>;
     query: Record<string, string>;
@@ -260,25 +306,47 @@ export interface ChannelInspectWindow {
     channel: string;
     partition: string;
 }
+/** One live action subscription, as the inspector reports it. */
+export interface ChannelInspectLiveAction {
+    /** The route module holding the action (`metadata.moduleId`). */
+    moduleId: string;
+    /** The action name, without the `action_` prefix. */
+    action: string;
+    /** Every (channel, partition) group the subscription entered. */
+    channels: {
+        channel: string;
+        partition: string;
+    }[];
+    /** The args the subscription declared — its address. */
+    args: Record<string, unknown> | null;
+    /** ISO timestamp of the subscription's last delivery; `null` when none yet. */
+    lastDeliveryAt: string | null;
+}
 /** 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[];
+    /** The live action subscriptions, per (moduleId, action, args). */
+    liveActions: ChannelInspectLiveAction[];
     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`.
+ * the timestamp of its last delivery; the coalescing windows still open; the
+ * live action subscriptions (module, action, args and the groups they hold);
+ * and the grand totals — where each live subscription counts once, however
+ * many channel groups it entered. 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
+ * Executes the connection's data source (the loader of a page connection, the
+ * action of a live subscription) 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
@@ -286,8 +354,8 @@ export declare function __resetChannels(): void;
  * 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
+ * A source that throws reports the failure on the connection (`error` event)
+ * instead of dying silently; a source that returns a `Response` (a redirect
  * short-circuit) has no state to send.
  */
 export declare function pushSnapshot(conn: ChannelConnection): Promise<TelemetryStatus>;
@@ -375,3 +443,41 @@ export declare function parseRouteParamsQuery(raw: string | undefined | null, de
  * whose partition no longer holds.
  */
 export declare function registerChannelRoute(app: Hono, path: string, channel: string, module: RouteModule, moduleId: string, middlewares: MiddlewareHandler[]): void;
+/** Query key carrying the subscription's declared args. */
+export declare const LIVE_ARGS_QUERY = "_args";
+/**
+ * The serialized-args ceiling of a live action subscription, in bytes. Args
+ * travel on the URL — the ceiling keeps the address an address, not a payload;
+ * a bigger read wants an action call plus channels on the page.
+ */
+export declare const LIVE_ARGS_MAX_BYTES = 4096;
+/**
+ * Parses and validates the `?_args=` payload of a live action subscription.
+ *
+ * The client declares the args of the tab it opened; they are the subscription's
+ * identity (a change reconnects) and the `body` of every re-execution. An
+ * absent payload is the empty object — a live action may take no arguments.
+ */
+export declare function parseLiveArgsQuery(raw: string | undefined | null): {
+    args: Record<string, unknown>;
+    error: string | null;
+};
+/**
+ * Registers the internal SSE route of one declared live action:
+ * `GET /_live/{moduleId}/{actionName}`, inheriting the route node's
+ * middlewares — the subscription is guarded exactly like the action call and
+ * the page are.
+ *
+ * The action runs once on subscribe (the snapshot of connection is the whole
+ * loading gesture — no initial POST exists) and once per emit in any of the
+ * declared channels, always with the args declared in the subscription as
+ * `body`. The subscription enters the groups of every declared channel: an
+ * emit in any one delivers.
+ *
+ * Guards are loud: an action that does not exist in the module, or a channel
+ * with no entry in `app/channels.ts`, is an explicit error — never a silent
+ * inert route. Args above `LIVE_ARGS_MAX_BYTES` reject the subscription with
+ * 400, naming the action and the limit; a scope that resolves to nothing (or
+ * throws) denies it with 403.
+ */
+export declare function registerLiveActionRoute(app: Hono, path: string, actionName: string, channels: readonly string[], module: RouteModule, moduleId: string, middlewares: MiddlewareHandler[]): void;