@mauroandre/velojs 0.0.22 → 0.0.24

package/dist/testing/index.js

@@ -0,0 +1,488 @@
+import { getRegisteredStreams as T } from "../events.js";
+import { createIsolatedContext as E, withAppContext as R } from "../app-context.js";
+function k(e) {
+  if (!e) return;
+  const r = Object.entries(e);
+  if (r.length !== 0)
+    return r.map(([a, u]) => `${encodeURIComponent(a)}=${encodeURIComponent(u)}`).join("; ");
+}
+function _(e) {
+  const r = {}, a = e.getSetCookie?.() ?? [];
+  for (const u of a) {
+    const i = u.indexOf(";"), l = i === -1 ? u : u.slice(0, i), h = l.indexOf("=");
+    if (h === -1) continue;
+    const c = l.slice(0, h).trim(), t = l.slice(h + 1).trim();
+    c && (r[c] = decodeURIComponent(t));
+  }
+  return r;
+}
+function x(e) {
+  if (!e) return "";
+  const r = new URLSearchParams();
+  for (const [u, i] of Object.entries(e))
+    if (Array.isArray(i))
+      for (const l of i) r.append(u, l);
+    else
+      r.set(u, i);
+  const a = r.toString();
+  return a ? `?${a}` : "";
+}
+function A(e) {
+  const r = {};
+  return e.forEach((a, u) => {
+    r[u] = a;
+  }), r;
+}
+function P(e) {
+  return e == null ? { body: null, contentType: null } : typeof e == "string" || e instanceof FormData || e instanceof URLSearchParams || e instanceof Blob || e instanceof ArrayBuffer || ArrayBuffer.isView(e) ? { body: e, contentType: null } : {
+    body: JSON.stringify(e),
+    contentType: "application/json"
+  };
+}
+const C = "http://velojs.test";
+function S(e, r) {
+  const a = x(r);
+  return e.startsWith("http://") || e.startsWith("https://") ? e + a : (e.startsWith("/") || (e = "/" + e), C + e + a);
+}
+function I(e) {
+  const r = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map();
+  function u(i) {
+    for (const l of i) {
+      const h = l.module.metadata?.moduleId, c = l.module.metadata?.fullPath;
+      if (h) {
+        for (const o of Object.keys(l.module)) {
+          if (!o.startsWith("action_")) continue;
+          const f = l.module[o];
+          if (typeof f != "function") continue;
+          const d = o.replace("action_", "");
+          r.set(f, {
+            name: d,
+            fn: f,
+            moduleId: h,
+            url: `/_action/${h}/${d}`
+          });
+        }
+        const t = l.module.loader;
+        if (typeof t == "function" && c) {
+          const o = a.get(t);
+          o ? o.paths.push(c) : a.set(t, {
+            fn: t,
+            moduleId: h,
+            paths: [c]
+          });
+        }
+      }
+      l.children && u(l.children);
+    }
+  }
+  return u(e), { actions: r, loaders: a };
+}
+function q(e, r) {
+  if (typeof r == "string") return r;
+  const a = e.actions.get(r);
+  if (!a)
+    throw new Error(
+      `[velojs/testing] action_* function was not found in the route tree.
+Make sure your Vitest config loads the VeloJS Vite plugin so that metadata is injected. See https://github.com/mauro-andre/velojs#testing`
+    );
+  return a.url;
+}
+function J(e, r, a) {
+  if (typeof r == "string") return r;
+  const u = e.loaders.get(r);
+  if (!u)
+    throw new Error(
+      `[velojs/testing] loader function was not found in the route tree.
+Make sure your Vitest config loads the VeloJS Vite plugin so that metadata is injected.`
+    );
+  let i = u.paths[0];
+  if (a)
+    for (const [l, h] of Object.entries(a))
+      i = i.replace(`:${l}`, encodeURIComponent(h));
+  return i;
+}
+class $ {
+  buffer = "";
+  current = {
+    event: "message",
+    data: []
+  };
+  push(r) {
+    this.buffer += r;
+    const a = [];
+    let u;
+    for (; (u = this.buffer.indexOf(`
+`)) !== -1; ) {
+      const i = this.buffer.slice(0, u);
+      if (this.buffer = this.buffer.slice(u + 1), i === "") {
+        if (this.current.data.length > 0 || this.current.event !== "message") {
+          const t = {
+            event: this.current.event,
+            data: this.current.data.join(`
+`)
+          };
+          this.current.id !== void 0 && (t.id = this.current.id), a.push(t);
+        }
+        this.current = { event: "message", data: [] };
+        continue;
+      }
+      if (i.startsWith(":")) continue;
+      const l = i.indexOf(":");
+      if (l === -1) continue;
+      const h = i.slice(0, l);
+      let c = i.slice(l + 1);
+      c.startsWith(" ") && (c = c.slice(1)), h === "event" ? this.current.event = c : h === "data" ? this.current.data.push(c) : h === "id" && (this.current.id = c);
+    }
+    return a;
+  }
+}
+async function H(e) {
+  const { response: r } = e, a = r.status, u = [];
+  let i = null, l = !1, h = null;
+  const c = [];
+  let t = null, o = Promise.resolve(void 0);
+  const f = (p) => {
+    for (; c.length > 0; ) {
+      const n = c.shift();
+      p ? n.reject(p) : n.reject(new Error("[velojs/testing] subscription closed before next event"));
+    }
+  };
+  if (a >= 200 && a < 300 && r.body) {
+    t = r.body.getReader();
+    const p = new TextDecoder(), n = new $();
+    o = (async () => {
+      try {
+        for (; ; ) {
+          const { value: s, done: w } = await t.read();
+          if (w) {
+            l || (l = !0), f();
+            return;
+          }
+          const g = p.decode(s, { stream: !0 }), v = n.push(g);
+          for (const m of v) {
+            if (m.event === "snapshot") {
+              try {
+                i = JSON.parse(m.data);
+              } catch (b) {
+                h = b;
+              }
+              continue;
+            }
+            if (m.event === "close") {
+              l = !0, f(), t.cancel().catch(() => {
+              });
+              return;
+            }
+            if (m.event !== "heartbeat")
+              try {
+                const b = JSON.parse(m.data);
+                u.push(b);
+                const j = c.shift();
+                j && j.resolve(b);
+              } catch (b) {
+                h = b;
+              }
+          }
+        }
+      } catch (s) {
+        if (s?.name === "AbortError") {
+          f();
+          return;
+        }
+        f(s);
+      }
+    })();
+  } else
+    await r.text().catch(() => ""), l = !0;
+  const d = {
+    get status() {
+      return a;
+    },
+    get events() {
+      return u;
+    },
+    get snapshot() {
+      return i;
+    },
+    get closed() {
+      return l;
+    },
+    async next({ timeoutMs: p }) {
+      if (h) throw h;
+      if (u.length > y) {
+        const n = u[y];
+        return y++, n;
+      }
+      if (l)
+        throw new Error("[velojs/testing] subscription is closed");
+      return new Promise((n, s) => {
+        const w = setTimeout(() => {
+          const m = c.findIndex((b) => b.resolve === g);
+          m !== -1 && c.splice(m, 1), s(new Error(
+            `[velojs/testing] timed out after ${p}ms waiting for next event`
+          ));
+        }, p), g = (m) => {
+          clearTimeout(w), y++, n(m);
+        }, v = (m) => {
+          clearTimeout(w), s(m);
+        };
+        c.push({ resolve: g, reject: v });
+      });
+    },
+    async nextN(p, { timeoutMs: n }) {
+      const s = Date.now(), w = [];
+      for (let g = 0; g < p; g++) {
+        const v = n - (Date.now() - s);
+        if (v <= 0)
+          throw new Error(
+            `[velojs/testing] timed out after ${n}ms waiting for ${p} events (got ${w.length})`
+          );
+        w.push(await d.next({ timeoutMs: v }));
+      }
+      return w;
+    },
+    async close() {
+      if (t)
+        try {
+          await t.cancel();
+        } catch {
+        }
+      l = !0, f(), await o.catch(() => {
+      });
+    }
+  };
+  let y = 0;
+  return d;
+}
+function N(e = {}) {
+  const { user: r, params: a = {}, query: u = {}, body: i, headers: l = {}, cookies: h } = e, c = k(h), t = new Headers(l);
+  c && !t.has("cookie") && t.set("cookie", c);
+  const o = C + "/_mock" + x(u), f = {
+    method: i == null ? "GET" : "POST",
+    headers: t
+  };
+  i != null && (typeof i == "string" || i instanceof FormData || i instanceof Blob ? f.body = i : (f.body = JSON.stringify(i), t.has("content-type") || t.set("content-type", "application/json")));
+  const d = new Request(o, f), y = /* @__PURE__ */ new Map();
+  return r !== void 0 && y.set("user", r), {
+    req: {
+      raw: d,
+      url: d.url,
+      method: d.method,
+      param(n) {
+        return n === void 0 ? a : a[n];
+      },
+      query(n) {
+        if (n === void 0) {
+          const s = {};
+          for (const [w, g] of Object.entries(u))
+            s[w] = String(g);
+          return s;
+        }
+        return u[n];
+      },
+      queries(n) {
+        const s = u[n];
+        if (s !== void 0)
+          return Array.isArray(s) ? s : [s];
+      },
+      header(n) {
+        if (n === void 0) {
+          const s = {};
+          return t.forEach((w, g) => {
+            s[g] = w;
+          }), s;
+        }
+        return t.get(n) ?? void 0;
+      },
+      async json() {
+        return i == null ? null : typeof i == "object" ? i : JSON.parse(String(i));
+      },
+      async text() {
+        return i == null ? "" : typeof i == "string" ? i : JSON.stringify(i);
+      },
+      async parseBody() {
+        return i ?? {};
+      },
+      path: "/_mock"
+    },
+    res: void 0,
+    env: {},
+    finalized: !1,
+    get(n) {
+      return y.get(n);
+    },
+    set(n, s) {
+      y.set(n, s);
+    },
+    var: new Proxy({}, {
+      get(n, s) {
+        return y.get(s);
+      }
+    }),
+    json(n, s = 200) {
+      return new Response(JSON.stringify(n), {
+        status: s,
+        headers: { "content-type": "application/json" }
+      });
+    },
+    text(n, s = 200) {
+      return new Response(n, { status: s });
+    },
+    html(n, s = 200) {
+      return new Response(n, {
+        status: s,
+        headers: { "content-type": "text/html; charset=UTF-8" }
+      });
+    },
+    body(n, s = 200) {
+      return new Response(n, { status: s });
+    },
+    redirect(n, s = 302) {
+      return new Response(null, { status: s, headers: { location: n } });
+    },
+    header(n, s) {
+    },
+    status(n) {
+    }
+  };
+}
+async function W(e) {
+  const r = E();
+  return await R(r, async () => {
+    e.bootstrap && await e.bootstrap();
+    const { createApp: a } = await import("../server.js"), u = await a(e.routes), i = I(e.routes);
+    return V(u, r, i, e, void 0);
+  });
+}
+function V(e, r, a, u, i) {
+  async function l(t, o, f = {}) {
+    const d = S(o, f.query), y = new Headers(f.headers ?? {}), p = { ...f.cookies ?? {} }, n = k(p);
+    n && y.set("cookie", n);
+    let s = null;
+    if (f.body !== void 0) {
+      const m = P(f.body);
+      s = m.body, m.contentType && !y.has("content-type") && y.set("content-type", m.contentType);
+    }
+    const w = { method: t, headers: y };
+    s !== null && (w.body = s);
+    const g = new Request(d, w), v = await e.fetch(g);
+    return await B(v);
+  }
+  async function h(t, o, f = {}) {
+    const d = S(o, {
+      ...f.query ?? {},
+      ...f.channel ? { channel: f.channel } : {}
+    }), y = new Headers(f.headers ?? {}), p = { ...f.cookies ?? {} }, n = k(p);
+    n && y.set("cookie", n);
+    const s = new Request(d, { method: t, headers: y });
+    return await e.fetch(s);
+  }
+  const c = {
+    hono: e,
+    // HTTP
+    get: (t, o) => l("GET", t, o ?? {}),
+    post: (t, o) => l("POST", t, o ?? {}),
+    put: (t, o) => l("PUT", t, o ?? {}),
+    patch: (t, o) => l("PATCH", t, o ?? {}),
+    delete: (t, o) => l("DELETE", t, o ?? {}),
+    async action(t, o = {}) {
+      const f = q(a, t);
+      return await l("POST", f, {
+        ...o,
+        body: o.body ?? {}
+      });
+    },
+    async loader(t, o = {}) {
+      const f = J(a, t, o.params), d = await l("GET", f, {
+        ...o,
+        query: { ...o.query ?? {}, _data: "1" }
+      });
+      if (d.status >= 300 && d.status < 400 || d.status >= 400) return d;
+      const y = typeof t == "function" ? a.loaders.get(t)?.moduleId : void 0, p = await d.json();
+      return y && p && typeof p == "object" && y in p ? p[y] : p;
+    },
+    async subscribe(t, o = {}) {
+      const f = typeof t == "string" ? t : t.__path ?? D(), d = await h("GET", f, o);
+      return await H({ response: d });
+    },
+    async sessionCookies({ user: t }) {
+      if (!u.getSessionCookie)
+        throw new Error(
+          "[velojs/testing] sessionCookies/as requires `getSessionCookie` in createTestApp options."
+        );
+      return await u.getSessionCookie({ user: t });
+    },
+    as({ user: t }) {
+      if (!u.getSessionCookie)
+        throw new Error(
+          "[velojs/testing] app.as() requires `getSessionCookie` in createTestApp options."
+        );
+      let o = null;
+      const f = () => (o || (o = Promise.resolve(u.getSessionCookie({ user: t }))), o), d = (p) => (async (...n) => {
+        const s = await f(), [w, g] = n, v = {
+          ...g ?? {},
+          cookies: { ...s, ...g?.cookies ?? {} }
+        };
+        return await p.call(c, w, v);
+      });
+      return {
+        hono: e,
+        get: d(c.get),
+        post: d(c.post),
+        put: d(c.put),
+        patch: d(c.patch),
+        delete: d(c.delete),
+        action: d(c.action),
+        loader: d(c.loader),
+        subscribe: d(c.subscribe),
+        sessionCookies: c.sessionCookies,
+        as: c.as,
+        // chaining .as.as works — last wins
+        mockContext: c.mockContext,
+        reset: c.reset,
+        close: c.close
+      };
+    },
+    mockContext(t = {}) {
+      return N(t);
+    },
+    async reset() {
+      for (const t of T())
+        try {
+          t.__reset();
+        } catch (o) {
+          console.error("[velojs/testing] stream.__reset failed:", o);
+        }
+    },
+    async close() {
+      await c.reset();
+      for (const t of r.disposers)
+        try {
+          t();
+        } catch (o) {
+          console.error("[velojs/testing] disposer failed:", o);
+        }
+      r.disposers.clear();
+    }
+  };
+  return c;
+}
+async function B(e) {
+  return {
+    status: e.status,
+    headers: A(e.headers),
+    cookies: _(e.headers),
+    json: () => e.clone().json(),
+    text: () => e.clone().text(),
+    blob: () => e.clone().blob(),
+    raw: e
+  };
+}
+function D(e) {
+  throw new Error(
+    "[velojs/testing] subscribe(stream) — stream has no __path. If this is a stream_* declaration, make sure your routes import is processed by the VeloJS Vite plugin (your vitest.config.ts must include `veloPlugin()`)."
+  );
+}
+export {
+  W as createTestApp
+};

