@mauroandre/velojs 0.0.20 → 0.0.22

package/README.md

@@ -581,11 +581,12 @@ One line to declare, three verbs to use. Route at `/_event/admin/Provision/logs`
 export const stream_progress = createEventStream<DeployState>();
 ```
 
-**Standalone** — for cross-cutting streams (global metrics, notifications). Pass `path` and (if needed) `middlewares` explicitly.
+**Standalone** — for cross-cutting streams (global metrics, notifications). Pass `path` and (if needed) `middlewares` explicitly. Use `broadcast: true` for streams without channels.
 
 ```typescript
 export const containerMetrics = createEventStream<Metric[]>({
     path: "/api/metrics/containers",
+    broadcast: true,
     middlewares: [authMiddleware],
 });
 ```
@@ -604,6 +605,7 @@ stream_logs.emit(sessionId, "Line", { snapshot: true });
 import { poll } from "@mauroandre/velojs";
 
 export const stream_metrics = createEventStream<Metric[]>({
+    broadcast: true,
     source: poll({
         intervalMs: 3000,
         tick: async (emit) => emit(await collectMetrics()),
@@ -626,10 +628,13 @@ export const stream_deploy = createEventStream<DeployState>({
 | Option | Type | Description |
 |--------|------|-------------|
 | `path` | `string` | (Standalone) Explicit URL path |
-| `channel` | `(c) => string` | Extract channel ID. Default: `?channel=...` query param |
+| `broadcast` | `boolean` | If true, every emit goes to all subscribers (no channels). Default: false |
+| `channel` | `(c) => string \| null \| Promise<...>` | Resolve channel ID. Sync or async. Return `null`/`undefined` to reject (403). Default: `?channel=...` |
 | `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 |
+| `source` | `(emit, { abortSignal }) => Promise<void>` | Stream-wide producer, only runs while subscribed |
+| `perChannelSource` | `(channelKey, emit, { abortSignal }) => Promise<void>` | Per-channel producer. Mutually exclusive with `source` |
+| `bufferSize` | `number` | Max entries kept in snapshot buffer per channel (FIFO). Default `Infinity` |
 | `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 |
@@ -695,6 +700,53 @@ For interval-based polling sources. Wraps your tick function in a loop that resp
 poll({ intervalMs: 3000, tick: async (emit) => emit(await collect()) })
 ```
 
+### Per-channel sources
+
+Use `perChannelSource` for resources that scale per channel (SSH connections, DB cursors, pub/sub topics). Invoked once per channel on first subscriber, aborted when the last subscriber of that channel leaves.
+
+```typescript
+export const stream_logs = createEventStream<string>({
+    channel: (c) => `${c.req.param("worker")}:${c.req.param("container")}`,
+    bufferSize: 500,
+    perChannelSource: async (key, emit, { abortSignal }) => {
+        const conn = await ssh.connect(...);
+        const stream = conn.exec(`podman logs -f ${key.split(":")[1]}`);
+        stream.on("data", (d) => emit(d.toString(), { snapshot: true }));
+        abortSignal.addEventListener("abort", () => { stream.close(); conn.end(); });
+    },
+});
+```
+
+Mutually exclusive with `source`.
+
+### Async channel resolver (auth + ownership)
+
+The `channel` resolver can be async and reject the connection by returning `null`/`undefined`:
+
+```typescript
+createEventStream({
+    channel: async (c) => {
+        const user = c.get("user");
+        const appId = c.req.query("channel");
+        const app = await getApp({ id: appId });
+        if (app?.owner !== user.id) return null; // → 403
+        return appId;
+    },
+});
+```
+
+Combines auth and channel extraction in one place.
+
+### Buffer size limits
+
+Cap memory usage of long-running log streams via FIFO ring:
+
+```typescript
+createEventStream<string>({ bufferSize: 500 });  // keep last 500 entries per channel
+```
+
+Only affects emits with `{ snapshot: true }`.
+
 ---
 
 ## Hooks
@@ -1140,11 +1192,11 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 
 | Import | Contents |
 |--------|----------|
