@mauroandre/velojs 0.0.55 → 0.0.57

package/README.md

@@ -461,6 +461,414 @@ SPA navigation:
 
 ---
 
+## Live Loader
+
+A page value that must **track server state over time** — a total another
+person's request changes, data a background scheduler mutates — declares the
+channels that keep it fresh. No extra component, no manual subscription: the
+module exports `channels` next to its `loader`.
+
+```tsx
+// app/expenses/Expenses.tsx
+export const loader = async ({ c }: LoaderArgs) => {
+    const user = c.get("user");
+    return {
+        teamTotal: await expensesService.teamTotal(user.teamId),
+        expenses: await expensesService.byTeam(user.teamId),
+    };
+};
+export const channels = ["teamExpenses"];
+
+export const Component = () => {
+    const { data, freshness } = useLoader();
+    return <h2 class={freshness.value}>Team: ${data.value?.teamTotal}</h2>;
+};
+```
+
+```ts
+// app/channels.ts — the app's channel map: name → partition resolver
+export const channels = {
+    teamExpenses: {
+        // On subscribe the ctx is { user, params }: the principal materialized
+        // in c.get("user") and the route params the connection declared. On
+        // emit it is the object the producer built, with the fields this scope
+        // consumes. Returns the partition key.
+        scope: ({ user }) => `team:${user.teamId}`,
+    },
+};
+```
+
+```ts
+// anywhere server-side: an action, server.tsx, a scheduler, a webhook
+import { emit } from "@mauroandre/velojs/server";
+
+await emit("teamExpenses", { user: { teamId: 7 } });
+```
+
+### What happens
+
+- The framework derives one internal SSE route per declared channel —
+  `GET /_channel/{moduleId}/{channel}`, the same family as `/_action` and
+  `/_event` — inheriting the `middlewares` of the module's route node.
+- After hydration the client opens one connection per (module, channel) of the
+  rendered hierarchy (layout and page alike) and closes it on unmount. A
+  channel declared by both a layout and a page produces one connection per
+  module, each feeding its own module's data; a single `emit` reaches both.
+- Every new connection immediately receives the **current state**, computed by
+  re-executing the loader with that connection's own principal and route
+  params — so the pane never shows the SSR value while the server has already
+  moved on.
+- `emit(channel, ctx)` resolves the partition with the same `scope` — the
+  producer builds the same `{ user, params }` shape with the fields its scope
+  consumes — finds the connections in that partition and pushes a fresh
+  snapshot to each one: its loader re-executed with its own principal and route
+  params. Connections of other partitions receive nothing.
+- The snapshot **replaces** the module's loader data; the component re-renders
+  by itself. `useLoader()` and `Loader()` also expose `freshness` — `"live"`,
+  `"stale"` (connection closed/reconnecting/silent), `"error"` (the last
+  re-execution failed) — aggregated per page, plus `freshnessByChannel`, the
+  same states keyed by each of the module's channel names. They are data for
+  CSS to react to.
+
+### Routes with `:params` — the client declares, the server decides
+
+A channel declared in a module whose route has `:params` (`/projeto/:id`, a page
+or a layout) partitions per **resource**, and the loader re-executes with
+`params.id` filled — the connect snapshot and every emit.
+
+```tsx
+// app/projeto/Projeto.tsx — the route /projeto/:id
+export const loader = async ({ params }: LoaderArgs) => ({
+    arquivos: await projetoService.arquivos(params.id),
+});
+export const channels = ["projetoArquivos"];
+```
+
+```ts
+// app/channels.ts
+export const channels = {
+    projetoArquivos: {
+        scope: ({ user, params }) => {
+            if (!params?.id) return null;
+            if (user && !podeVer(user, params.id)) return null;   // 403
+            return `projeto:${params.id}`;
+        },
+    },
+};
+```
+
+- The client **declares** the address it is already seeing: it extracts the
+  params the module's `fullPath` declares, matching as a **prefix** of the
+  pathname (a layout `/projeto/:id` covers `/projeto/7/sala` and extracts
+  `id=7`; the child's suffix takes no part) and sends them in `?_route=<json>`.
+  A catch-all (`/docs/*`) declares no `:` key — the connection travels by
+  principal.
+- The server **decides**: it validates the keys against the module's declared
+  path — a key the path does not declare rejects the subscription with **400** —
+  and the `scope` validates the policy (possession/permission), deriving the
+  key. `params` are never an authorization input: they are the declared route,
+  validated by shape and then by policy.
+- The internal `_route` key never reaches the loader's `query`: it is transport,
+  not page data.
+- The connection is **keyed by the extracted params**, not by the pathname:
+  `/projeto/7` → `/projeto/9` closes the connection and opens a new one (with a
+  snapshot on connect); `/projeto/7` → `/projeto/7/sala` does not reconnect.
+
+### Group lifecycle: `onGroupOpen` / `onGroupClose`
+
+A source with a **cost of life** — a filesystem watcher, a process, a
+subscription to an external service — must not run forever for an empty group.
+The first connection of a group (channel + partition) arms it and the last one
+disarms it, by any cause (disconnect, idle, revalidation):
+
+```ts
+export const channels = {
+    projetoArquivos: {
+        scope: ({ params }) => (params?.id ? `projeto:${params.id}` : null),
+        onGroupOpen: ({ params }) =>
+            watchers.armar(params.id, () => emit("projetoArquivos", { params: { id: params.id } })),
+        onGroupClose: ({ partition }) => watchers.desarmar(),
+    },
+};
+```
+
+- A second connection of the same group fires nothing.
+- Both hooks may be async and are **awaited**: on open, before the connect
+  snapshot (the source is armed before the first data arrives); on close, before
+  the group is discarded. A hook that throws (or rejects) is logged loudly,
+  naming channel and partition, and the group continues — the cold-source
+  snapshot still arrives, only the live data waits for the fix.
+- The hook is infrastructure, not policy: it does not receive `user`.
+- The `params` of `onGroupOpen` belong to the connection that opened the group
+  and are identical across it **only when the partition derives from them** (a
+  watcher per resource). A channel partitioned by **principal**, declared in a
+  module with `:params`, mixes resources in one group: do not consume the
+  hook's params there.
+
+### Two ways to emit
+
+**Invalidation** — `emit(channel, ctx)` says *this partition changed*, without
+knowing the shape of the data: the runtime re-executes the loader per connection
+and pushes the snapshot. Use it when only the server knows the new value (a
+background job, another request).
+
+**Slice** — `emit(module, channel, ctx, slice)` says *here is the new value*: the
+producer already holds it, so it travels as-is to the connections of that
+(module, channel) pair in the partition, and **no loader runs**. The slice is
+typed as a `Partial` of what that module's loader returns, so `tsc` rejects an
+unknown key or a wrong value type.
+
+```ts
+import { emit } from "@mauroandre/velojs/server";
+import * as Expenses from "../app/expenses/Expenses.js";
+
+// invalidation: the runtime re-executes Expenses.loader per connection
+await emit("teamExpenses", { user: { teamId: 7 } });
+
+// slice: the value is already in hand — delivered as-is, no re-execution
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
+```
+
+Why the module, and not just the channel name? Because the same channel can be
+declared by a layout **and** by a page, each with its own loader and its own
+`Data` — a slice is the shape of exactly one of them, and it reaches only that
+module's connections. `emit(channel, ctx)` keeps reaching every module of the
+channel.
+
+### The merge contract
+
+- **Snapshot replaces; slice merges.** A snapshot (connect or invalidation) is
+the whole value of the module's data; a slice applies a **shallow** merge by
+key on top of the current value.
+- The key sent is replaced by the **whole value** sent — lists travel whole
+  inside their key; there is no list diff. Keys not sent stay intact.
+- **Removal is explicit**: removing an item is re-sending the key with the new
+  whole list (without the item). An absent key never means "remove".
+- The merge happens **on arrival**, never at render: slices that land in the
+  same frame are applied together before the next render — none is lost — and
+  for the same key the last one in arrival order wins. A malformed payload keeps
+  the previous value.
+- The runtime merges blindly (it is JavaScript); shape safety comes from the
+  emit typing. A key that does not exist in the loader's `Data` only gets in
+  through a cast, and that is a usage error.
+
+### Bursts, log and revalidation
+
+- **Coalescing.** Invalidation emits are folded per (channel, partition): the
+  first opens a window, the emits inside it join, and closing the window fires
+  **one** re-execution round per connection — no invalidation is lost. The
+  default window is `50ms`; `registerChannels(map, { coalesceMs: 0 })` turns it
+  off (immediate), and a slice never waits for it (a slice is pushed directly).
+
+  The window decides what `await emit(…)` waits for: with it off (`0`, and the
+  test toolkit's default) the await resolves after the round was delivered;
+  with it open it resolves as soon as the gesture is registered — the log line
+  is out, the delivery comes later. Never assert a screen update right after
+  `await emit(…)` under the default window: await the arrival (`next()` /
+  `nextEvent()`) or wait for the effect.
+- **Emit log.** Every `emit`, in either mode, writes one `console.log` line at
+  the moment of the gesture:
+
+  ```
+  [velojs] emit kind=invalidate channel="teamExpenses" partition="team:7" connections=2 at=2026-09-30T12:00:00.000Z
+  ```
+
+  `connections` is the size of the group at that instant — before coalescing and
+  before revalidation — and the consolidated delivery writes no second line. An
+  emit whose `scope` resolves to nothing logs `partition=null connections=0`:
+  reaching nobody is exactly what the log is for.
+  `registerChannels(map, { logEmits: false })` silences it. In tests,
+  `createTestApp` registers with the window off and takes the same options in
+  `channelOptions`.
+- **Partition revalidation.** Before delivering anything, the runtime re-derives
+  each connection's partition by running the `scope` again with the ctx captured
+  at subscribe — the principal and the validated route params of that
+  connection. A connection whose partition moved — or whose scope now
+  returns `null` — is removed from the group and closed: the client sees the
+  connection closed (`freshness` goes `"stale"`) and receives none of that
+  emit's data. A `scope` that **throws** on re-derivation is treated the same
+  way — fail-closed, with the failure logged naming the channel — so a scope
+  that does I/O must handle its own failures. Only the partition is revalidated;
+  session expiry stays with the normal request pipeline.
+
+### Transport: heartbeat, idle timeout and the proxy
+
+An SSE connection crosses infrastructure that was not built for it — proxies,
+load balancers, browsers with sleeping tabs. The channel answer is built for
+that traffic, and its transport has exactly two clocks:
+
+- **Heartbeat** — an SSE comment (`: ping`) written through the write chain
+every `heartbeatMs`. It keeps proxies and browsers from buffering or closing an
+idle stream, and it is pure transport: it generates no event in the client and
+does not count as a delivery — it touches neither freshness nor idle. The
+default is `20000` (20s), the same `DEFAULT_HEARTBEAT_MS` the `stream_*` SSE
+surface uses — one transport ruler in the house. `0` disables it.
+- **Idle timeout** — a connection with **no deliveries** (snapshot or slice) for
+`idleMs` is closed by the server. The heartbeat does not reset it: idle is
+about data, heartbeat is transport. A live but quiet page cycles by design —
+close, `EventSource` reconnects by itself, snapshot on connect repairs the
+state — and an abandoned page's resources are freed for good. The default is
+`300000` (5 min) in any registration without options; `0` disables it.
+
+```ts
+// app/channels.ts registration with explicit windows
+registerChannels(channels, { idleMs: 60000, heartbeatMs: 15000 });
+```
+
+The answer also carries `Cache-Control: no-store`: a proxy or the browser must
+never serve a cached channel snapshot — a stale snapshot is exactly the illusion
+the live loader exists to kill.
+
+**Behind a reverse proxy (the house recipe, Caddy).** SSE needs the proxy to
+flush immediately and never buffer the response, or the page goes silent even
+with everything alive. In the Caddyfile, the reverse_proxy for the app needs
+`flush_interval -1` (flush as soon as data arrives — a negative value means
+"immediately", which is what SSE requires; a positive interval would batch
+chunks and delay every snapshot). Caddy passes the request through with
+streaming by default and closes dead upstreams on its own probes — the
+heartbeat then does its part at 20s, and the idle timeout closes what nobody is
+reading anymore. If you put another proxy in front (nginx, a cloud LB), the
+same two rules apply: no response buffering, and `X-Accel-Buffering: no` for
+nginx or the equivalent for the LB.
+
+### Inspecting the live channels
+
+When the incident happens, the server answers "what is alive?":
+
+```ts
+// anywhere server-side (an action, a guarded endpoint of your own)
+import { inspectChannels } from "@mauroandre/velojs/server";
+
+const report = inspectChannels();
+// {
+//   channels: [{
+//     channel: "teamExpenses",
+//     groups: [
+//       { moduleId: "expenses/Layout", partition: "team:7",
+//         connections: 1, lastDeliveryAt: "2026-09-30T12:00:00.000Z" },
+//       { moduleId: "expenses/Expenses", partition: "team:7",
+//         connections: 1, lastDeliveryAt: "2026-09-30T12:00:01.104Z" },
+//     ],
+//     connections: 2,
+//   }],
+//   openCoalesceWindows: [],
+//   totalConnections: 2,
+// }
+```
+
+Per channel, the groups are identified by the pair (moduleId, partition key) —
+in the incident you know which page/module holds every connection — each with
+its connection count and the timestamp of the last delivery; the coalescing
+windows still open; the grand totals. `inspectChannels()` is always available:
+the app decides how (and with what guard) to expose it.
+
+In development there is a ready-made lens: `GET /_channel-inspect` answers the
+same JSON in the browser. It exists **only in dev** — the map of channels and
+partitions is internal information, and it never ships in a production build.
+
+### The partition contract
+
+On subscribe the `scope` receives `{ user, params }`. `user` is `c.get("user")`
+— the house key, the same one the stream/socket channel resolvers use (a
+middleware that materializes the principal elsewhere should set it in `"user"`
+too) — and `params` are the route params the connection declared, already
+validated. Without an authenticated principal `user` is `undefined`: a public
+channel ignores it (`() => "all"`), an authenticated one returns `null`, which
+denies the subscription with 403; an app that does not materialize a principal
+at all (a network guard, e.g. loopback) writes `({ params }) => …`. On emit the
+same scope receives the object the producer built, with the fields it consumes
+(`{ params: … }` or `{ user: … }`). A scope that **throws** on subscribe denies
+with **403** and logs loudly, naming the channel.
+The partition **never** derives from the query string or from any other client
+input: `params` are the declared route — validated by shape — not a choice of
+subject.
+
+### State or flow?
+
+Two questions decide, every time:
+
+| Question | Answer | Tool |
+|---|---|---|
+| Is this a **value** or a **sequence**? | value — "what is it now?", replacement | `loader` + `channels` |
+| | sequence — "what happened?", accumulation (chat, log, progress) | `stream_*` / `socket_*` |
+| Does the change come from **someone else** or from **me**? | someone else / a background job | `loader` + `channels` |
+| | me, through my own action | `refetch()` after the action |
+
+### Guards
+
+- `channels` in a module **without** a `loader`: explicit error in the dev
+  server and in the build ("nothing to synchronize").
+- A channel **without an entry** in `app/channels.ts`: explicit error in the dev
+  server and in the build, naming the channel.
+- `emit()` on a channel with no entry in the map: throws immediately, naming
+  the channel. `emit()` on a valid channel with no subscribers is a no-op.
+- Route params with a key the module's path does **not** declare: the
+  subscription is rejected with **400**, naming the key — the client may only
+  declare what the route declares.
+- A `scope` that **throws** on subscribe: denied with **403** and logged
+  loudly, naming the channel.
+- `emit(module, channel, …)` on a module that does not declare that channel, or
+  that has no `loader`: throws immediately, naming both. A slice that is not an
+  object throws too.
+- `velojs build --static` with a module declaring `channels`: the channels are
+  **inert** (no server for SSE) — the client opens no connection, `freshness`
+  stays `"live"` and the build warns, naming the module.
+- A module outside the conventions (`.jsx`/`.js`, or outside `app/`) is the one
+  genuinely silent line: no transform, so the channel is simply inert.
+
+### Testing a live loader
+
+```ts
+import { createTestApp } from "@mauroandre/velojs/testing";
+import { emit } from "@mauroandre/velojs/server";
+import { channels } from "../app/channels.js";
+import * as Expenses from "../app/expenses/Expenses.js";
+
+const app = await createTestApp({
+    routes,
+    channels,
+    getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
+});
+
+const sub = await app.as({ user: { teamId: 7 } }).channel(Expenses, "teamExpenses");
+await sub.next({ timeoutMs: 1000 });     // snapshot on connect
+await emit("teamExpenses", { user: { teamId: 7 } });
+const snapshot = await sub.next({ timeoutMs: 1000 });
+await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
+const slice = await sub.next({ timeoutMs: 1000 });
+
+// A route with `:params`: the connection declares them (validated for real).
+const project = await app.channel(Project, "projetoArquivos", { params: { id: "7" } });
+expect(await project.next({ timeoutMs: 1000 })).toEqual({ id: "7", files: ["a.txt"] });
+```
+
+`next()` returns the payload exactly as it travelled (a whole snapshot or a raw
+slice); `nextEvent()` returns the same arrivals discriminated —
+`{ type: "snapshot" | "slice", data }`. The toolkit registers the channels with
+the coalescing window off, so `await emit(…)` is the delivery; a test that
+exercises the window passes it in `channelOptions` — a sibling of `channels`,
+which stays the map — and drives it with fake timers:
+
+```ts
+const app = await createTestApp({
+    routes,
+    channels,                                    // the map
+    channelOptions: { coalesceMs: 20 },          // the registration options
+    getSessionCookie,
+});
+```
+
+The same `channelOptions` accepts `idleMs` and `heartbeatMs` — both default to
+`0` in the toolkit (deterministic: no connection dies, no comment is written
+unless the test asks for it and advances fake timers through the window it
+meant). `inspectChannels()` is process-wide and sees the test app's real
+channels: subscribe, emit, inspect, close, inspect again — all without network.
+A test that exercises the idle timeout or the heartbeat arms the window
+explicitly and drives it with fake timers; never assert freshness (in either
+surface) without advancing the fake timers through the window.
+
+---
+
 ## Actions
 
 Server-side functions callable from the client via RPC.
@@ -1375,6 +1783,12 @@ const event = await sub.next({ timeoutMs: 2000 });
 const asAlice = app.as({ user: alice });
 await asAlice.subscribe(stream_progress, { channel: appId });
 
+// Live loader — open a channel with a principal, emit, await the next snapshot
+const live = await app.as({ user: { teamId: 7 } }).channel(Expenses, "teamExpenses");
+await live.next({ timeoutMs: 1000 });            // snapshot on connect
+await emit("teamExpenses", { user: { teamId: 7 } });
+const snapshot = await live.next({ timeoutMs: 1000 });
+
 await app.close();
 ```
 
@@ -1388,6 +1802,7 @@ await app.close();
 | `app.action(fn, opts)` | Invoke `action_*` by function reference |
 | `app.loader(fn, opts)` | Invoke `loader` and unwrap response data |
 | `app.subscribe(stream, opts)` | Subscribe to a stream; returns `TestSubscription` with `next/nextN/snapshot/close/closed` |
+| `app.channel(module, name, opts)` | Open a live-loader channel connection; `opts.params` declares the route params (validated for real — a wrong key rejects with 400); snapshots and slices arrive through `next()` (raw) or `nextEvent()` (`{ type, data }`) |
 | `app.as({ user })` | Sub-client with cookies bound to a user |
 | `app.sessionCookies({ user })` | Build cookies via `getSessionCookie` |
 | `app.mockContext(opts)` | Escape hatch — partial Hono Context for direct invocation |
@@ -1423,11 +1838,11 @@ See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/17-t
 | Import | Contents |
 |--------|----------|
 | `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`, `PerChannelSourceFn`, `ChannelResolver`), `Scripts`, `Link`, `createEventStream`, `poll`, `defineConfig` |
-| `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage` |
+| `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage`, `emit`, `registerChannels`, `ChannelDefinition`, `ChannelMap`, `ChannelRegistryOptions` |
 | `@mauroandre/velojs/client` | `startClient` |
-| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch` |
+| `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch`, `Freshness` |
 | `@mauroandre/velojs/events` | `createEventStream`, `poll`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`, `PerChannelSourceFn`, `ChannelResolver` (also re-exported from root) |
-| `@mauroandre/velojs/testing` | `createTestApp`, `TestApp`, `TestResponse`, `TestSubscription`, `CreateTestAppOptions`, `MockContextOptions` |
+| `@mauroandre/velojs/testing` | `createTestApp`, `TestApp`, `TestResponse`, `TestSubscription`, `TestChannelSubscription`, `ChannelEvent`, `CreateTestAppOptions`, `MockContextOptions` |
 | `@mauroandre/velojs/cookie` | `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie` |
 | `@mauroandre/velojs/factory` | `createMiddleware`, `createFactory` |
 | `@mauroandre/velojs/vite` | `veloPlugin` |
@@ -1460,6 +1875,7 @@ interface Metadata {
 interface RouteModule {
     Component: ComponentType<any>;
     loader?: (args: LoaderArgs) => Promise<any>;
+    channels?: readonly string[];   // live loader: channel names kept fresh
     metadata?: Metadata;
     [key: `action_${string}`]: (args: ActionArgs) => Promise<any>;
 }
@@ -1535,6 +1951,10 @@ export const staticPaths = async () => {
 
 Routes without `staticPaths` are skipped with a warning.
 
+### Live loader in a static build
+
+A module that declares `channels` keeps rendering, but its channels are **inert** there: there is no server to speak SSE, so the client opens no connection, `freshness` stays `"live"` and the build warns, naming the module. Static output has no live data by construction.
+
 ### Deploying
 
 The `dist/` folder is self-contained. Deploy to any static hosting (Nginx, Cloudflare Pages, S3, etc.). No server required.