package/dist/testing/internal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Internal helpers — not exported from `@mauroandre/velojs/testing`.
+ */
+import type { Cookies, Headers as TestHeaders, Query } from "./types.js";
+/** Serialize cookies object into a `Cookie` header value. */
+export declare function serializeCookies(cookies?: Cookies): string | undefined;
+/** Parse Set-Cookie header(s) into a cookies record (best effort). */
+export declare function parseSetCookies(headers: Headers): Cookies;
+/** Convert query object to URL search string (without leading `?`). */
+export declare function buildQueryString(query?: Query): string;
+/** Convert headers record (any case) to a Headers instance. */
+export declare function toHeaders(record?: TestHeaders): Headers;
+/** Headers instance → flat record. */
+export declare function fromHeaders(h: Headers): TestHeaders;
+/**
+ * Encode a body for fetch:
+ * - FormData / URLSearchParams / Blob / ReadableStream / string → passed as-is
+ * - undefined/null → no body
+ * - everything else → JSON.stringify + Content-Type: application/json
+ */
+export declare function encodeBody(body: unknown): {
+    body: BodyInit | null;
+    contentType: string | null;
+};
+/**
+ * Build a Request URL using a base — Hono's `app.fetch` requires absolute URLs.
+ * We use a fixed in-memory host since no socket is opened.
+ */
+export declare const TEST_BASE_URL = "http://velojs.test";
+export declare function buildUrl(path: string, query?: Query): string;

