@mauroandre/velojs 0.0.19 → 0.0.21

package/README.md

@@ -536,57 +536,91 @@ The client-side transform rewrites the import to fetch `/_action/admin/Layout/lo
 
 ## Event Streams
 
-Push real-time updates from server to client via Server-Sent Events (SSE). Useful for live progress, notifications, metrics, log streaming, AI tokens, and any server → client push scenario.
+Push real-time updates from server to client via Server-Sent Events (SSE). Live progress, notifications, metrics, log streaming, AI tokens — anything server → client.
 
-### `stream_*` convention
+Three verbs: `emit`, `close`, `useEventStream`. The framework handles routing, types, listener management, snapshots, lifecycle, reconnection, and cleanup.
 
-Declare a stream alongside `loader` / `action_*` in any page or layout module. The framework registers an SSE route at `/_event/{moduleId}/{name}` automatically:
+### Shortest example
 
 ```typescript
-// app/admin/Deploy.tsx
+// app/admin/Provision.tsx
 import { createEventStream } from "@mauroandre/velojs";
-import { useEventStream, useParams } from "@mauroandre/velojs/hooks";
+import { useEventStream } from "@mauroandre/velojs/hooks";
 
-type DeployState = { step: string; status: "running" | "success" | "error" };
-
-const activeDeploys = new Map<string, DeployState>();
-
-export const stream_progress = createEventStream<DeployState>({
-    channel: (c) => c.req.query("channel") ?? "",
-    snapshot: (channel) => activeDeploys.get(channel ?? ""),
-    closeOn: (s) => s.status === "success" || s.status === "error",
-});
+export const stream_logs = createEventStream<string>();
 
 export const Component = () => {
-    const params = useParams<{ id: string }>();
-    const { data, snapshot, closed } = useEventStream(stream_progress, {
-        channel: params.id,
-    });
-
-    const state = data.value ?? snapshot.value;
-    return <div>{state?.step ?? "waiting..."}</div>;
+    const { snapshot, data, closed } = useEventStream(stream_logs, { channel: sessionId });
+    const lines = [...(snapshot.value ?? []), ...(data.value ? [data.value] : [])];
+    return <pre>{lines.join("\n")}{closed.value && "\n[done]"}</pre>;
 };
 ```
 
-Emit from any service that imports the stream:
+```typescript
+// app/admin/provision.service.ts
+import { stream_logs } from "./Provision.js";
+
+export async function provision(sessionId: string) {
+    try {
+        stream_logs.emit(sessionId, "Connecting...", { snapshot: true });
+        // ... real work
+        stream_logs.emit(sessionId, "Worker ready.", { snapshot: true });
+    } finally {
+        stream_logs.close(sessionId);
+    }
+}
+```
+
+One line to declare, three verbs to use. Route at `/_event/admin/Provision/logs` is registered automatically. Middlewares inherited from parent route nodes.
+
+### Two ways to declare
+
+**Convention `stream_*`** (recommended) — for streams logically tied to a page/layout. Path derived from module ID, middlewares inherited.
 
 ```typescript
-import { stream_progress } from "./Deploy.js";
+export const stream_progress = createEventStream<DeployState>();
+```
+
+**Standalone** — for cross-cutting streams (global metrics, notifications). Pass `path` and (if needed) `middlewares` explicitly. Use `broadcast: true` for streams without channels.
 
-stream_progress.emit("app-123", { step: "building", status: "running" });
+```typescript
+export const containerMetrics = createEventStream<Metric[]>({
+    path: "/api/metrics/containers",
+    broadcast: true,
+    middlewares: [authMiddleware],
+});
 ```
 
-### Standalone streams
+### Three ways to emit
 
-For cross-cutting streams (global metrics, notifications) consumed by many pages, use an explicit `path`:
+**Reactive** — call `emit()` from anywhere when something happens. Most common:
 
 ```typescript
