@mauroandre/velojs 0.0.55 → 0.0.57

package/dist/testing/subscription.d.ts

@@ -2,10 +2,26 @@
  * SSE subscription helper — parses the SSE protocol from a streaming Response
  * and exposes assertion-friendly methods for tests.
  */
-import type { TestSubscription } from "./types.js";
+import type { TestSubscription, NextOptions, ChannelEvent } from "./types.js";
 interface BuildSubscriptionOptions {
     response: Response;
     parseJson?: boolean;
+    /**
+     * Deliver `snapshot` events through `events`/`next()` too, not only via the
+     * `snapshot` getter. The live loader has no `message` events at all — every
+     * update is a snapshot — so its subscription reads them as plain events.
+     */
+    snapshotEvents?: boolean;
+    /**
+     * Live-loader mode: `slice` events travel through `events`/`next()` like the
+     * snapshots (the payload exactly as it went on the wire), and every arrival
+     * is recorded discriminated in `nextEvent()` — `{ type: "snapshot" |
+     * "slice", data }`. `next()` keeps the slice-1 contract: the raw `data`.
+     */
+    channelEvents?: boolean;
 }
-export declare function buildSubscription<TEvent, TSnapshot>(opts: BuildSubscriptionOptions): Promise<TestSubscription<TEvent, TSnapshot>>;
+export declare function buildSubscription<TEvent, TSnapshot>(opts: BuildSubscriptionOptions): Promise<TestSubscription<TEvent, TSnapshot> & {
+    /** Next arrival discriminated by the mode that delivered it. */
+    nextEvent(opts: NextOptions): Promise<ChannelEvent<TEvent>>;
+}>;
 export {};

package/dist/testing/types.d.ts

@@ -5,6 +5,7 @@ import type { Hono, Context } from "hono";
 import type { AppRoutes } from "../types.js";
 import type { EventStream } from "../events.js";
 import type { SocketHandler, SocketStub } from "../sockets.js";
+import type { ChannelMap, ChannelRegistryOptions } from "../channels.js";
 export type Cookies = Record<string, string>;
 export type Headers = Record<string, string>;
 export type Query = Record<string, string | string[]>;
@@ -28,6 +29,20 @@ export interface CreateTestAppOptions {
     getSessionCookie?: (input: {
         user: any;
     }) => Promise<Cookies> | Cookies;
+    /**
+     * The app's live-loader channel map — the same object `app/channels.ts`
+     * exports. Registered before the app is created, so the channel routes and
+     * `emit()` can resolve partitions. May also be registered from `bootstrap`
+     * via `registerChannels()`.
+     */
+    channels?: ChannelMap;
+    /**
+     * Options of the channel registration: the coalescing window of the
+     * invalidation mode and the emit log. `createTestApp` registers with
+     * `coalesceMs: 0` (immediate, deterministic) unless this option says
+     * otherwise; `logEmits` defaults to on, as in production.
+     */
+    channelOptions?: ChannelRegistryOptions;
     /**
      * Serve the app over real TCP on this port, in addition to the in-memory
      * API. Needed when an actor outside this process must reach the app over
@@ -80,6 +95,18 @@ export interface SubscribeOptions extends RequestOptions {
     /** Channel ID — sent as `?channel=...`. */
     channel?: string;
 }