-| `@mauroandre/velojs` | Types (`AppRoutes`, `ActionArgs`, `LoaderArgs`, `Metadata`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`), `Scripts`, `Link`, `createEventStream`, `poll`, `defineConfig` |
+| `@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/client` | `startClient` |
 | `@mauroandre/velojs/hooks` | `Loader`, `useLoader`, `useEventStream`, `useParams`, `useQuery`, `useNavigate`, `usePathname`, `touch` |
-| `@mauroandre/velojs/events` | `createEventStream`, `poll`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn` (also re-exported from root) |
+| `@mauroandre/velojs/events` | `createEventStream`, `poll`, `EventStream`, `EventStreamConfig`, `EmitFn`, `EmitOptions`, `SourceFn`, `PerChannelSourceFn`, `ChannelResolver` (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

@@ -66,6 +66,36 @@ export interface EmitOptions {
 export type SourceFn<TEvent> = (emit: EmitFn<TEvent>, ctx: {
     abortSignal: AbortSignal;
 }) => void | Promise<void>;
+/**
+ * A per-channel producer function. Invoked when the **first** subscriber connects
+ * to a specific channel. Aborted when the **last** subscriber of that channel disconnects.
+ *
+ * The provided `emit` function is bound to the current channel — call it with just
+ * the event value (no need to pass the channel ID again).
+ *
+ * Example (per-channel SSH log stream):
+ * ```typescript
+ * perChannelSource: async (channelKey, emit, { abortSignal }) => {
+ *     const conn = await ssh.connect(...);
+ *     const stream = conn.exec(`podman logs -f ${channelKey}`);
+ *     stream.on("data", (d) => emit(d.toString(), { snapshot: true }));
+ *     abortSignal.addEventListener("abort", () => { stream.close(); conn.end(); });
+ * }
+ * ```
+ *
+ * Use this for resources that are **per-channel and expensive** (SSH connections,
+ * DB cursors, external pub/sub subscriptions). Mutually exclusive with `source`.
+ */
+export type PerChannelSourceFn<TEvent> = (channelKey: string, emit: (event: TEvent, options?: EmitOptions) => void, ctx: {
+    abortSignal: AbortSignal;
+}) => void | Promise<void>;
+/**
+ * Async-capable channel resolver. Returns a channel ID, or `null`/`undefined`
+ * to reject the connection (framework responds 403).
+ *
+ * Useful for combining channel extraction with authorization in one place.
+ */
+export type ChannelResolver = (c: Context) => string | null | undefined | Promise<string | null | undefined>;
 export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
     /**
      * Explicit URL path for the SSE endpoint (standalone usage).
@@ -78,8 +108,22 @@ export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
      * Subscribers only receive events emitted to their channel.
      * When omitted, defaults to `c.req.query("channel") ?? ""` so client-side
      * `useEventStream(stream, { channel })` works out of the box.
+     *
+     * Can be **async** — return a Promise to perform DB lookups, auth checks, etc.
+     * Return `null` or `undefined` to reject the connection (framework responds 403).
+     *
+     * Ignored when `broadcast: true` is set.
      */
-    channel?: (c: Context) => string;
+    channel?: ChannelResolver;
+    /**
+     * 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.
@@ -116,19 +160,45 @@ export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
      * When the last subscriber disconnects, the AbortSignal fires.
      *
      * Use the `poll` helper for the common interval-based pattern.
+     *
+     * Mutually exclusive with `perChannelSource`.
      */
     source?: SourceFn<TEvent>;
+    /**
+     * Per-channel producer. Invoked when the **first** subscriber of a channel connects.
+     * Aborted when the **last** subscriber of that channel disconnects.
+     *
+     * Use this for resources that scale per channel (SSH connections, DB cursors,
+     * external pub/sub subscriptions). The `emit` provided is bound to the current
+     * channel — call it with just the value.
+     *
+     * Mutually exclusive with `source`.
+     */
+    perChannelSource?: PerChannelSourceFn<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;
+    /**
+     * Maximum number of events kept in the per-channel snapshot buffer
+     * (only applies to `emit(..., { snapshot: true })`).
+     *
+     * When the buffer reaches this size, the oldest entries are dropped (FIFO ring).
+     * Use this to prevent memory growth in long-running log streams.
+     *
+     * Default: `Infinity` (no limit, current behavior).
+     */
+    bufferSize?: number;
 }
 export interface EventStream<TEvent, TSnapshot = TEvent> {
-    /** Broadcast emit (no channel) */
+    /**
+     * 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;
-    /** Channel-targeted emit */
     emit(channel: string, event: TEvent, options?: EmitOptions): void;
     /**
      * Closes the stream (or a specific channel).

package/dist/events.js

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

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export type { VeloConfig } from "./config.js";
 export { defineConfig } from "./config.js";
 export { Scripts, Link } from "./components.js";
 export { createEventStream, poll } from "./events.js";
-export type { EventStream, EventStreamConfig, EmitFn, EmitOptions, SourceFn, } from "./events.js";
+export type { EventStream, EventStreamConfig, EmitFn, EmitOptions, SourceFn, PerChannelSourceFn, ChannelResolver, } from "./events.js";
 export type { Context, MiddlewareHandler, Next } from "hono";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mauroandre/velojs",
-    "version": "0.0.20",
+    "version": "0.0.22",
     "type": "module",
     "description": "Fullstack web framework built on Hono + Preact with Vite-powered AST transforms",
     "keywords": [
@@ -30,7 +30,7 @@
     ],
     "scripts": {
         "build": "vite build --config vite.build.config.ts && tsc --declaration --emitDeclarationOnly --outDir dist --noEmit false --rootDir src",
-        "typecheck": "tsc --noEmit",
+        "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
         "test": "vitest run",
         "test:watch": "vitest"
     },