-// app/streams/metrics.ts
-export const metricsStream = createEventStream<Metric[]>({
-    path: "/api/metrics/containers",
+stream_logs.emit(sessionId, "Line", { snapshot: true });
+```
+
+**Source-driven** — pass a `source` function. Framework runs it only while subscribed (zero CPU when nobody is watching):
+
+```typescript
+import { poll } from "@mauroandre/velojs";
+
+export const stream_metrics = createEventStream<Metric[]>({
+    broadcast: true,
+    source: poll({
+        intervalMs: 3000,
+        tick: async (emit) => emit(await collectMetrics()),
+    }),
 });
+```
 
-setInterval(() => metricsStream.emit(collectMetrics()), 2000);
+**Stateful snapshot** — for state-machine patterns where each emit is the complete current state:
+
+```typescript
+const deploys = new Map<string, DeployState>();
+
+export const stream_deploy = createEventStream<DeployState>({
+    snapshot: (id) => deploys.get(id ?? ""),
+});
 ```
 
 ### Configuration
@@ -594,25 +628,50 @@ setInterval(() => metricsStream.emit(collectMetrics()), 2000);
 | Option | Type | Description |
 |--------|------|-------------|
 | `path` | `string` | (Standalone) Explicit URL path |
-| `channel` | `(c: Context) => string` | Extract channel ID from request — subscribers only get matching events |
-| `snapshot` | `(channel) => TSnapshot \| undefined` | Returns current state on connect (and reconnect) |
-| `closeOn` | `(event: TEvent) => boolean` | Closes the SSE connection when matching event is sent |
-| `heartbeatMs` | `number \| false` | Keep-alive heartbeat interval, default `20000` (20s). `false` to disable |
-| `middlewares` | `MiddlewareHandler[]` | (Standalone) Hono middlewares applied to the SSE route |
+| `broadcast` | `boolean` | If true, every emit goes to all subscribers (no channels). Default: false |
+| `channel` | `(c) => string` | Extract channel ID. Default: `?channel=...` query param. Ignored when `broadcast: true` |
+| `snapshot` | `(channel) => TSnapshot` | Returns current state on connect (state-machine pattern) |
+| `closeOn` | `(event) => boolean` | Closes SSE when matching event is sent (declarative) |
+| `source` | `(emit, { abortSignal }) => Promise<void>` | Self-running producer, only runs while subscribed |
+| `retainMs` | `number` | Buffer retention after `close()`. Default `300000` (5 min) |
+| `heartbeatMs` | `number \| false` | Heartbeat interval. Default `20000` (20s). `false` to disable |
+| `middlewares` | `MiddlewareHandler[]` | (Standalone) Hono middlewares for the SSE route |
 
-### Middleware inheritance
+### Snapshot mechanisms
 
-Streams declared with `stream_*` automatically inherit middlewares from parent route nodes — same as pages and actions. A stream under an `AdminLayout` with `authMiddleware` is protected without extra wiring.
+Two snapshot patterns for two cases:
 
-For standalone streams, pass middlewares explicitly:
+**Per-emit `{ snapshot: true }` — append pattern.** Framework keeps a buffer per channel. Late subscribers receive the array.
 
 ```typescript
-export const metricsStream = createEventStream<Metric[]>({
-    path: "/api/metrics",
-    middlewares: [authMiddleware],
-});
+stream_logs.emit(id, "line 1", { snapshot: true });
+stream_logs.emit(id, "line 2", { snapshot: true });
+// Late subscriber → snapshot.value = ["line 1", "line 2"]
 ```
 
+**`snapshot: callback` config — replace pattern.** You return the latest state from your own data structure.
+
+```typescript
+createEventStream({ snapshot: (id) => deploys.get(id ?? "") });
+// Late subscriber → snapshot.value = the latest DeployState
+```
+
+Both survive after `close()` for `retainMs` (default 5 min) so refresh-after-finish still shows final state.
+
+### Closing
+
+Two ways, choose either or both:
+
+```typescript
+// Imperative — call from anywhere
+stream.close(channelId);
+
+// Declarative — predicate on event
+createEventStream({ closeOn: (s) => s.status === "success" });
+```
+
+After close, subsequent `emit()` to that channel is ignored with a warning.
+
 ### `useEventStream` hook
 
 ```typescript
@@ -624,12 +683,20 @@ const { data, snapshot, closed, error } = useEventStream(stream, {
 
 | Signal | Description |
 |--------|-------------|
-| `data` | Latest event received from the server |
-| `snapshot` | Initial state on connect (if `snapshot` is configured) |
-| `closed` | `true` when server closed the stream (`closeOn` matched) |
+| `data` | Latest event received |
+| `snapshot` | Initial state on connect (buffer or callback) |
+| `closed` | `true` when server closed the stream |
 | `error` | Parse or connection error, if any |
 
-The hook handles `EventSource` lifecycle automatically: opens on mount, closes on unmount, re-opens when `channel` changes.
+Lifecycle is automatic: opens on mount, closes on unmount, re-opens fresh when `channel` changes.
+
+### `poll` helper
+
+For interval-based polling sources. Wraps your tick function in a loop that respects the `AbortSignal`. Errors in tick are logged but don't stop the loop.
+
+```typescript
+poll({ intervalMs: 3000, tick: async (emit) => emit(await collect()) })
+```
 
 ---
 
@@ -1076,11 +1143,11 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 
 | Import | Contents |
 |--------|----------|
-| `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`, `EventStream`, `EventStreamConfig`), `Scripts`, `Link`, `createEventStream`, `defineConfig` |
+| `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`), `Scripts`, `Link`, `createEventStream`, `poll`, `defineConfig` |
 | `@mauroandre/velojs/server` | `startServer`, `createApp`, `addRoutes`, `onServer`, `serverDataStorage` |
 | `@mauroandre/velojs/client` | `startClient` |
 | `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch` |
-| `@mauroandre/velojs/events` | `createEventStream`, `EventStream`, `EventStreamConfig` (also re-exported from root) |
+| `@mauroandre/velojs/events` | `createEventStream`, `poll`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn` (also re-exported from root) |
 | `@mauroandre/velojs/cookie` | `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie` |
 | `@mauroandre/velojs/factory` | `createMiddleware`, `createFactory` |
 | `@mauroandre/velojs/vite` | `veloPlugin` |

package/dist/events.d.ts

@@ -1,28 +1,71 @@
 /**
  * VeloJS Event Streams
- * Server-Sent Events (SSE) with snapshot, channels, and auto-close.
+ * Server-Sent Events (SSE) with snapshot, channels, source-driven emission, and auto-close.
  *
- * Two ways to use:
+ * Two ways to declare:
  *
- * 1. Standalone (cross-cutting streams like global metrics):
+ * 1. Convention `stream_*` (per-page or per-layout, route registered automatically):
+ * ```typescript
+ * // app/admin/Deploy.tsx
+ * export const stream_progress = createEventStream<DeployState>();
+ * ```
+ *
+ * 2. Standalone (cross-cutting streams like global metrics):
  * ```typescript
  * export const metricsStream = createEventStream<Metric[]>({
  *     path: "/api/metrics",
+ *     middlewares: [authMiddleware],
  * });
- * metricsStream.emit(currentMetrics);
  * ```
  *
- * 2. Convention `stream_*` (per-page streams, route registered automatically):
+ * Three ways to emit (server-side):
+ *
+ * - Reactive (call from anywhere when something happens):
+ *   `stream.emit(channelId, value, { snapshot: true })`
+ * - Source-driven (framework runs your producer only when subscribed):
+ *   `createEventStream({ source: poll({ intervalMs, tick }) })`
+ * - Stateful snapshot via callback (for state-machine patterns):
+ *   `createEventStream({ snapshot: (channelId) => activeStates.get(channelId) })`
+ */
+import type { Context, Hono, MiddlewareHandler } from "hono";
+/** Function passed to `source` for emitting values. */
+export type EmitFn<TEvent> = {
+    /** Broadcast emit (no channel) */
+    (event: TEvent, options?: EmitOptions): void;
+    /** Channel-targeted emit */
+    (channel: string, event: TEvent, options?: EmitOptions): void;
+};
+/** Options accepted by `emit()` per call. */
+export interface EmitOptions {
+    /**
+     * If true, the value is appended to the stream's internal buffer for that channel.
+     * Late subscribers receive the full buffer as a snapshot on connect.
+     * Default: false (event is broadcast-only, not retained).
+     */
+    snapshot?: boolean;
+}
+/**
+ * A producer function that runs **only when there are active subscribers**.
+ * The framework passes an `AbortSignal` that fires when the last subscriber disconnects.
+ *
+ * Example (event-driven):
  * ```typescript
- * // app/admin/Deploy.tsx
- * export const stream_progress = createEventStream<DeployState>({
- *     channel: (c) => c.req.param("id"),
- *     snapshot: (id) => activeDeploys.get(id),
- *     closeOn: (s) => s.status === "success" || s.status === "error",
- * });
+ * source: async (emit, { abortSignal }) => {
+ *     const handler = (e) => emit(e);
+ *     bus.on("event", handler);
+ *     abortSignal.addEventListener("abort", () => bus.off("event", handler));
+ *     await new Promise(r => abortSignal.addEventListener("abort", r));
+ * }
  * ```
+ *
+ * For polling, use the `poll` helper instead of writing the loop yourself.
+ *
+ * **Anti-pattern**: ignoring `abortSignal` keeps the source running forever (and leaks
+ * resources). Only do this if the producer is meant to run independently of UI.
  */
-import type { Context, Hono, MiddlewareHandler } from "hono";
+export type SourceFn<TEvent> = (emit: EmitFn<TEvent>, ctx: {
+    abortSignal: AbortSignal;
+}) => void | Promise<void>;
 export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
     /**
      * Explicit URL path for the SSE endpoint (standalone usage).
@@ -33,19 +76,37 @@ export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
     /**
      * Channel selector — extracts a channel ID from the request.
      * Subscribers only receive events emitted to their channel.
-     * When omitted, the stream is a broadcast (all subscribers receive all events).
+     * When omitted, defaults to `c.req.query("channel") ?? ""` so client-side
+     * `useEventStream(stream, { channel })` works out of the box.
+     *
+     * Ignored when `broadcast: true` is set.
      */
     channel?: (c: Context) => string;
+    /**
+     * If true, this stream has no channels — every emit goes to all subscribers.
+     * - `emit(value, options?)` (no channel arg)
+     * - `useEventStream(stream)` (no channel option)
+     * - Server uses a single broadcast bucket regardless of `?channel=` query.
+     *
+     * Default: false (channel-aware — `emit(channel, value, options?)`).
+     */
+    broadcast?: boolean;
     /**
      * Returns the current state of a channel for snapshot-on-connect.
      * Sent before any new events to bring the client up to date.
-     * Must remain available even after the stream "closes" — clients reconnecting
-     * after a terminal event still need to see the final state.
+     *
+     * Use this for **state-machine patterns** where each emit is a complete state
+     * (deploy progress, migration status). The callback returns the latest state.
+     *
+     * For **append-only patterns** (logs, tokens), prefer `emit(..., { snapshot: true })`
+     * which uses an internal buffer managed by the framework.
      */
     snapshot?: (channel: string | undefined) => TSnapshot | undefined | Promise<TSnapshot | undefined>;
     /**
      * Returns true when an event marks the end of the stream for that channel.
      * The server closes the SSE connection after sending such an event.
+     *
+     * For imperative close from anywhere, use `stream.close(channel)` instead.
      */
     closeOn?: (event: TEvent) => boolean;
     /**
@@ -60,32 +121,78 @@ export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
      * parent route nodes automatically.
      */
     middlewares?: MiddlewareHandler[];
+    /**
+     * Self-running producer that emits values into the stream.
+     * The framework only invokes `source` while there are active subscribers.
+     * When the last subscriber disconnects, the AbortSignal fires.
+     *
+     * Use the `poll` helper for the common interval-based pattern.
+     */
+    source?: SourceFn<TEvent>;
+    /**
+     * Time (ms) the per-channel snapshot buffer is retained after `close()`.
+     * Reconnecting clients within this window still see the final state.
+     * Default: 5 * 60 * 1000 (5 minutes).
+     */
+    retainMs?: number;
 }
 export interface EventStream<TEvent, TSnapshot = TEvent> {
-    /** Broadcast emit (no channel) */
-    emit(event: TEvent): void;
-    /** Channel-targeted emit */
-    emit(channel: string, event: TEvent): void;
+    /**
+     * Emit an event.
+     * - For channel-aware streams (default): `emit(channel, value, options?)`
+     * - For broadcast streams (`config.broadcast: true`): `emit(value, options?)`
+     */
+    emit(event: TEvent, options?: EmitOptions): void;
+    emit(channel: string, event: TEvent, options?: EmitOptions): void;
+    /**
+     * Closes the stream (or a specific channel).
+     * - Notifies current subscribers so their `useEventStream().closed` becomes true.
+     * - Schedules cleanup of the per-channel buffer after `retainMs`.
+     * - Idempotent: calling close on an already-closed channel is a no-op.
+     */
+    close(channel?: string): void;
     /** Internal: marker for runtime detection */
     readonly __isVeloEventStream: true;
     /** Internal: configuration */
     readonly __config: EventStreamConfig<TEvent, TSnapshot>;
     /** Internal: registered listeners by channel ("" for broadcast) */
-    readonly __listeners: Map<string, Set<(event: TEvent) => void>>;
+    readonly __listeners: Map<string, Set<StreamListener<TEvent>>>;
+    /** Internal: per-channel buffer for { snapshot: true } emits */
+    readonly __buffers: Map<string, TEvent[]>;
     /** Internal: assigned URL path (set by standalone or by stream_* discovery) */
     __path: string | undefined;
+    /** Internal: source lifecycle hook */
+    __onConnect(channelKey: string, listener: StreamListener<TEvent>): void;
+    /** Internal: source lifecycle hook */
+    __onDisconnect(channelKey: string, listener: StreamListener<TEvent>): void;
+}
+/** Internal listener — receives events and a close signal. */
+interface StreamListener<TEvent> {
+    (event: TEvent): void;
+    close(): void;
 }
-/**
- * Returns and clears the queue of pending standalone streams.
- * Called by createApp to register their routes.
- */
 export declare function flushPendingStreamRoutes(app: Hono): void;
+export declare function createEventStream<TEvent, TSnapshot = TEvent>(config?: EventStreamConfig<TEvent, TSnapshot>): EventStream<TEvent, TSnapshot>;
 /**
- * Creates a typed event stream with optional channel, snapshot, and close-on-event.
+ * Creates a `source` function that runs `tick` every `intervalMs` while subscribed.
+ * The tick function is wrapped in try/catch — errors are logged but don't stop the loop.
+ *
+ * ```typescript
+ * export const stream_metrics = createEventStream<Metric[]>({
+ *     source: poll({
+ *         intervalMs: 3000,
+ *         tick: async (emit) => emit(await collectMetrics()),
+ *     }),
+ * });
+ * ```
  */
-export declare function createEventStream<TEvent, TSnapshot = TEvent>(config?: EventStreamConfig<TEvent, TSnapshot>): EventStream<TEvent, TSnapshot>;
+export declare function poll<TEvent>(opts: {
+    intervalMs: number;
+    tick: (emit: EmitFn<TEvent>) => void | Promise<void>;
+}): SourceFn<TEvent>;
 /**
  * Registers a GET SSE route for the given stream at the given path.
  * Used both by standalone streams and by stream_* discovery.
  */
 export declare function registerStreamHandler<TEvent, TSnapshot>(app: Hono, path: string, stream: EventStream<TEvent, TSnapshot>, middlewares?: Array<(c: Context, next: () => Promise<void>) => any>): void;
+export {};

package/dist/events.js

@@ -1,62 +1,140 @@
-const A = [];
-function w(t) {
-  for (const s of A) s(t);
-  A.length = 0;
+const T = [];
+function m(t) {
+  for (const r of T) r(t);
+  T.length = 0;
 }
 function N(t = {}) {
-  const s = /* @__PURE__ */ new Map();
-  function e(a, f) {
-    let l, n;
-    arguments.length === 1 ? (l = "", n = a) : (l = a, n = f);
-    const c = s.get(l);
+  t.broadcast && t.channel && console.warn(
+    "[velojs] createEventStream: `broadcast: true` ignores `channel`. Remove one of them — broadcast streams have no channels."
+  );
+  const r = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Set(), u = /* @__PURE__ */ new Map();
+  let f = null, A = 0;
+  const d = () => {
+    t.source && (f || (f = new AbortController(), Promise.resolve(
+      t.source(E, { abortSignal: f.signal })
+    ).catch((e) => {
+      console.error("[velojs] event stream source threw:", e);
+    })));
+  }, w = () => {
+    A > 0 || f && (f.abort(), f = null);
+  };
+  function E(e, c, n) {
+    let s, l, h;
+    if (!!t.broadcast ? (s = "", l = e, h = c) : (s = e, l = c, h = n), a.has(s)) {
+      console.warn(
+        `[velojs] emit() called on closed channel "${s}" — ignored. Reopen the channel by emitting to a fresh ID, or remove the close() call.`
+      );
+      return;
+    }
+    if (h?.snapshot) {
+      const b = o.get(s) ?? [];
+      b.push(l), o.set(s, b);
+    }
+    const v = r.get(s);
+    if (v)
+      for (const b of v) b(l);
+  }
+  function i(e = "") {
+    if (a.has(e)) return;
+    a.add(e);
+    const c = r.get(e);
     if (c)
-      for (const h of c) h(n);
+      for (const l of c) l.close();
+    const n = t.retainMs ?? 3e5, s = u.get(e);
+    s && clearTimeout(s), u.set(
+      e,
+      setTimeout(() => {
+        o.delete(e), u.delete(e), a.delete(e);
+      }, n)
+    );
   }
-  const r = {
-    emit: e,
+  const S = {
+    emit: E,
+    close: i,
     __isVeloEventStream: !0,
     __config: t,
-    __listeners: s,
-    __path: t.path
+    __listeners: r,
+    __buffers: o,
+    __path: t.path,
+    __onConnect(e, c) {
+      let n = r.get(e);
+      n || (n = /* @__PURE__ */ new Set(), r.set(e, n)), n.add(c), A++, d();
+    },
+    __onDisconnect(e, c) {
+      const n = r.get(e);
+      n && (n.delete(c), n.size === 0 && r.delete(e), A--, w());
+    }
   };
-  return t.path && A.push((a) => {
-    p(a, t.path, r, t.middlewares ?? []);
-  }), r;
+  return t.path && T.push((e) => {
+    g(e, t.path, S, t.middlewares ?? []);
+  }), S;
 }
-function p(t, s, e, r = []) {
-  const a = async (f) => {
-    const { streamSSE: l } = await import("hono/streaming"), n = e.__config.channel ? e.__config.channel(f) : "", c = e.__config.heartbeatMs, h = c === !1 ? 0 : c ?? 2e4;
-    return l(f, async (_) => {
-      if (e.__config.snapshot) {
-        const o = await e.__config.snapshot(
-          n === "" ? void 0 : n
+function C(t) {
+  return async (r, { abortSignal: o }) => {
+    for (; !o.aborted; ) {
+      try {
+        await t.tick(r);
+      } catch (a) {
+        console.error("[velojs] poll tick threw:", a);
+      }
+      await new Promise((a) => {
+        const u = setTimeout(a, t.intervalMs);
+        o.addEventListener(
+          "abort",
+          () => {
+            clearTimeout(u), a();
+          },
+          { once: !0 }
         );
-        o !== void 0 && await _.writeSSE({
+      });
+    }
+  };
+}
+function p(t) {
+  return t.req.query("channel") ?? "";
+}
+function g(t, r, o, a = []) {
+  const u = async (f) => {
+    const { streamSSE: A } = await import("hono/streaming"), d = o.__config.broadcast ? "" : (o.__config.channel ?? p)(f), w = o.__config.heartbeatMs, E = w === !1 ? 0 : w ?? 2e4;
+    return A(f, async (i) => {
+      const S = o.__buffers.get(d);
+      if (S && S.length > 0 && await i.writeSSE({
+        event: "snapshot",
+        data: JSON.stringify(S)
+      }), o.__config.snapshot) {
+        const _ = await o.__config.snapshot(
+          d === "" ? void 0 : d
+        );
+        _ !== void 0 && await i.writeSSE({
           event: "snapshot",
-          data: JSON.stringify(o)
+          data: JSON.stringify(_)
         });
       }
-      let E;
-      const T = new Promise((o) => {
-        E = o;
+      let e;
+      const c = new Promise((_) => {
+        e = _;
+      });
+      let n = !1, s = null;
+      const l = () => {
+        n || (n = !0, s && clearInterval(s), o.__onDisconnect(d, h), e());
+      }, h = ((_) => {
+        n || (i.writeSSE({ data: JSON.stringify(_) }).catch(() => {
+        }), o.__config.closeOn?.(_) && (i.close(), l()));
       });
-      let S = !1, u = null, i;
-      const d = () => {
-        S || (S = !0, u && clearInterval(u), i?.delete(g), i?.size === 0 && e.__listeners.delete(n), E());
-      }, g = (o) => {
-        S || (_.writeSSE({ data: JSON.stringify(o) }).catch(() => {
-        }), e.__config.closeOn?.(o) && (_.close(), d()));
-      };
-      i = e.__listeners.get(n), i || (i = /* @__PURE__ */ new Set(), e.__listeners.set(n, i)), i.add(g), u = h > 0 ? setInterval(() => {
-        S || _.writeSSE({ event: "heartbeat", data: "" }).catch(() => {
+      h.close = () => {
+        n || (i.writeSSE({ event: "close", data: "" }).catch(() => {
+        }), i.close(), l());
+      }, o.__onConnect(d, h), s = E > 0 ? setInterval(() => {
+        n || i.writeSSE({ event: "heartbeat", data: "" }).catch(() => {
         });
-      }, h) : null, _.onAbort(d), await T;
+      }, E) : null, i.onAbort(l), await c;
     });
   };
-  r.length > 0 ? t.on(["GET"], [s], ...r, a) : t.on(["GET"], [s], a);
+  a.length > 0 ? t.on(["GET"], [r], ...a, u) : t.on(["GET"], [r], u);
 }
 export {
   N as createEventStream,
-  w as flushPendingStreamRoutes,
-  p as registerStreamHandler
+  m as flushPendingStreamRoutes,
+  C as poll,
+  g as registerStreamHandler
 };

package/dist/hooks.js

@@ -13,42 +13,42 @@ function m(e) {
         return e ? globalThis.__veloServerData?.getStore?.()?.[e] ?? null : null;
       }
     }, loading: o };
-  const t = window.__PAGE_DATA__, n = e && t?.[e] ? t[e] : null;
-  return { data: v(n), loading: o };
+  const t = window.__PAGE_DATA__, r = e && t?.[e] ? t[e] : null;
+  return { data: v(r), loading: o };
 }
 function A(e, o) {
-  let t, n;
-  Array.isArray(e) ? n = e : (t = e, n = o);
-  let r = null;
+  let t, r;
+  Array.isArray(e) ? r = e : (t = e, r = o);
+  let n = null;
   if (typeof window > "u" && t) {
-    const l = globalThis.__veloServerData?.getStore?.();
-    l?.[t] && (r = l[t]);
+    const i = globalThis.__veloServerData?.getStore?.();
+    i?.[t] && (n = i[t]);
   }
   if (typeof window < "u" && t) {
     const a = window.__PAGE_DATA__;
-    a?.[t] && (r = a[t], delete a[t]);
+    a?.[t] && (n = a[t], delete a[t]);
   }
-  const u = c(r), s = c(!1), _ = () => {
+  const u = c(n), s = c(!1), _ = () => {
     if (typeof window > "u" || !t) return;
     const a = window.location.pathname;
     s.value = !0;
     const f = typeof __VELO_STATIC__ < "u" && __VELO_STATIC__ ? `${a === "/" ? "" : a}/index.json` : (() => {
-      const i = new URLSearchParams(window.location.search);
-      return i.set("_data", "1"), `${a}?${i.toString()}`;
+      const l = new URLSearchParams(window.location.search);
+      return l.set("_data", "1"), `${a}?${l.toString()}`;
     })();
-    fetch(f, { cache: "no-cache" }).then((i) => i.json()).then((i) => {
-      typeof __VELO_BUILD_HASH__ < "u" && i.__buildHash && i.__buildHash !== __VELO_BUILD_HASH__ && (S.value = !0), u.value = i[t], s.value = !1;
+    fetch(f, { cache: "no-cache" }).then((l) => l.json()).then((l) => {
+      typeof __VELO_BUILD_HASH__ < "u" && l.__buildHash && l.__buildHash !== __VELO_BUILD_HASH__ && (S.value = !0), u.value = l[t], s.value = !1;
     }).catch(() => {
       s.value = !1;
     });
-  }, d = p(r !== null);
+  }, d = p(n !== null);
   return h(() => {
     if (d.current) {
       d.current = !1;
       return;
     }
     _();
-  }, n ?? []), { data: u, loading: s, refetch: _ };
+  }, r ?? []), { data: u, loading: s, refetch: _ };
 }
 function P() {
   const [, e] = w();
@@ -64,42 +64,44 @@ function b() {
   if (e?.__query)
     return e.__query;
   const o = new URLSearchParams(window.location.search), t = {};
-  return o.forEach((n, r) => {
-    t[r] = n;
+  return o.forEach((r, n) => {
+    t[n] = r;
   }), t;
 }
 function H() {
   return typeof window > "u" ? globalThis.__veloServerData?.getStore?.()?.__pathname ?? "/" : (w(), window.location.pathname);
 }
 function U(e, o = {}) {
-  const t = c(null), n = c(null), r = c(!1), u = c(null), { channel: s, enabled: _ = !0 } = o;
+  const t = c(null), r = c(null), n = c(!1), u = c(null), { channel: s, enabled: _ = !0 } = o;
   return h(() => {
     if (typeof window > "u" || !_) return;
     if (!e.__path) {
       console.warn("[velojs] useEventStream: stream has no __path");
       return;
     }
-    t.value = null, n.value = null, r.value = !1, u.value = null;
+    t.value = null, r.value = null, n.value = !1, u.value = null;
     const d = s ? `${e.__path}?channel=${encodeURIComponent(s)}` : e.__path, a = new EventSource(d);
-    return a.addEventListener("snapshot", (l) => {
+    return a.addEventListener("snapshot", (i) => {
       try {
-        n.value = JSON.parse(l.data);
+        r.value = JSON.parse(i.data);
       } catch (f) {
         u.value = f;
       }
-    }), a.addEventListener("message", (l) => {
+    }), a.addEventListener("message", (i) => {
       try {
-        t.value = JSON.parse(l.data);
+        t.value = JSON.parse(i.data);
       } catch (f) {
         u.value = f;
       }
     }), a.addEventListener("heartbeat", () => {
+    }), a.addEventListener("close", () => {
+      n.value = !0, a.close();
     }), a.addEventListener("error", () => {
-      a.readyState === EventSource.CLOSED && (r.value = !0);
+      a.readyState === EventSource.CLOSED && (n.value = !0);
     }), () => {
       a.close();
     };
-  }, [e, s, _]), { data: t, snapshot: n, closed: r, error: u };
+  }, [e, s, _]), { data: t, snapshot: r, closed: n, error: u };
 }
 export {
   m as Loader,

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export type { AppRoutes, RouteNode, RouteModule, LoaderArgs, ActionArgs, Metadat
 export type { VeloConfig } from "./config.js";
 export { defineConfig } from "./config.js";
 export { Scripts, Link } from "./components.js";
-export { createEventStream } from "./events.js";
-export type { EventStream, EventStreamConfig } from "./events.js";
+export { createEventStream, poll } from "./events.js";
+export type { EventStream, EventStreamConfig, EmitFn, EmitOptions, SourceFn, } from "./events.js";
 export type { Context, MiddlewareHandler, Next } from "hono";

package/dist/index.js

@@ -1,9 +1,10 @@
 import { defineConfig as o } from "./config.js";
-import { Link as f, Scripts as i } from "./components.js";
-import { createEventStream as n } from "./events.js";
+import { Link as f, Scripts as p } from "./components.js";
+import { createEventStream as m, poll as n } from "./events.js";
 export {
   f as Link,
-  i as Scripts,
-  n as createEventStream,
-  o as defineConfig
+  p as Scripts,
+  m as createEventStream,
+  o as defineConfig,
+  n as poll
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mauroandre/velojs",
-    "version": "0.0.19",
+    "version": "0.0.21",
     "type": "module",
     "description": "Fullstack web framework built on Hono + Preact with Vite-powered AST transforms",
     "keywords": [