@nifrajs/testing 1.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @nifrajs/testing
+
+Testing helpers for nifra apps. [`@nifrajs/client`](../client)'s **`testClient`** is already the typed,
+no-network in-process request client (nifra's supertest / `inject`). This package adds what it doesn't: a
+**cookie jar** and a **cookie-persisting `testSession`**, so a login → authenticated-request flow tests as
+easily as a single request.
+
+```ts
+import { testSession } from "@nifrajs/testing"
+import { app } from "../src/app"
+
+const { client, cookies } = testSession<typeof app>(app)
+
+await client.auth.login.post({ email, password }) // Set-Cookie captured into the jar
+const me = await client.me.get()                   // Cookie sent automatically
+expect(me.ok && me.data.id).toBeDefined()
+expect(cookies.get("sid")).toBeDefined()           // inspect the jar
+
+await client.auth.logout.post()                    // a Max-Age=0 Set-Cookie clears it
+expect(cookies.get("sid")).toBeUndefined()
+```
+
+Same in-process client as `testClient` — the app's own `fetch`, no server/port/network, the full real
+lifecycle (validation, middleware, contracts, auth) and end-to-end types from `App`. The only addition is
+that every call carries and captures cookies via a shared jar.
+
+## API
+
+- `testSession<App>(app, { origin?, cookies? })` → `{ client: Treaty<App>, cookies: CookieJar }`.
+- `cookieJar()` → `CookieJar` — `header()` · `applyTo(headers)` · `store(response)` · `set` · `get` · `clear` · `size`.
+  Honours removal (`Max-Age=0` / past `Expires`); other cookie attributes are ignored (in-process, same-origin).
+
+For a **stateless** request (no cookies), use `testClient` from `@nifrajs/client` directly.

package/dist/cookies.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A tiny cookie jar for in-process tests — parses `Set-Cookie` off responses and emits a `Cookie`
+ * request header, so a login → authenticated-request flow works without threading headers by hand. It
+ * honours removal (`Max-Age=0` / a past `Expires`) so logout clears the cookie; other attributes
+ * (Domain/Path/Secure/SameSite) are ignored — everything is same-origin in-process.
+ */
+export interface CookieJar {
+    /** The current `Cookie` request-header value (`"a=1; b=2"`, or `""` when empty). */
+    header(): string;
+    /** Set the `Cookie` header on `headers` when the jar is non-empty. */
+    applyTo(headers: Headers): void;
+    /** Absorb every `Set-Cookie` on a response (setting or, on removal, deleting each). */
+    store(response: {
+        headers: Headers;
+    }): void;
+    set(name: string, value: string): void;
+    get(name: string): string | undefined;
+    clear(): void;
+    readonly size: number;
+}
+/** Create an empty cookie jar. */
+export declare function cookieJar(): CookieJar;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../src/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,MAAM,IAAI,MAAM,CAAA;IAChB,sEAAsE;IACtE,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAC/B,uFAAuF;IACvF,KAAK,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IAC3C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACrC,KAAK,IAAI,IAAI,CAAA;IACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AA8BD,kCAAkC;AAClC,wBAAgB,SAAS,IAAI,SAAS,CA0BrC"}

package/dist/cookies.js

@@ -0,0 +1,69 @@
+/**
+ * A tiny cookie jar for in-process tests — parses `Set-Cookie` off responses and emits a `Cookie`
+ * request header, so a login → authenticated-request flow works without threading headers by hand. It
+ * honours removal (`Max-Age=0` / a past `Expires`) so logout clears the cookie; other attributes
+ * (Domain/Path/Secure/SameSite) are ignored — everything is same-origin in-process.
+ */
+/** Read `Set-Cookie` values portably: `getSetCookie()` (Bun/Node/edge) with a single-header fallback. */
+function setCookies(headers) {
+    const withGetter = headers;
+    if (typeof withGetter.getSetCookie === "function")
+        return withGetter.getSetCookie();
+    const single = headers.get("set-cookie");
+    return single === null ? [] : [single];
+}
+function isRemoval(attributes) {
+    if (/(^|;)\s*max-age=0(\s|;|$)/.test(attributes))
+        return true;
+    const expires = /expires=([^;]+)/.exec(attributes);
+    if (expires === null)
+        return false;
+    const at = Date.parse(expires[1]);
+    return !Number.isNaN(at) && at < Date.now();
+}
+function parseSetCookie(line) {
+    const semicolon = line.indexOf(";");
+    const pair = semicolon === -1 ? line : line.slice(0, semicolon);
+    const equals = pair.indexOf("=");
+    if (equals === -1)
+        return null;
+    const name = pair.slice(0, equals).trim();
+    if (name === "")
+        return null;
+    const value = pair.slice(equals + 1).trim();
+    const attributes = semicolon === -1 ? "" : line.slice(semicolon + 1).toLowerCase();
+    return { name, value, remove: isRemoval(attributes) };
+}
+/** Create an empty cookie jar. */
+export function cookieJar() {
+    const cookies = new Map();
+    const header = () => [...cookies].map(([name, value]) => `${name}=${value}`).join("; ");
+    return {
+        header,
+        get size() {
+            return cookies.size;
+        },
+        set: (name, value) => {
+            cookies.set(name, value);
+        },
+        get: (name) => cookies.get(name),
+        clear: () => cookies.clear(),
+        applyTo: (headers) => {
+            const current = header();
+            if (current !== "")
+                headers.set("cookie", current);
+        },
+        store: (response) => {
+            for (const line of setCookies(response.headers)) {
+                const parsed = parseSetCookie(line);
+                if (parsed === null)
+                    continue;
+                if (parsed.remove)
+                    cookies.delete(parsed.name);
+                else
+                    cookies.set(parsed.name, parsed.value);
+            }
+        },
+    };
+}
+//# sourceMappingURL=cookies.js.map

package/dist/cookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../src/cookies.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @nifrajs/testing — helpers for testing nifra apps in-process. `@nifrajs/client`'s `testClient` is the
+ * typed, no-network request client (the supertest/inject equivalent); this adds what it doesn't: a
+ * {@link cookieJar} and a cookie-persisting {@link testSession}, so stateful auth/session flows are as
+ * easy to test as a single request.
+ *
+ *   import { testSession } from "@nifrajs/testing"
+ *   const { client, cookies } = testSession<typeof app>(app)
+ */
+export { type CookieJar, cookieJar } from "./cookies.js";
+export { type AppLike, type TestSession, type TestSessionOptions, testSession } from "./session.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @nifrajs/testing — helpers for testing nifra apps in-process. `@nifrajs/client`'s `testClient` is the
+ * typed, no-network request client (the supertest/inject equivalent); this adds what it doesn't: a
+ * {@link cookieJar} and a cookie-persisting {@link testSession}, so stateful auth/session flows are as
+ * easy to test as a single request.
+ *
+ *   import { testSession } from "@nifrajs/testing"
+ *   const { client, cookies } = testSession<typeof app>(app)
+ */
+export { cookieJar } from "./cookies.js";
+export { testSession } from "./session.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAkB,SAAS,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAA2D,WAAW,EAAE,MAAM,cAAc,CAAA"}