+/**
+ * Options of a live-loader channel connection.
+ *
+ * `params` are the route params the connection declares — the same ones the
+ * browser extracts from the URL and sends in `?_route=`. The server-side
+ * validation of the declared path runs for real: a key the module's path does
+ * not declare rejects the subscription (400), never silently ignores the input.
+ */
+export interface ChannelSubscribeOptions extends SubscribeOptions {
+    /** Route params the connection declares (serialized into `?_route=`). */
+    params?: Params;
+}
 export interface NextOptions {
     /** Reject if no event arrives within this many ms. */
     timeoutMs: number;
@@ -124,6 +151,35 @@ export interface TestSubscription<TEvent = any, TSnapshot = any> {
     /** Force disconnect. Triggers per-channel source abortSignal server-side. */
     close(): Promise<void>;
 }
+/**
+ * A live-loader channel subscription. Every update — the snapshot on connect,
+ * each emit's snapshot and each slice — arrives through `next()` as the `data`
+ * exactly as it went on the wire (a whole snapshot or a raw slice), so `await
+ * next({ timeoutMs })` is the clock: no sleep, no retry, no timing assertion.
+ *
+ * `nextEvent()` is the same arrival stream discriminated as
+ * `{ type: "snapshot" | "slice", data }` — use it when the test cares which
+ * mode delivered the update. `next()` and `nextEvent()` each advance their own
+ * cursor over the same arrivals, so use one or the other within a test.
+ *
+ * The connection only exists after the connect snapshot: await the first
+ * `next()` before emitting, and the server is guaranteed to have registered it.
+ */
+export interface TestChannelSubscription<T = any> extends TestSubscription<T, T> {
+    /** Next arrival, discriminated by the mode that delivered it. */
+    nextEvent(opts: NextOptions): Promise<ChannelEvent<T>>;
+}
+/** One channel arrival: a whole snapshot or a slice to be merged. */
+export interface ChannelEvent<T = any> {
+    type: "snapshot" | "slice";
+    data: T;
+}
+/** The module (or moduleId) a channel belongs to, as `app.channel()` accepts it. */
+export type ChannelModuleRef = string | {
+    metadata?: {
+        moduleId?: string;
+    } | undefined;
+};
 export interface MockContextOptions {
     user?: any;
     params?: Params;
@@ -168,6 +224,35 @@ export interface TestApp {
      */
     loader<T = any>(fn: Function | string, opts?: LoaderRequestOptions): Promise<T | TestResponse>;
     subscribe<TEvent = any, TSnapshot = any>(stream: EventStream<TEvent, TSnapshot> | string, opts?: SubscribeOptions): Promise<TestSubscription<TEvent, TSnapshot>>;
+    /**
+     * Open a live-loader channel connection for a module's declared channel.
+     *
+     * The module may be the imported route module (its `metadata.moduleId` is
+     * read) or a moduleId string. Cookies (and therefore the principal) come
+     * from the options or from `app.as(user)`; the route node's middlewares run
+     * for real, so an unauthenticated subscription is denied exactly as in
+     * production. `params` are the route params the connection declares — the
+     * server validates their keys against the module's path.
+     *
+     * ```ts
+     * const sub = await app.as({ id: 7 }).channel(Expenses, "teamExpenses");
+     * await sub.next({ timeoutMs: 1000 });        // snapshot on connect
+     * await emit("teamExpenses", { user: { teamId: 7 } });
+     * expect(await sub.next({ timeoutMs: 1000 })).toEqual({ teamTotal: 2 });
+     *
+     * // A route with `:params`: the connection declares them and the loader
+     * // re-executes with them.
+     * const project = await app.channel(Project, "projectFiles", { params: { id: "7" } });
+     *
+     * // The same arrivals discriminated: nextEvent() tells a snapshot from a slice.
+     * await emit(Expenses, "teamExpenses", { user: { teamId: 7 } }, { teamTotal: 880 });
+     * expect(await sub.nextEvent({ timeoutMs: 1000 })).toEqual({
+     *     type: "slice",
+     *     data: { teamTotal: 880 },
+     * });
+     * ```
+     */
+    channel<T = any>(module: ChannelModuleRef, name: string, opts?: ChannelSubscribeOptions): Promise<TestChannelSubscription<T>>;
     /**
      * Open an in-memory session against a `socket_*` handler.
      *

package/dist/types.d.ts

@@ -20,6 +20,15 @@ export interface Metadata {
 export interface RouteModule {
     Component: ComponentType<any>;
     loader?: (args: LoaderArgs) => Promise<any>;
+    /**
+     * Channel names whose state must keep this module's loader data faithful.
+     * The opt-in for the live loader: with `channels`, the framework derives an
+     * internal SSE route per channel (`/_channel/{moduleId}/{channel}`) and the
+     * client opens one connection per (module, channel) after hydration. A
+     * module that declares `channels` without a `loader` is an explicit
+     * dev/build error. Requires an entry per name in `app/channels.ts`.
+     */
+    channels?: readonly string[];
     staticPaths?: () => Promise<Record<string, string>[]>;
     metadata?: Metadata;
     [key: `action_${string}`]: (args: ActionArgs<any>) => Promise<any>;

package/dist/vite.d.ts

@@ -66,6 +66,21 @@ export declare function buildFullPathMap(code: string): Map<string, PathInfo>;
  * Percorre recursivamente a árvore de rotas e coleta moduleName → { fullPath, path }
  */
 export declare function collectFullPaths(elements: (t.Expression | t.SpreadElement | null)[], parentPath: string, result: Map<string, PathInfo>): void;
+/**
+ * Names declared by a module's `channels` export — `null` when the module does
+ * not declare the convention (no `channels` array export at all).
+ *
+ * Only the array form is a channel declaration: `app/channels.ts` also exports
+ * a `channels` binding, but an object (the name → resolver map), and must never
+ * be read as a module declaring channels.
+ */
+export declare function declaredChannelNames(code: string): string[] | null;
+/**
+ * Channel names declared in the app's channel map file (`app/channels.ts`) —
+ * the canonical list the framework validates module declarations against.
+ * A missing file yields an empty set, which makes every declaration unknown.
+ */
+export declare function readChannelMapNames(file: string): Set<string>;
 /**
  * @hono/vite-dev-server treats `exclude` as all-or-nothing: passing one
  * replaces the defaults entirely. We compose instead — the upstream defaults