@mauroandre/velojs 0.0.21 → 0.0.22

package/README.md

@@ -629,10 +629,12 @@ export const stream_deploy = createEventStream<DeployState>({
 |--------|------|-------------|
 | `path` | `string` | (Standalone) Explicit URL path |
 | `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` |
+| `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 |
@@ -698,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
@@ -1143,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).
@@ -79,9 +109,12 @@ export interface EventStreamConfig<TEvent, TSnapshot = TEvent> {
      * 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)
@@ -127,14 +160,37 @@ 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> {
     /**

package/dist/events.js

@@ -1,88 +1,112 @@
-const T = [];
-function m(t) {
-  for (const r of T) r(t);
-  T.length = 0;
+const C = [];
+function R(t) {
+  for (const a of C) a(t);
+  C.length = 0;
 }
-function N(t = {}) {
-  t.broadcast && t.channel && console.warn(
+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."
-  );
-  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 })
+  ), 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(_, { abortSignal: u.signal })
     ).catch((e) => {
       console.error("[velojs] event stream source threw:", e);
     })));
-  }, w = () => {
-    A > 0 || f && (f.abort(), f = 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 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)) {
+  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 "${s}" — 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 (h?.snapshot) {
-      const b = o.get(s) ?? [];
-      b.push(l), o.set(s, b);
+    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 v = r.get(s);
-    if (v)
-      for (const b of v) b(l);
+    const m = a.get(r);
+    if (m)
+      for (const w of m) w(S);
   }
-  function i(e = "") {
-    if (a.has(e)) return;
-    a.add(e);
-    const c = r.get(e);
-    if (c)
-      for (const l of c) l.close();
-    const n = t.retainMs ?? 3e5, s = u.get(e);
-    s && clearTimeout(s), u.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(() => {
-        o.delete(e), u.delete(e), a.delete(e);
+        s.delete(e), d.delete(e), l.delete(e);
       }, n)
     );
   }
-  const S = {
-    emit: E,
-    close: i,
+  const h = {
+    emit: _,
+    close: A,
     __isVeloEventStream: !0,
     __config: t,
-    __listeners: r,
-    __buffers: o,
+    __listeners: a,
+    __buffers: s,
     __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();
+    __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, c) {
-      const n = r.get(e);
-      n && (n.delete(c), n.size === 0 && r.delete(e), A--, w());
+    __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 && T.push((e) => {
-    g(e, t.path, S, t.middlewares ?? []);
-  }), S;
+  return t.path && C.push((e) => {
+    N(e, t.path, h, t.middlewares ?? []);
+  }), h;
 }
-function C(t) {
-  return async (r, { abortSignal: o }) => {
-    for (; !o.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 u = setTimeout(a, t.intervalMs);
-        o.addEventListener(
+      await new Promise((l) => {
+        const d = setTimeout(l, t.intervalMs);
+        s.addEventListener(
           "abort",
           () => {
-            clearTimeout(u), a();
+            clearTimeout(d), l();
           },
           { once: !0 }
         );
@@ -90,51 +114,67 @@ function C(t) {
     }
   };
 }
-function p(t) {
+function g(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({
+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(S)
-      }), o.__config.snapshot) {
-        const _ = await o.__config.snapshot(
-          d === "" ? void 0 : d
+        data: JSON.stringify(f)
+      }), s.__config.snapshot) {
+        const r = await s.__config.snapshot(
+          c === "" ? void 0 : c
         );
-        _ !== void 0 && await i.writeSSE({
+        r !== void 0 && await i.writeSSE({
           event: "snapshot",
-          data: JSON.stringify(_)
+          data: JSON.stringify(r)
         });
       }
-      let e;
-      const c = new Promise((_) => {
-        e = _;
+      let _;
+      const A = new Promise((r) => {
+        _ = r;
       });
-      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 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()));
       });
-      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(() => {
+      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, i.onAbort(l), await c;
+      }, v) : null, i.onAbort(o), await A;
     });
   };
-  a.length > 0 ? t.on(["GET"], [r], ...a, u) : t.on(["GET"], [r], u);
+  l.length > 0 ? t.on(["GET"], [a], ...l, d) : t.on(["GET"], [a], d);
 }
 export {
-  N as createEventStream,
-  m as flushPendingStreamRoutes,
-  C as poll,
-  g 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.21",
+    "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"
     },