@c9up/ream 0.1.3

package/src/testing/RequestBuilder.ts

@@ -0,0 +1,275 @@
+import type { TestResponse } from './TestClient.js'
+
+/**
+ * Fluent HTTP request builder with assertion methods.
+ *
+ *   await client
+ *     .fluent('GET', '/api/users/42')
+ *     .withAuth(user)
+ *     .expectStatus(200)
+ *     .expectJson({ id: 42 })
+ *
+ * The builder chains: setters return `this`, assertion methods send the
+ * request on first call (memoised) and return a `Promise<this>` so further
+ * assertions can be awaited or chained via `await`.
+ */
+
+export interface AuthSubject {
+  /** String or numeric user id — used by `withAuth` / `asUser` to sign the session. */
+  id: string | number
+  /** Optional custom headers added to the request (e.g. tenant markers). */
+  extraHeaders?: Record<string, string>
+}
+
+export interface AuthStrategy {
+  /** Compute the headers Warden expects for this user (Bearer token / session cookie / ...). */
+  headersFor(subject: AuthSubject): Record<string, string> | Promise<Record<string, string>>
+  /** Compute cookies for session-based strategies. */
+  cookiesFor?(subject: AuthSubject): Record<string, string> | Promise<Record<string, string>>
+}
+
+/** Assertion failure — plain Error so tests see a clean stack trace. */
+class ExpectationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ExpectationError'
+  }
+}
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+/**
+ * Internal low-level sender — matches what the TestClient exposes.
+ * Accepting it as an injected callable keeps RequestBuilder framework-agnostic.
+ */
+export type HttpSender = (
+  method: HttpMethod,
+  path: string,
+  init: {
+    headers: Record<string, string>
+    body: Buffer
+  },
+) => Promise<TestResponse>
+
+export class RequestBuilder {
+  #sender: HttpSender
+  #method: HttpMethod
+  #path: string
+  #headers: Record<string, string> = {}
+  #body: Buffer = Buffer.alloc(0)
+  #cookies: Record<string, string> = {}
+  #authStrategy: AuthStrategy | null
+  #pendingAuth: AuthSubject | null = null
+  #sent: Promise<TestResponse> | null = null
+
+  constructor(
+    sender: HttpSender,
+    method: HttpMethod,
+    path: string,
+    authStrategy: AuthStrategy | null = null,
+  ) {
+    this.#sender = sender
+    this.#method = method
+    this.#path = path
+    this.#authStrategy = authStrategy
+  }
+
+  headers(map: Record<string, string>): this {
+    for (const [k, v] of Object.entries(map)) {
+      this.#headers[k.toLowerCase()] = v
+    }
+    return this
+  }
+
+  header(name: string, value: string): this {
+    this.#headers[name.toLowerCase()] = value
+    return this
+  }
+
+  json(data: unknown): this {
+    this.#body = Buffer.from(JSON.stringify(data), 'utf8')
+    this.#headers['content-type'] = 'application/json'
+    return this
+  }
+
+  body(data: Buffer | string, contentType?: string): this {
+    this.#body = typeof data === 'string' ? Buffer.from(data, 'utf8') : data
+    if (contentType) this.#headers['content-type'] = contentType
+    return this
+  }
+
+  form(data: Record<string, string>): this {
+    const pairs = Object.entries(data).map(
+      ([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`,
+    )
+    this.#body = Buffer.from(pairs.join('&'), 'utf8')
+    this.#headers['content-type'] = 'application/x-www-form-urlencoded'
+    return this
+  }
+
+  cookies(map: Record<string, string>): this {
+    Object.assign(this.#cookies, map)
+    return this
+  }
+
+  cookie(name: string, value: string): this {
+    this.#cookies[name] = value
+    return this
+  }
+
+  /**
+   * Attach auth for a user. Uses the strategy passed to `client`'s `auth`
+   * option — Warden's session/JWT/API-key strategy decides the header/cookie
+   * shape. Without a strategy, throws at send time.
+   */
+  withAuth(subject: AuthSubject): this {
+    this.#pendingAuth = subject
+    return this
+  }
+
+  /** Shortcut for `withAuth({ id: userId })` — user is identified by id only. */
+  asUser(userId: string | number): this {
+    this.#pendingAuth = { id: userId }
+    return this
+  }
+
+  /** Fire the request (once) and return the raw response. Idempotent. */
+  send(): Promise<TestResponse> {
+    if (this.#sent === null) this.#sent = this.#execute()
+    return this.#sent
+  }
+
+  async expectStatus(code: number): Promise<this> {
+    const res = await this.send()
+    if (res.status !== code) {
+      throw new ExpectationError(
+        `Expected status ${code}, got ${res.status}. Body: ${capBody(res.body)}`,
+      )
+    }
+    return this
+  }
+
+  async expectHeader(name: string, value: string | RegExp): Promise<this> {
+    const res = await this.send()
+    const actual = res.headers[name.toLowerCase()]
+    if (actual === undefined) {
+      throw new ExpectationError(
+        `Expected header ${name}, not present in response headers: ${Object.keys(res.headers).join(', ')}`,
+      )
+    }
+    if (value instanceof RegExp) {
+      if (!value.test(actual)) {
+        throw new ExpectationError(`Expected header ${name} to match ${value}, got "${actual}"`)
+      }
+    } else if (actual !== value) {
+      throw new ExpectationError(`Expected header ${name} = "${value}", got "${actual}"`)
+    }
+    return this
+  }
+
+  async expectCookie(name: string, value?: string | RegExp): Promise<this> {
+    const res = await this.send()
+    const setCookie = res.headers['set-cookie']
+    if (!setCookie) {
+      throw new ExpectationError(`Expected cookie ${name}, but no Set-Cookie header was returned`)
+    }
+    const cookies = setCookie.split(/,(?=\s*\w+=)/)
+    const match = cookies.find((c) => c.trimStart().startsWith(`${name}=`))
+    if (!match) {
+      throw new ExpectationError(`Expected cookie ${name}, not found in: ${setCookie}`)
+    }
+    if (value === undefined) return this
+    const rawVal = match.split(';')[0]?.split('=')[1] ?? ''
+    if (value instanceof RegExp) {
+      if (!value.test(rawVal)) {
+        throw new ExpectationError(`Expected cookie ${name} to match ${value}, got "${rawVal}"`)
+      }
+    } else if (rawVal !== value) {
+      throw new ExpectationError(`Expected cookie ${name} = "${value}", got "${rawVal}"`)
+    }
+    return this
+  }
+
+  async expectJson(expected: unknown): Promise<this> {
+    const res = await this.send()
+    let actual: unknown
+    try {
+      actual = res.json()
+    } catch (err) {
+      throw new ExpectationError(
+        `Expected JSON body, got non-JSON. Body: ${capBody(res.body)} (parse error: ${err instanceof Error ? err.message : String(err)})`,
+      )
+    }
+    if (!partialMatch(actual, expected)) {
+      throw new ExpectationError(
+        `JSON partial match failed.\nExpected (partial): ${JSON.stringify(expected)}\nActual: ${capBody(JSON.stringify(actual))}`,
+      )
+    }
+    return this
+  }
+
+  async #execute(): Promise<TestResponse> {
+    // Resolve auth before sending.
+    if (this.#pendingAuth !== null) {
+      if (!this.#authStrategy) {
+        throw new Error(
+          'RequestBuilder: `withAuth()` / `asUser()` called but no AuthStrategy was provided via the client `auth` option.',
+        )
+      }
+      const authHeaders = await this.#authStrategy.headersFor(this.#pendingAuth)
+      for (const [k, v] of Object.entries(authHeaders)) {
+        this.#headers[k.toLowerCase()] = v
+      }
+      if (this.#authStrategy.cookiesFor) {
+        const authCookies = await this.#authStrategy.cookiesFor(this.#pendingAuth)
+        Object.assign(this.#cookies, authCookies)
+      }
+      if (this.#pendingAuth.extraHeaders) {
+        for (const [k, v] of Object.entries(this.#pendingAuth.extraHeaders)) {
+          this.#headers[k.toLowerCase()] = v
+        }
+      }
+    }
+
+    // Serialise cookies into a single `Cookie:` header.
+    const cookieEntries = Object.entries(this.#cookies)
+    if (cookieEntries.length > 0) {
+      this.#headers.cookie = cookieEntries.map(([k, v]) => `${k}=${v}`).join('; ')
+    }
+
+    return this.#sender(this.#method, this.#path, {
+      headers: this.#headers,
+      body: this.#body,
+    })
+  }
+}
+
+function capBody(s: string, max = 512): string {
+  return s.length <= max ? s : `${s.slice(0, max)}...[truncated]`
+}
+
+/** Narrowing guard — a non-null, non-array object usable as a string map. */
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null && !Array.isArray(x)
+}
+
+/**
+ * Partial deep-match. For objects, every key in `expected` must match in
+ * `actual`. For arrays, every element in `expected` must match SOMEWHERE in
+ * `actual` (order-independent). Primitives compared by strict equality.
+ */
+export function partialMatch(actual: unknown, expected: unknown): boolean {
+  if (expected === null || expected === undefined) {
+    return actual === expected
+  }
+  if (typeof expected !== 'object') return actual === expected
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) return false
+    return expected.every((want) => actual.some((have) => partialMatch(have, want)))
+  }
+  if (!isRecord(actual) || !isRecord(expected)) return false
+  for (const key of Object.keys(expected)) {
+    if (!partialMatch(actual[key], expected[key])) return false
+  }
+  return true
+}

package/src/testing/TestClient.ts

@@ -0,0 +1,344 @@
+/**
+ * TestClient — supertest-like HTTP client for integration testing.
+ *
+ * Boots a Ream application on an ephemeral port and provides a fluent API
+ * for sending requests and asserting responses.
+ *
+ * Usage:
+ *   const client = new TestClient(createApp)
+ *   await client.boot()
+ *   const res = await client.get('/api/health')
+ *   expect(res.status).toBe(200)
+ *   await client.close()
+ *
+ * Or with the helper:
+ *   const client = await createTestClient(createApp)
+ *   const res = await client.post('/api/users').json({ name: 'Alice' }).send()
+ *   await client.close()
+ */
+
+import type { Dict } from '../types/helpers.js'
+import {
+  type AuthStrategy,
+  type HttpMethod,
+  type HttpSender,
+  RequestBuilder,
+} from './RequestBuilder.js'
+
+export interface TestResponse {
+  status: number
+  headers: Dict
+  body: string
+  json<T = unknown>(): T
+}
+
+export interface TestRequestBuilder {
+  /** Set a request header. */
+  header(name: string, value: string): TestRequestBuilder
+  /** Set the request body as JSON. */
+  json(data: unknown): TestRequestBuilder
+  /** Set a raw string body with optional content type. */
+  body(content: string, contentType?: string): TestRequestBuilder
+  /** Set a cookie. */
+  cookie(name: string, value: string): TestRequestBuilder
+  /** Send the request and return the response. */
+  send(): Promise<TestResponse>
+}
+
+export class TestClient {
+  #port = 0
+  #headers: Dict = {}
+  #bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>
+  #auth: AuthStrategy | null
+
+  constructor(
+    bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>,
+    options: { auth?: AuthStrategy } = {},
+  ) {
+    this.#bootFn = bootFn
+    this.#auth = options.auth ?? null
+  }
+
+  #server: { port: number; close: () => Promise<void> | void } | null = null
+
+  /** Boot the application on a random port. */
+  async boot(): Promise<void> {
+    this.#server = await this.#bootFn(0)
+    this.#port = this.#server.port
+  }
+
+  /** Close the server. */
+  async close(): Promise<void> {
+    if (this.#server) {
+      await this.#server.close()
+      this.#server = null
+    }
+  }
+
+  /**
+   * Ephemeral port the booted server bound to. Useful for long-lived
+   * connections (SSE / WebSocket) that the fluent buffered request
+   * surface can't model — open them with `fetch` against
+   * `http://127.0.0.1:${client.port}/...`. Returns 0 before `boot()`.
+   */
+  get port(): number {
+    return this.#port
+  }
+
+  /** Set a default header for all requests. */
+  withHeader(name: string, value: string): this {
+    this.#headers[name.toLowerCase()] = value
+    return this
+  }
+
+  /** GET request. */
+  get(path: string): Promise<TestResponse> {
+    return this.request('GET', path).send()
+  }
+
+  /** POST request. */
+  post(path: string): TestRequestBuilder {
+    return this.request('POST', path)
+  }
+
+  /** PUT request. */
+  put(path: string): TestRequestBuilder {
+    return this.request('PUT', path)
+  }
+
+  /** PATCH request. */
+  patch(path: string): TestRequestBuilder {
+    return this.request('PATCH', path)
+  }
+
+  /** DELETE request. */
+  delete(path: string): Promise<TestResponse> {
+    return this.request('DELETE', path).send()
+  }
+
+  /**
+   * Build a request with the rich fluent surface: chained assertions
+   * (`expectStatus` / `expectJson` / `expectHeader` / `expectCookie`), auth
+   * injection (`withAuth` / `asUser`, needs the `auth` client option), and
+   * `form()`. The lower-level `request()` (below) stays for raw control.
+   */
+  fluent(method: HttpMethod, path: string): RequestBuilder {
+    const sender: HttpSender = (m, p, init) =>
+      sendRequest(
+        this.#port,
+        m,
+        p,
+        { ...this.#headers, ...init.headers },
+        init.body.toString('utf8'),
+      )
+    return new RequestBuilder(sender, method, path, this.#auth)
+  }
+
+  /** Build a request with the low-level fluent API. */
+  request(method: string, path: string): TestRequestBuilder {
+    const headers: Dict = { ...this.#headers }
+    let bodyContent = ''
+    const cookies: string[] = []
+
+    const builder: TestRequestBuilder = {
+      header(name: string, value: string) {
+        headers[name.toLowerCase()] = value
+        return builder
+      },
+      json(data: unknown) {
+        bodyContent = JSON.stringify(data)
+        headers['content-type'] = 'application/json'
+        return builder
+      },
+      body(content: string, contentType?: string) {
+        bodyContent = content
+        if (contentType) headers['content-type'] = contentType
+        return builder
+      },
+      cookie(name: string, value: string) {
+        cookies.push(`${name}=${value}`)
+        return builder
+      },
+      send: async () => {
+        if (cookies.length > 0) {
+          headers.cookie = cookies.join('; ')
+        }
+        return sendRequest(this.#port, method, path, headers, bodyContent)
+      },
+    }
+
+    return builder
+  }
+}
+
+/** Create and boot a test client in one call. */
+export async function createTestClient(
+  bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>,
+  options?: { auth?: AuthStrategy },
+): Promise<TestClient> {
+  const client = new TestClient(bootFn, options)
+  await client.boot()
+  return client
+}
+
+export {
+  type AuthStrategy,
+  type AuthSubject,
+  type HttpMethod,
+  type HttpSender,
+  partialMatch,
+  RequestBuilder,
+} from './RequestBuilder.js'
+
+/** Send an HTTP request using raw TCP (no external dependencies). */
+async function sendRequest(
+  port: number,
+  method: string,
+  path: string,
+  headers: Dict,
+  body: string,
+): Promise<TestResponse> {
+  const { connect } = await import('node:net')
+
+  return new Promise((resolve, reject) => {
+    const socket = connect({ host: '127.0.0.1', port }, () => {
+      // Build HTTP/1.1 request
+      const headerLines = Object.entries(headers)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join('\r\n')
+
+      const contentLength = Buffer.byteLength(body, 'utf8')
+
+      let request = `${method} ${path} HTTP/1.1\r\n`
+      request += `Host: localhost:${port}\r\n`
+      request += `Connection: close\r\n`
+      if (contentLength > 0) {
+        request += `Content-Length: ${contentLength}\r\n`
+      }
+      if (headerLines) {
+        request += `${headerLines}\r\n`
+      }
+      request += '\r\n'
+      request += body
+
+      socket.write(request)
+    })
+
+    const chunks: Buffer[] = []
+    socket.on('data', (chunk) => chunks.push(chunk))
+    socket.on('end', () => {
+      // Keep the wire bytes as a Buffer through parseHttpResponse — chunked
+      // decoding has to count bytes (per RFC 7230), not UTF-16 code units.
+      // Converting to a string here used to truncate non-ASCII and binary
+      // chunked responses (é / emoji / images / PDF).
+      resolve(parseHttpResponse(Buffer.concat(chunks)))
+    })
+    socket.on('error', reject)
+
+    // Socket inactivity timeout. 5s was too tight for real e2e flows —
+    // signup hashes a password with argon2 (~50-200ms), then an INSERT
+    // crosses sqlite's WAL fsync, then JWT sign + serialize. Under
+    // cross-package CPU pressure (parallel helix workers, NAPI
+    // tokio runtimes) the cumulative latency exceeded 5s ~30% of runs
+    // and surfaced as flaky `bob accepts` / `non-member 403` failures
+    // in kitchen-sink's workspace.test.ts. 30s matches the helix
+    // `--timeout=60000` per-test budget without masking real hangs.
+    socket.setTimeout(30_000, () => {
+      socket.destroy()
+      reject(new Error('TestClient request timed out'))
+    })
+  })
+}
+
+/**
+ * Parse a raw HTTP response. Accepts the wire bytes (Buffer) or a UTF-8
+ * string for back-compat with older test callers. Chunked decoding runs on
+ * the Buffer to keep byte-counting honest — HTTP counts bytes (RFC 7230),
+ * not UTF-16 code units, so doing the work on a `.toString('utf8')` string
+ * silently truncated non-ASCII and binary responses.
+ */
+export function parseHttpResponse(raw: string | Buffer): TestResponse {
+  const buf = typeof raw === 'string' ? Buffer.from(raw, 'utf8') : raw
+  const HEADER_TERM = Buffer.from('\r\n\r\n', 'ascii')
+  const headerEnd = buf.indexOf(HEADER_TERM)
+  if (headerEnd === -1) {
+    const body = buf.toString('utf8')
+    return { status: 0, headers: {}, body, json: () => JSON.parse(body) }
+  }
+
+  // HTTP headers are ASCII (RFC 7230 §3.2); decoding via 'ascii' is safe and
+  // makes any non-ASCII byte show as a question-mark, surfacing protocol bugs
+  // instead of silently smuggling them.
+  const headerSection = buf.subarray(0, headerEnd).toString('ascii')
+  let bodyBuffer = buf.subarray(headerEnd + HEADER_TERM.length)
+
+  const lines = headerSection.split('\r\n')
+  const statusLine = lines[0] ?? ''
+  const statusMatch = statusLine.match(/HTTP\/\d+\.\d+ (\d+)/)
+  const status = statusMatch ? Number.parseInt(statusMatch[1], 10) : 0
+
+  const headers: Dict = {}
+  for (let i = 1; i < lines.length; i++) {
+    const colonIdx = lines[i].indexOf(':')
+    if (colonIdx === -1) continue
+    const key = lines[i].slice(0, colonIdx).trim().toLowerCase()
+    const value = lines[i].slice(colonIdx + 1).trim()
+    headers[key] = value
+  }
+
+  // RFC 7230 §4.1: when Transfer-Encoding includes `chunked`, the message body
+  // is a sequence of `<size-hex>[;ext]\r\n<bytes>\r\n` chunks terminated by
+  // `0\r\n\r\n`. Decode on the Buffer so chunk sizes (bytes) match slice
+  // boundaries — character-counting corrupts é / emoji / binary payloads.
+  const transferEncoding = headers['transfer-encoding'] ?? ''
+  if (
+    transferEncoding
+      .toLowerCase()
+      .split(',')
+      .map((s) => s.trim())
+      .includes('chunked')
+  ) {
+    bodyBuffer = decodeChunked(bodyBuffer)
+    delete headers['transfer-encoding']
+  }
+
+  const body = bodyBuffer.toString('utf8')
+  return {
+    status,
+    headers,
+    body,
+    json<T = unknown>(): T {
+      return JSON.parse(body)
+    },
+  }
+}
+
+/**
+ * Decode an HTTP/1.1 chunked-transfer body. Operates on a Buffer because
+ * chunk sizes are byte counts per RFC 7230 — character-counting silently
+ * corrupts non-ASCII / binary responses. Tolerant: stops at the first
+ * malformed chunk header rather than throwing — surfacing a partial body is
+ * more useful for a failing test assertion than swallowing the whole
+ * response.
+ */
+function decodeChunked(raw: Buffer): Buffer {
+  const CRLF = Buffer.from('\r\n', 'ascii')
+  const out: Buffer[] = []
+  let i = 0
+  while (i < raw.length) {
+    const lineEnd = raw.indexOf(CRLF, i)
+    if (lineEnd === -1) break
+    const sizeStr = raw.subarray(i, lineEnd).toString('ascii').split(';')[0]?.trim() ?? ''
+    const size = Number.parseInt(sizeStr, 16)
+    if (!Number.isFinite(size) || size < 0) break
+    i = lineEnd + CRLF.length
+    if (size === 0) break
+    if (i + size > raw.length) {
+      out.push(raw.subarray(i))
+      break
+    }
+    out.push(raw.subarray(i, i + size))
+    i += size + CRLF.length // chunk + trailing \r\n
+  }
+  return Buffer.concat(out)
+}

package/src/types/helpers.ts

@@ -0,0 +1,52 @@
+/**
+ * Type helpers — utility types for the Ream framework.
+ */
+
+/**
+ * Infer route parameters from a route pattern string.
+ *
+ * Usage:
+ *   type Params = InferRouteParams<'/users/:id/posts/:postId'>
+ *   // => { id: string; postId: string }
+ */
+export type InferRouteParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
+  ? { [K in Param | keyof InferRouteParams<`/${Rest}`>]: string }
+  : T extends `${string}:${infer Param}`
+    ? { [K in Param]: string }
+    : Record<string, never>
+
+/** Accept a single value or an array. */
+export type OneOrMore<T> = T | T[]
+
+/** Create a nominal/opaque type from a base type. */
+export type Opaque<Base, Tag extends string> = Base & { readonly __tag: Tag }
+
+/** Unwrap an opaque type back to its base. */
+export type UnwrapOpaque<T> = T extends Opaque<infer Base, string> ? Base : T
+
+/** Accept sync or async values. */
+export type AsyncOrSync<T> = T | Promise<T>
+
+/** Constructor type. */
+export type Constructor<T = unknown, Args extends unknown[] = unknown[]> = new (...args: Args) => T
+
+/** Abstract constructor type. */
+export type AbstractConstructor<T = unknown> = abstract new (...args: unknown[]) => T
+
+/** Extract only function properties from a type. */
+export type ExtractFunctions<T, Ignore extends keyof T = never> = {
+  [K in Exclude<keyof T, Ignore>]: T[K] extends (...args: unknown[]) => unknown ? K : never
+}[Exclude<keyof T, Ignore>]
+
+/** Prettify a type intersection for better IDE display. */
+export type Prettify<T> = { [K in keyof T]: T[K] } & {}
+
+/**
+ * String-keyed bag of values — the recurring HTTP-shaped objects:
+ * headers, cookies, query params, route params, env vars, form fields...
+ *
+ * Defaults to a string→string map (the most common case, and what
+ * `Record<string, string>` was being repeated for). Pass a value type
+ * explicitly when needed: `Dict<unknown>`, `Dict<number>`, ...
+ */
+export type Dict<V = string> = Record<string, V>

package/swcrc.app.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/swcrc",
+  "jsc": {
+    "parser": {
+      "syntax": "typescript",
+      "decorators": true
+    },
+    "transform": {
+      "legacyDecorator": true,
+      "decoratorMetadata": true
+    },
+    "target": "es2022"
+  },
+  "module": {
+    "type": "es6"
+  }
+}