package/dist/testing/mockContext.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Escape hatch — build a partial Hono Context for direct invocation of
+ * actions / loaders / jobs without going through HTTP.
+ *
+ * Middlewares do NOT run. This is intentional — pass `c.set("user", ...)` etc
+ * via the `user` option if your handler reads from `c.get("user")`.
+ */
+import type { Context } from "hono";
+import type { MockContextOptions } from "./types.js";
+export declare function buildMockContext(opts?: MockContextOptions): Context;

package/dist/testing/subscription.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SSE subscription helper — parses the SSE protocol from a streaming Response
+ * and exposes assertion-friendly methods for tests.
+ */
+import type { TestSubscription } from "./types.js";
+interface BuildSubscriptionOptions {
+    response: Response;
+    parseJson?: boolean;
+}
+export declare function buildSubscription<TEvent, TSnapshot>(opts: BuildSubscriptionOptions): Promise<TestSubscription<TEvent, TSnapshot>>;
+export {};

package/dist/testing/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Public types for the VeloJS testing toolkit.
+ */
+import type { Hono, Context } from "hono";
+import type { AppRoutes } from "../types.js";
+import type { EventStream } from "../events.js";
+export type Cookies = Record<string, string>;
+export type Headers = Record<string, string>;
+export type Query = Record<string, string | string[]>;
+export type Params = Record<string, string>;
+export interface CreateTestAppOptions {
+    /** App routes — typically `import { routes } from "./app/routes.js"`. */
+    routes: AppRoutes;
+    /**
+     * Optional setup that runs once before the app is created.
+     * Use for DB connections, index creation, or any side effects that the
+     * production `app/server.tsx` would do at startup.
+     *
+     * `addRoutes()` and `onServer()` calls here are scoped to this app only.
+     */
+    bootstrap?: () => void | Promise<void>;
+    /**
+     * Optional callback that maps a `user` (or any opaque object) to the
+     * cookies the test client should attach. Required for `app.as(user)` and
+     * `app.sessionCookies(user)`.
+     */
+    getSessionCookie?: (input: {
+        user: any;
+    }) => Promise<Cookies> | Cookies;
+}
+export interface RequestOptions {
+    /** Cookies serialized into the `Cookie` header. */
+    cookies?: Cookies;
+    /** Extra headers (case-insensitive). */
+    headers?: Headers;
+    /** Query string. Arrays become repeated keys: `{ tag: ["a","b"] }` → `?tag=a&tag=b`. */
+    query?: Query;
+}
+export interface BodyRequestOptions extends RequestOptions {
+    /** Body — plain object → JSON; FormData/URLSearchParams/Blob/string passed as-is. */
+    body?: unknown;
+}
+export interface LoaderRequestOptions extends RequestOptions {
+    /** URL params (for routes with `:id` placeholders). */
+    params?: Params;
+}
+/** Wraps the Hono Response. */
+export interface TestResponse {
+    status: number;
+    headers: Headers;
+    json<T = any>(): Promise<T>;
+    text(): Promise<string>;
+    blob(): Promise<Blob>;
+    /** Cookie header parsed: `{ session: "value" }`. */
+    cookies: Cookies;
+    /** Underlying Response (Fetch spec). */
+    raw: Response;
+}
+export interface SubscribeOptions extends RequestOptions {
+    /** Channel ID — sent as `?channel=...`. */
+    channel?: string;
+}
+export interface NextOptions {
+    /** Reject if no event arrives within this many ms. */
+    timeoutMs: number;
+}
+export interface TestSubscription<TEvent = any, TSnapshot = any> {
+    /** HTTP status of the initial SSE response (200, 403, etc). */
+    readonly status: number;
+    /** All events received since connect, in order. */
+    readonly events: ReadonlyArray<TEvent>;
+    /** Snapshot from the server (if any). */
+    readonly snapshot: TSnapshot | null;
+    /** True when the server signaled a deliberate close (closeOn / stream.close). */
+    readonly closed: boolean;
+    /** Wait for the next event. Rejects on timeout. */
+    next(opts: NextOptions): Promise<TEvent>;
+    /** Wait for N events. Total timeout, not per-event. */
+    nextN(n: number, opts: NextOptions): Promise<TEvent[]>;
+    /** Force disconnect. Triggers per-channel source abortSignal server-side. */
+    close(): Promise<void>;
+}
+export interface MockContextOptions {
+    user?: any;
+    params?: Params;
+    query?: Record<string, string>;
+    body?: unknown;
+    headers?: Headers;
+    cookies?: Cookies;
+}
+export interface TestApp {
+    /** Underlying Hono app. */
+    readonly hono: Hono;
+    get(path: string, opts?: RequestOptions): Promise<TestResponse>;
+    post(path: string, opts?: BodyRequestOptions): Promise<TestResponse>;
+    put(path: string, opts?: BodyRequestOptions): Promise<TestResponse>;
+    patch(path: string, opts?: BodyRequestOptions): Promise<TestResponse>;
+    delete(path: string, opts?: RequestOptions): Promise<TestResponse>;
+    /**
+     * Invoke a `action_*` server function via HTTP. Auto-resolves URL from the
+     * function's metadata (injected by the VeloJS Vite plugin).
+     */
+    action(fn: Function | string, opts?: BodyRequestOptions): Promise<TestResponse>;
+    /**
+     * Invoke a `loader` server function. By default unwraps the response data:
+     * - Resolved normally → returns the loader's return value
+     * - Threw → re-throws
+     * - Redirected → returns a `TestResponse` for status inspection
+     */
+    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>>;
+    /** Build cookies for a user via `getSessionCookie` config. */
+    sessionCookies(input: {
+        user: any;
+    }): Promise<Cookies>;
+    /** Sub-client with cookies automatically applied to every request. */
+    as(input: {
+        user: any;
+    }): TestApp;
+    mockContext(opts?: MockContextOptions): Context;
+    /** Reset all transient state (stream buffers, listeners, retention timers). */
+    reset(): Promise<void>;
+    /** Tear down everything (timers, callbacks). Vitest must report zero open handles. */
+    close(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mauroandre/velojs",
-    "version": "0.0.22",
+    "version": "0.0.24",
     "type": "module",
     "description": "Fullstack web framework built on Hono + Preact with Vite-powered AST transforms",
     "keywords": [
@@ -57,6 +57,10 @@
             "types": "./dist/events.d.ts",
             "import": "./dist/events.js"
         },
+        "./testing": {
+            "types": "./dist/testing/index.d.ts",
+            "import": "./dist/testing/index.js"
+        },
         "./cookie": {
             "types": "./dist/cookie.d.ts",
             "import": "./dist/cookie.js"