package/dist/session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A stateful, cookie-aware in-process test client. `@nifrajs/client`'s `testClient` already drives an
+ * app's `fetch` with end-to-end types (no server/port/network) — this wraps it with a {@link CookieJar}
+ * that carries `Set-Cookie` across calls, so a login → authenticated-request flow just works.
+ *
+ *   import { testSession } from "@nifrajs/testing"
+ *   import { app } from "../src/app"
+ *
+ *   const { client, cookies } = testSession<typeof app>(app)
+ *   await client.auth.login.post({ email, password })   // Set-Cookie captured
+ *   const me = await client.me.get()                     // Cookie sent automatically
+ *   expect(me.ok && me.data.id).toBeDefined()
+ */
+import { type ClientOptions, type Treaty } from "@nifrajs/client";
+import { type CookieJar } from "./cookies.js";
+/** The minimal shape a nifra `server()` app satisfies — its own `fetch`. */
+export interface AppLike {
+    fetch(request: Request): Response | Promise<Response>;
+}
+export interface TestSessionOptions extends Omit<ClientOptions, "fetch"> {
+    /** Origin used to resolve relative paths. Default `"http://nifra.internal"`. */
+    readonly origin?: string;
+    /** Reuse an existing jar (e.g. seed a session cookie, or share one across sessions). */
+    readonly cookies?: CookieJar;
+}
+export interface TestSession<App> {
+    /** The end-to-end-typed in-process client — every call carries + captures cookies. */
+    readonly client: Treaty<App>;
+    /** The jar backing this session — inspect (`cookies.get("sid")`), seed, or `clear()` it. */
+    readonly cookies: CookieJar;
+}
+/** Create a cookie-persisting in-process test client for `app`. */
+export declare function testSession<App extends AppLike>(app: App, options?: TestSessionOptions): TestSession<App>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,aAAa,EAAwB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACvF,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,cAAc,CAAA;AAExD,4EAA4E;AAC5E,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CACtD;AAED,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC;IACtE,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wFAAwF;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAA;CAC7B;AAED,MAAM,WAAW,WAAW,CAAC,GAAG;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAC5B;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,GAAG,SAAS,OAAO,EAC7C,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAAC,GAAG,CAAC,CAUlB"}

