@mauroandre/velojs 0.0.22 → 0.0.24

package/README.md

@@ -1188,6 +1188,60 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 
 ---
 
+## Testing
+
+VeloJS ships a backend testing toolkit at `@mauroandre/velojs/testing`. Spin up the app in memory, fire HTTP requests against the registered handlers, subscribe to event streams. No socket, no browser, no fragile mocks of framework internals.
+
+```typescript
+import { createTestApp } from "@mauroandre/velojs/testing";
+import { routes } from "../app/routes.js";
+import { stream_progress } from "../app/Deploy.js";
+import { action_startDeploy } from "../app/Deploy.js";
+
+const app = await createTestApp({
+    routes,
+    bootstrap: async () => { await connect(process.env.MONGO_URI!); },
+    getSessionCookie: async ({ user }) => ({ session: await sign(user) }),
+});
+
+// HTTP
+const res = await app.get("/api/health");
+
+// Convention helpers — pass the function, framework resolves the URL
+const data = await app.loader(homeLoader, { params: { id: "abc" } });
+await app.action(action_startDeploy, { body: { appId } });
+
+// Streams — TestSubscription with snapshot, next(), close, etc
+const sub = await app.subscribe(stream_progress, { channel: appId });
+expect(sub.status).toBe(200);
+const event = await sub.next({ timeoutMs: 2000 });
+
+// Auth — sub-client with cookies bound automatically
+const asAlice = app.as({ user: alice });
+await asAlice.subscribe(stream_progress, { channel: appId });
+
+await app.close();
+```
+
+**Prerequisite:** `vitest.config.ts` must include `veloPlugin()` so action/loader/stream metadata is injected.
+
+| API | Purpose |
+|-----|---------|
+| `createTestApp(options)` | Build isolated app with bootstrap + auth callback |
+| `app.get/post/put/patch/delete` | HTTP requests (cookies, headers, query, JSON/FormData body) |
+| `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.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 |
+| `app.reset()` | Clear stream buffers/listeners between tests |
+| `app.close()` | Tear down everything (zero open handles guaranteed) |
+
+See [Testing docs](https://github.com/mauro-andre/velojs/blob/dev/site/docs/16-testing.md) for the full guide with patterns, isolation, and FAQ.
+
+---
+
 ## Subpath Exports
 
 | Import | Contents |
@@ -1197,6 +1251,7 @@ Hooks (`useParams`, `useQuery`, `usePathname`, `Loader`, `useLoader`) access thi
 | `@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`, `PerChannelSourceFn`, `ChannelResolver` (also re-exported from root) |
+| `@mauroandre/velojs/testing` | `createTestApp`, `TestApp`, `TestResponse`, `TestSubscription`, `CreateTestAppOptions`, `MockContextOptions` |
 | `@mauroandre/velojs/cookie` | `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie` |
 | `@mauroandre/velojs/factory` | `createMiddleware`, `createFactory` |
 | `@mauroandre/velojs/vite` | `veloPlugin` |

package/dist/app-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * App context — scoped via a swappable global slot so multiple test apps
+ * can coexist without polluting each other's pending route registrations.
+ *
+ * Production runtime uses a single default context implicitly. Tests create
+ * isolated contexts via `withAppContext()` which swaps the slot for the
+ * duration of the call.
+ *
+ * NOTE: this module is client-safe (no `node:async_hooks` import). Vitest runs
+ * each test file in its own worker, so a simple swappable slot is sufficient
+ * for parallelism between files. Within a single file, tests run sequentially
+ * unless `describe.concurrent`/`it.concurrent` is used.
+ */
+import type { Hono } from "hono";
+type RouteRegisterFn = (app: Hono) => void | Promise<void>;
+type StreamRouteRegisterFn = (app: Hono) => void;
+type ServerCallbackFn = (server: any) => void;
+export interface AppContext {
+    pendingRoutes: RouteRegisterFn[];
+    pendingStreamRoutes: StreamRouteRegisterFn[];
+    serverCallbacks: ServerCallbackFn[];
+    disposers: Set<() => void>;
+}
+export declare function getAppContext(): AppContext;
+/**
+ * Run a function within an isolated app context (for tests).
+ * Restores the previous context after the function resolves/rejects.
+ */
+export declare function withAppContext<T>(ctx: AppContext, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Create a new isolated context. Inherits a SNAPSHOT of the default context
+ * so any addRoutes/onServer/createEventStream calls that happened at top-level
+ * import time are captured.
+ */
+export declare function createIsolatedContext(): AppContext;
+export declare function registerDisposer(dispose: () => void): void;
+export declare function unregisterDisposer(dispose: () => void): void;
+export {};

package/dist/app-context.js

@@ -0,0 +1,43 @@
+function o() {
+  return {
+    pendingRoutes: [],
+    pendingStreamRoutes: [],
+    serverCallbacks: [],
+    disposers: /* @__PURE__ */ new Set()
+  };
+}
+const n = o();
+let e = n;
+function i() {
+  return e;
+}
+async function p(t, s) {
+  const r = e;
+  e = t;
+  try {
+    return await s();
+  } finally {
+    e = r;
+  }
+}
+function u() {
+  return {
+    pendingRoutes: [...n.pendingRoutes],
+    pendingStreamRoutes: [...n.pendingStreamRoutes],
+    serverCallbacks: [...n.serverCallbacks],
+    disposers: /* @__PURE__ */ new Set()
+  };
+}
+function a(t) {
+  e.disposers.add(t);
+}
+function d(t) {
+  e.disposers.delete(t);
+}
+export {
+  u as createIsolatedContext,
+  i as getAppContext,
+  a as registerDisposer,
+  d as unregisterDisposer,
+  p as withAppContext
+};

package/dist/events.d.ts

@@ -221,6 +221,8 @@ export interface EventStream<TEvent, TSnapshot = TEvent> {
     __onConnect(channelKey: string, listener: StreamListener<TEvent>): void;
     /** Internal: source lifecycle hook */
     __onDisconnect(channelKey: string, listener: StreamListener<TEvent>): void;
+    /** @internal Test-only: reset all transient state (buffers, listeners, controllers, timers). */
+    __reset(): void;
 }
 /** Internal listener — receives events and a close signal. */
 interface StreamListener<TEvent> {
@@ -228,6 +230,8 @@ interface StreamListener<TEvent> {
     close(): void;
 }
 export declare function flushPendingStreamRoutes(app: Hono): void;
+/** @internal Used by `@mauroandre/velojs/testing` to reset all streams. */
+export declare function getRegisteredStreams(): ReadonlySet<EventStream<unknown, unknown>>;
 export declare function createEventStream<TEvent, TSnapshot = TEvent>(config?: EventStreamConfig<TEvent, TSnapshot>): EventStream<TEvent, TSnapshot>;
 /**
  * Creates a `source` function that runs `tick` every `intervalMs` while subscribed.

package/dist/events.js

@@ -1,7 +1,12 @@
-const C = [];
-function R(t) {
-  for (const a of C) a(t);
-  C.length = 0;
+import { getAppContext as A } from "./app-context.js";
+const M = 2e4, R = 300 * 1e3, v = "";
+function x(t) {
+  const o = A().pendingStreamRoutes.splice(0);
+  for (const c of o) c(t);
+}
+const I = /* @__PURE__ */ new Set();
+function y() {
+  return I;
 }
 function L(t = {}) {
   if (t.broadcast && t.channel && console.warn(
@@ -10,103 +15,116 @@ function L(t = {}) {
     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 })
+  const a = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), c = /* @__PURE__ */ new Set(), f = /* @__PURE__ */ new Map();
+  let l = null, w = 0;
+  const i = /* @__PURE__ */ new Map(), b = () => {
+    t.source && (l || (l = new AbortController(), Promise.resolve(
+      t.source(p, { abortSignal: l.signal })
     ).catch((e) => {
       console.error("[velojs] event stream source threw:", e);
     })));
-  }, 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) => {
+  }, m = () => {
+    w > 0 || l && (l.abort(), l = null);
+  }, u = (e) => {
+    if (!t.perChannelSource || i.has(e)) return;
+    const n = new AbortController();
+    i.set(e, n);
+    const s = (r, S) => {
       h.emit(e, r, S);
     };
     Promise.resolve(
-      t.perChannelSource(e, n, { abortSignal: o.signal })
+      t.perChannelSource(e, s, { abortSignal: n.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));
+  }, d = (e) => {
+    const n = i.get(e);
+    n && (n.abort(), i.delete(e));
   };
-  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)) {
+  function p(e, n, s) {
+    let r, S, E;
+    if (!!t.broadcast ? (r = v, S = e, E = n) : (r = e, S = n, E = s), c.has(r)) {
       console.warn(
         `[velojs] emit() called on closed channel "${r}" — ignored. Reopen the channel by emitting to a fresh ID, or remove the close() call.`
       );
       return;
     }
-    if (b?.snapshot) {
-      const w = s.get(r) ?? [];
-      w.push(S);
+    if (E?.snapshot) {
+      const _ = o.get(r) ?? [];
+      _.push(S);
       const T = t.bufferSize ?? 1 / 0;
-      w.length > T && w.splice(0, w.length - T), s.set(r, w);
+      _.length > T && _.splice(0, _.length - T), o.set(r, _);
     }
-    const m = a.get(r);
-    if (m)
-      for (const w of m) w(S);
+    const C = a.get(r);
+    if (C)
+      for (const _ of C) _(S);
   }
-  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(
+  function g(e = v) {
+    if (c.has(e)) return;
+    c.add(e);
+    const n = a.get(e);
+    if (n)
+      for (const S of n) S.close();
+    const s = t.retainMs ?? R, r = f.get(e);
+    r && clearTimeout(r), f.set(
       e,
       setTimeout(() => {
-        s.delete(e), d.delete(e), l.delete(e);
-      }, n)
+        o.delete(e), f.delete(e), c.delete(e);
+      }, s)
     );
   }
   const h = {
-    emit: _,
-    close: A,
+    emit: p,
+    close: g,
     __isVeloEventStream: !0,
     __config: t,
     __listeners: a,
-    __buffers: s,
+    __buffers: o,
     __path: t.path,
-    __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);
+    __onConnect(e, n) {
+      let s = a.get(e);
+      const r = !s || s.size === 0;
+      s || (s = /* @__PURE__ */ new Set(), a.set(e, s)), s.add(n), w++, b(), r && u(e);
+    },
+    __onDisconnect(e, n) {
+      const s = a.get(e);
+      s && (s.delete(n), s.size === 0 && (a.delete(e), d(e)), w--, m());
     },
-    __onDisconnect(e, o) {
-      const n = a.get(e);
-      n && (n.delete(o), n.size === 0 && (a.delete(e), f(e)), p--, v());
+    __reset() {
+      for (const e of a.values())
+        for (const n of e)
+          try {
+            n.close();
+          } catch {
+          }
+      a.clear(), o.clear(), c.clear();
+      for (const e of f.values()) clearTimeout(e);
+      f.clear(), l && (l.abort(), l = null);
+      for (const e of i.values()) e.abort();
+      i.clear(), w = 0;
     }
   };
-  return t.path && C.push((e) => {
-    N(e, t.path, h, t.middlewares ?? []);
-  }), h;
+  return t.path && A().pendingStreamRoutes.push((e) => {
+    D(e, t.path, h, t.middlewares ?? []);
+  }), I.add(h), h;
 }
-function M(t) {
-  return async (a, { abortSignal: s }) => {
-    for (; !s.aborted; ) {
+function B(t) {
+  return async (a, { abortSignal: o }) => {
+    for (; !o.aborted; ) {
       try {
         await t.tick(a);
-      } catch (l) {
-        console.error("[velojs] poll tick threw:", l);
+      } catch (c) {
+        console.error("[velojs] poll tick threw:", c);
       }
-      await new Promise((l) => {
-        const d = setTimeout(l, t.intervalMs);
-        s.addEventListener(
+      await new Promise((c) => {
+        const f = setTimeout(c, t.intervalMs);
+        o.addEventListener(
           "abort",
           () => {
-            clearTimeout(d), l();
+            clearTimeout(f), c();
           },
           { once: !0 }
         );
@@ -114,67 +132,68 @@ function M(t) {
     }
   };
 }
-function g(t) {
-  return t.req.query("channel") ?? "";
+function j(t) {
+  return t.req.query("channel") ?? v;
 }
-function N(t, a, s, l = []) {
-  const d = async (u) => {
-    const { streamSSE: p } = await import("hono/streaming");
-    let c;
-    if (s.__config.broadcast)
-      c = "";
+function D(t, a, o, c = []) {
+  const f = async (l) => {
+    const { streamSSE: w } = await import("hono/streaming");
+    let i;
+    if (o.__config.broadcast)
+      i = v;
     else {
-      const i = s.__config.channel ?? g;
-      let f;
+      const u = o.__config.channel ?? j;
+      let d;
       try {
-        f = await i(u);
-      } catch (_) {
-        return console.error("[velojs] channel resolver threw:", _), u.json({ error: "internal" }, 500);
+        d = await u(l);
+      } catch (p) {
+        return console.error("[velojs] channel resolver threw:", p), l.json({ error: "internal" }, 500);
       }
-      if (f == null)
-        return u.json({ error: "forbidden" }, 403);
-      c = f;
+      if (d == null)
+        return l.json({ error: "forbidden" }, 403);
+      i = d;
     }
-    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({
+    const b = o.__config.heartbeatMs, m = b === !1 ? 0 : b ?? M;
+    return w(l, async (u) => {
+      const d = o.__buffers.get(i);
+      if (d && d.length > 0 && await u.writeSSE({
         event: "snapshot",
-        data: JSON.stringify(f)
-      }), s.__config.snapshot) {
-        const r = await s.__config.snapshot(
-          c === "" ? void 0 : c
+        data: JSON.stringify(d)
+      }), o.__config.snapshot) {
+        const r = await o.__config.snapshot(
+          i === v ? void 0 : i
         );
-        r !== void 0 && await i.writeSSE({
+        r !== void 0 && await u.writeSSE({
           event: "snapshot",
           data: JSON.stringify(r)
         });
       }
-      let _;
-      const A = new Promise((r) => {
-        _ = r;
+      let p;
+      const g = new Promise((r) => {
+        p = r;
       });
       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()));
+      const n = () => {
+        h || (h = !0, e && clearInterval(e), o.__onDisconnect(i, s), p());
+      }, s = ((r) => {
+        h || (u.writeSSE({ data: JSON.stringify(r) }).catch(() => {
+        }), o.__config.closeOn?.(r) && (u.close(), n()));
       });
-      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(() => {
+      s.close = () => {
+        h || (u.writeSSE({ event: "close", data: "" }).catch(() => {
+        }), u.close(), n());
+      }, o.__onConnect(i, s), e = m > 0 ? setInterval(() => {
+        h || u.writeSSE({ event: "heartbeat", data: "" }).catch(() => {
         });
-      }, v) : null, i.onAbort(o), await A;
+      }, m) : null, u.onAbort(n), await g;
     });
   };
-  l.length > 0 ? t.on(["GET"], [a], ...l, d) : t.on(["GET"], [a], d);
+  c.length > 0 ? t.on(["GET"], [a], ...c, f) : t.on(["GET"], [a], f);
 }
 export {
   L as createEventStream,
-  R as flushPendingStreamRoutes,
-  M as poll,
-  N as registerStreamHandler
+  x as flushPendingStreamRoutes,
+  y as getRegisteredStreams,
+  B as poll,
+  D as registerStreamHandler
 };