package/dist/session.js

@@ -0,0 +1,28 @@
+/**
+ * A stateful, cookie-aware in-process test client. `@nifrajs/client`'s `testClient` already drives an
+ * app's `fetch` with end-to-end types (no server/port/network) — this wraps it with a {@link CookieJar}
+ * that carries `Set-Cookie` across calls, so a login → authenticated-request flow just works.
+ *
+ *   import { testSession } from "@nifrajs/testing"
+ *   import { app } from "../src/app"
+ *
+ *   const { client, cookies } = testSession<typeof app>(app)
+ *   await client.auth.login.post({ email, password })   // Set-Cookie captured
+ *   const me = await client.me.get()                     // Cookie sent automatically
+ *   expect(me.ok && me.data.id).toBeDefined()
+ */
+import { client } from "@nifrajs/client";
+import { cookieJar } from "./cookies.js";
+/** Create a cookie-persisting in-process test client for `app`. */
+export function testSession(app, options = {}) {
+    const { origin = "http://nifra.internal", cookies = cookieJar(), ...clientOptions } = options;
+    const bridge = async (url, init) => {
+        const headers = new Headers(init?.headers);
+        cookies.applyTo(headers);
+        const response = await app.fetch(new Request(url, { ...init, headers }));
+        cookies.store(response);
+        return response;
+    };
+    return { client: client(origin, { ...clientOptions, fetch: bridge }), cookies };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAsB,MAAM,EAA6B,MAAM,iBAAiB,CAAA;AACvF,OAAO,EAAkB,SAAS,EAAE,MAAM,cAAc,CAAA;AAqBxD,mEAAmE;AACnE,MAAM,UAAU,WAAW,CACzB,GAAQ,EACR,UAA8B,EAAE;IAEhC,MAAM,EAAE,MAAM,GAAG,uBAAuB,EAAE,OAAO,GAAG,SAAS,EAAE,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAA;IAC7F,MAAM,MAAM,GAAY,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAC1C,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QACxB,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;QACxE,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACvB,OAAO,QAAQ,CAAA;IACjB,CAAC,CAAA;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAM,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAA;AACtF,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nifrajs/testing",
+  "version": "1.1.0",
+  "description": "Testing helpers for nifra apps — a cookie jar + a cookie-persisting in-process test session on top of @nifrajs/client's testClient, so stateful auth/session flows test as easily as a single request.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "testing",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@nifrajs/client": "1.1.0"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/testing"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/cookies.ts

@@ -0,0 +1,76 @@
+/**
+ * A tiny cookie jar for in-process tests — parses `Set-Cookie` off responses and emits a `Cookie`
+ * request header, so a login → authenticated-request flow works without threading headers by hand. It
+ * honours removal (`Max-Age=0` / a past `Expires`) so logout clears the cookie; other attributes
+ * (Domain/Path/Secure/SameSite) are ignored — everything is same-origin in-process.
+ */
+
+export interface CookieJar {
+  /** The current `Cookie` request-header value (`"a=1; b=2"`, or `""` when empty). */
+  header(): string
+  /** Set the `Cookie` header on `headers` when the jar is non-empty. */
+  applyTo(headers: Headers): void
+  /** Absorb every `Set-Cookie` on a response (setting or, on removal, deleting each). */
+  store(response: { headers: Headers }): void
+  set(name: string, value: string): void
+  get(name: string): string | undefined
+  clear(): void
+  readonly size: number
+}
+
+/** Read `Set-Cookie` values portably: `getSetCookie()` (Bun/Node/edge) with a single-header fallback. */
+function setCookies(headers: Headers): string[] {
+  const withGetter = headers as Headers & { getSetCookie?: () => string[] }
+  if (typeof withGetter.getSetCookie === "function") return withGetter.getSetCookie()
+  const single = headers.get("set-cookie")
+  return single === null ? [] : [single]
+}
+
+function isRemoval(attributes: string): boolean {
+  if (/(^|;)\s*max-age=0(\s|;|$)/.test(attributes)) return true
+  const expires = /expires=([^;]+)/.exec(attributes)
+  if (expires === null) return false
+  const at = Date.parse(expires[1] as string)
+  return !Number.isNaN(at) && at < Date.now()
+}
+
+function parseSetCookie(line: string): { name: string; value: string; remove: boolean } | null {
+  const semicolon = line.indexOf(";")
+  const pair = semicolon === -1 ? line : line.slice(0, semicolon)
+  const equals = pair.indexOf("=")
+  if (equals === -1) return null
+  const name = pair.slice(0, equals).trim()
+  if (name === "") return null
+  const value = pair.slice(equals + 1).trim()
+  const attributes = semicolon === -1 ? "" : line.slice(semicolon + 1).toLowerCase()
+  return { name, value, remove: isRemoval(attributes) }
+}
+
+/** Create an empty cookie jar. */
+export function cookieJar(): CookieJar {
+  const cookies = new Map<string, string>()
+  const header = (): string => [...cookies].map(([name, value]) => `${name}=${value}`).join("; ")
+  return {
+    header,
+    get size() {
+      return cookies.size
+    },
+    set: (name, value) => {
+      cookies.set(name, value)
+    },
+    get: (name) => cookies.get(name),
+    clear: () => cookies.clear(),
+    applyTo: (headers) => {
+      const current = header()
+      if (current !== "") headers.set("cookie", current)
+    },
+    store: (response) => {
+      for (const line of setCookies(response.headers)) {
+        const parsed = parseSetCookie(line)
+        if (parsed === null) continue
+        if (parsed.remove) cookies.delete(parsed.name)
+        else cookies.set(parsed.name, parsed.value)
+      }
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @nifrajs/testing — helpers for testing nifra apps in-process. `@nifrajs/client`'s `testClient` is the
+ * typed, no-network request client (the supertest/inject equivalent); this adds what it doesn't: a
+ * {@link cookieJar} and a cookie-persisting {@link testSession}, so stateful auth/session flows are as
+ * easy to test as a single request.
+ *
+ *   import { testSession } from "@nifrajs/testing"
+ *   const { client, cookies } = testSession<typeof app>(app)
+ */
+
+export { type CookieJar, cookieJar } from "./cookies.ts"
+export { type AppLike, type TestSession, type TestSessionOptions, testSession } from "./session.ts"

package/src/session.ts

@@ -0,0 +1,50 @@
+/**
+ * A stateful, cookie-aware in-process test client. `@nifrajs/client`'s `testClient` already drives an
+ * app's `fetch` with end-to-end types (no server/port/network) — this wraps it with a {@link CookieJar}
+ * that carries `Set-Cookie` across calls, so a login → authenticated-request flow just works.
+ *
+ *   import { testSession } from "@nifrajs/testing"
+ *   import { app } from "../src/app"
+ *
+ *   const { client, cookies } = testSession<typeof app>(app)
+ *   await client.auth.login.post({ email, password })   // Set-Cookie captured
+ *   const me = await client.me.get()                     // Cookie sent automatically
+ *   expect(me.ok && me.data.id).toBeDefined()
+ */
+import { type ClientOptions, client, type FetchFn, type Treaty } from "@nifrajs/client"
+import { type CookieJar, cookieJar } from "./cookies.ts"
+
+/** The minimal shape a nifra `server()` app satisfies — its own `fetch`. */
+export interface AppLike {
+  fetch(request: Request): Response | Promise<Response>
+}
+
+export interface TestSessionOptions extends Omit<ClientOptions, "fetch"> {
+  /** Origin used to resolve relative paths. Default `"http://nifra.internal"`. */
+  readonly origin?: string
+  /** Reuse an existing jar (e.g. seed a session cookie, or share one across sessions). */
+  readonly cookies?: CookieJar
+}
+
+export interface TestSession<App> {
+  /** The end-to-end-typed in-process client — every call carries + captures cookies. */
+  readonly client: Treaty<App>
+  /** The jar backing this session — inspect (`cookies.get("sid")`), seed, or `clear()` it. */
+  readonly cookies: CookieJar
+}
+
+/** Create a cookie-persisting in-process test client for `app`. */
+export function testSession<App extends AppLike>(
+  app: App,
+  options: TestSessionOptions = {},
+): TestSession<App> {
+  const { origin = "http://nifra.internal", cookies = cookieJar(), ...clientOptions } = options
+  const bridge: FetchFn = async (url, init) => {
+    const headers = new Headers(init?.headers)
+    cookies.applyTo(headers)
+    const response = await app.fetch(new Request(url, { ...init, headers }))
+    cookies.store(response)
+    return response
+  }
+  return { client: client<App>(origin, { ...clientOptions, fetch: bridge }), cookies }
+}