@c9up/ream 0.1.26 → 0.1.27

package/src/testing/TestClient.ts

@@ -23,40 +23,24 @@ import {
   type HttpMethod,
   type HttpSender,
   RequestBuilder,
+  type TestResponse,
 } from './RequestBuilder.js'
 
-export interface TestResponse {
-  status: number
-  headers: Dict
-  body: string
-  json<T = unknown>(): T
-}
-
-/**
- * Fluent request builder. Thenable like AdonisJS/japa's api-client: `await
- * client.get('/x')` sends the request, and chaining works on every verb —
- * `await client.get('/x').header('authorization', token)`. The explicit
- * `.send()` is kept for callers that prefer it.
- */
-export interface TestRequestBuilder extends PromiseLike<TestResponse> {
-  /** 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>
-}
+// The raw response shape + the rich response live in ApiResponse.ts and are
+// re-exported here so `@c9up/ream/testing` consumers keep their import path.
+export { ApiResponse, type TestResponse } from './RequestBuilder.js'
 
 /**
  * Named-route manifest — `name → path pattern`, e.g. `{ 'users.show':
  * '/users/:id' }`. Feed `router.namedManifest()` here so `visit()` can resolve
  * named routes without the full Router.
+ *
+ * A value may be a bare path string OR `{ path, method }` — when the method is
+ * present, `visit(name)` uses it (Japa route-registry parity, e.g.
+ * `visit('users.store').json(...).assertCreated()` issues a POST).
  */
-export type RouteManifest = Record<string, string>
+export type RouteEntry = string | { path: string; method?: HttpMethod }
+export type RouteManifest = Record<string, RouteEntry>
 
 export class TestClient {
   #port = 0
@@ -106,29 +90,47 @@ export class TestClient {
     return this
   }
 
-  /** GET request. Returns a chainable, awaitable builder (await sends it). */
-  get(path: string): TestRequestBuilder {
-    return this.request('GET', path)
+  // Verb shortcuts return the RICH builder — the full japa/api-client surface
+  // (assertOk/assertStatus/assertBody/… + auth/csrf) AND awaitable (`await
+  // client.get('/x')` sends and resolves to the response). One unified builder,
+  // no split between `get()` and `fluent()`.
+
+  /** GET request — rich, awaitable builder. */
+  get(path: string): RequestBuilder {
+    return this.fluent('GET', path)
   }
 
-  /** POST request. */
-  post(path: string): TestRequestBuilder {
-    return this.request('POST', path)
+  /** POST request — rich, awaitable builder. */
+  post(path: string): RequestBuilder {
+    return this.fluent('POST', path)
   }
 
-  /** PUT request. */
-  put(path: string): TestRequestBuilder {
-    return this.request('PUT', path)
+  /** PUT request — rich, awaitable builder. */
+  put(path: string): RequestBuilder {
+    return this.fluent('PUT', path)
   }
 
-  /** PATCH request. */
-  patch(path: string): TestRequestBuilder {
-    return this.request('PATCH', path)
+  /** PATCH request — rich, awaitable builder. */
+  patch(path: string): RequestBuilder {
+    return this.fluent('PATCH', path)
   }
 
-  /** DELETE request. Returns a chainable, awaitable builder (await sends it). */
-  delete(path: string): TestRequestBuilder {
-    return this.request('DELETE', path)
+  /** DELETE request — rich, awaitable builder. */
+  delete(path: string): RequestBuilder {
+    return this.fluent('DELETE', path)
+  }
+
+  /**
+   * HEAD request — japa/api-client's `.head()`. Returns the rich builder so you
+   * can assert status/headers (a HEAD response carries headers, no body).
+   */
+  head(path: string): RequestBuilder {
+    return this.fluent('HEAD', path)
+  }
+
+  /** OPTIONS request — japa/api-client's `.options()`. */
+  options(path: string): RequestBuilder {
+    return this.fluent('OPTIONS', path)
   }
 
   /**
@@ -145,6 +147,7 @@ export class TestClient {
         p,
         { ...this.#headers, ...init.headers },
         init.body.toString('utf8'),
+        init.timeoutMs,
       )
     return new RequestBuilder(sender, method, path, this.#auth)
   }
@@ -161,48 +164,20 @@ export class TestClient {
         'TestClient: visit() needs a named-route manifest. Pass `routes: router.namedManifest()` in the client options.',
       )
     }
-    return this.fluent('GET', resolveNamedRoute(this.#routes, name, params))
+    const entry = this.#routes[name]
+    // Method comes from the registry when the entry carries one (Japa parity),
+    // otherwise GET.
+    const method: HttpMethod = typeof entry === 'object' && entry.method ? entry.method : 'GET'
+    return this.fluent(method, resolveNamedRoute(this.#routes, name, params))
   }
 
-  /** 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)
-      },
-      // Thenable: `await client.get('/x')` (or any builder) sends the request,
-      // matching AdonisJS/japa's api-client ergonomics. The `then` IS the public
-      // contract here — awaiting the builder is the documented way to send.
-      // biome-ignore lint/suspicious/noThenProperty: thenable request builder is the intended API (AdonisJS/japa parity) — `await client.get(path)` sends
-      then: (onfulfilled, onrejected) => builder.send().then(onfulfilled, onrejected),
-    }
-
-    return builder
+  /**
+   * Generic request — japa/api-client's `client.request(url, method)` (note the
+   * arg order: URL first, method second, defaulting to GET). Returns the same
+   * rich, awaitable builder as the verb shortcuts.
+   */
+  request(path: string, method: HttpMethod = 'GET'): RequestBuilder {
+    return this.fluent(method, path)
   }
 }
 
@@ -237,12 +212,12 @@ export function resolveNamedRoute(
   name: string,
   params?: Record<string, string>,
 ): string {
-  const pattern = manifest[name]
-  if (pattern === undefined) {
+  const entry = manifest[name]
+  if (entry === undefined) {
     const available = Object.keys(manifest).join(', ') || '(none)'
     throw new Error(`Route '${name}' not found. Available: ${available}`)
   }
-  let url = pattern
+  let url = typeof entry === 'string' ? entry : entry.path
   if (params) {
     for (const [key, value] of Object.entries(params)) {
       const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -264,6 +239,7 @@ async function sendRequest(
   path: string,
   headers: Dict,
   body: string,
+  timeoutMs?: number,
 ): Promise<TestResponse> {
   const { connect } = await import('node:net')
 
@@ -309,8 +285,9 @@ async function sendRequest(
     // 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, () => {
+    // `--timeout=60000` per-test budget without masking real hangs. A
+    // per-request `.timeout(ms)` (Japa) overrides the default.
+    socket.setTimeout(timeoutMs && timeoutMs > 0 ? timeoutMs : 30_000, () => {
       socket.destroy()
       reject(new Error('TestClient request timed out'))
     })

package/src/utils/Macroable.ts

@@ -24,7 +24,7 @@ export type GetterFn = () => unknown
 export class Macroable {
   /** Attach a method to every instance of this class (AdonisJS `macro`). */
   static macro(name: string, fn: MacroFn): void {
-    Object.defineProperty(this.prototype, name, {
+    Object.defineProperty(Macroable.prototype, name, {
       value: fn,
       writable: true,
       configurable: true,
@@ -37,11 +37,11 @@ export class Macroable {
    */
   static getter(name: string, fn: GetterFn, singleton = false): void {
     if (!singleton) {
-      Object.defineProperty(this.prototype, name, { get: fn, configurable: true })
+      Object.defineProperty(Macroable.prototype, name, { get: fn, configurable: true })
       return
     }
     const cacheKey = Symbol(name)
-    Object.defineProperty(this.prototype, name, {
+    Object.defineProperty(Macroable.prototype, name, {
       configurable: true,
       get(this: Record<symbol, unknown>) {
         if (!(cacheKey in this)) {

package/dist/console/CommandRunner.d.ts

@@ -1,18 +0,0 @@
-/**
- * CommandRunner — minimal CLI command framework.
- *
- * Registers commands and dispatches based on argv.
- * Like AdonisJS Ace but lightweight.
- */
-export interface Command {
-    name: string;
-    description: string;
-    run(args: string[], flags: Record<string, string | boolean>): Promise<void>;
-}
-export declare class CommandRunner {
-    #private;
-    register(command: Command): this;
-    handle(argv: string[]): Promise<void>;
-    getCommands(): Map<string, Command>;
-}
-//# sourceMappingURL=CommandRunner.d.ts.map

package/dist/console/CommandRunner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CommandRunner.d.ts","sourceRoot":"","sources":["../../src/console/CommandRunner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5E;AAED,qBAAa,aAAa;;IAGxB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAK1B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B3C,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;CAGpC"}

package/dist/console/CommandRunner.js

@@ -1,65 +0,0 @@
-/**
- * CommandRunner — minimal CLI command framework.
- *
- * Registers commands and dispatches based on argv.
- * Like AdonisJS Ace but lightweight.
- */
-export class CommandRunner {
-    #commands = new Map();
-    register(command) {
-        this.#commands.set(command.name, command);
-        return this;
-    }
-    async handle(argv) {
-        const { commandName, args, flags } = parseArgv(argv);
-        if (!commandName || commandName === 'help') {
-            this.#printHelp();
-            return;
-        }
-        const command = this.#commands.get(commandName);
-        if (!command) {
-            console.error(`Unknown command: ${commandName}`);
-            console.error(`Run without arguments to see available commands.`);
-            process.exitCode = 1;
-            return;
-        }
-        await command.run(args, flags);
-    }
-    #printHelp() {
-        console.log('\nAvailable commands:\n');
-        for (const [name, cmd] of this.#commands) {
-            console.log(`  ${name.padEnd(25)} ${cmd.description}`);
-        }
-        console.log('');
-    }
-    getCommands() {
-        return new Map(this.#commands);
-    }
-}
-function parseArgv(argv) {
-    const flags = {};
-    const positional = [];
-    for (const arg of argv) {
-        if (arg.startsWith('--')) {
-            const eqIdx = arg.indexOf('=');
-            if (eqIdx !== -1) {
-                flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
-            }
-            else {
-                flags[arg.slice(2)] = true;
-            }
-        }
-        else if (arg.startsWith('-') && arg.length === 2) {
-            flags[arg.slice(1)] = true;
-        }
-        else {
-            positional.push(arg);
-        }
-    }
-    return {
-        commandName: positional[0],
-        args: positional.slice(1),
-        flags,
-    };
-}
-//# sourceMappingURL=CommandRunner.js.map

package/dist/console/CommandRunner.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"CommandRunner.js","sourceRoot":"","sources":["../../src/console/CommandRunner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,OAAO,aAAa;IACxB,SAAS,GAAyB,IAAI,GAAG,EAAE,CAAA;IAE3C,QAAQ,CAAC,OAAgB;QACvB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACzC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAc;QACzB,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;QAEpD,IAAI,CAAC,WAAW,IAAI,WAAW,KAAK,MAAM,EAAE,CAAC;YAC3C,IAAI,CAAC,UAAU,EAAE,CAAA;YACjB,OAAM;QACR,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,oBAAoB,WAAW,EAAE,CAAC,CAAA;YAChD,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAA;YACjE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;YACpB,OAAM;QACR,CAAC;QAED,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAChC,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAA;QACtC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACzC,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC,CAAA;QACxD,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IACjB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAChC,CAAC;CACF;AAED,SAAS,SAAS,CAAC,IAAc;IAK/B,MAAM,KAAK,GAAqC,EAAE,CAAA;IAClD,MAAM,UAAU,GAAa,EAAE,CAAA;IAE/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YAC9B,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;gBACjB,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;YACnD,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;YAC5B,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;QAC5B,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO;QACL,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;QAC1B,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QACzB,KAAK;KACN,CAAA;AACH,CAAC"}

package/src/console/CommandRunner.ts

@@ -1,82 +0,0 @@
-/**
- * CommandRunner — minimal CLI command framework.
- *
- * Registers commands and dispatches based on argv.
- * Like AdonisJS Ace but lightweight.
- */
-
-export interface Command {
-  name: string
-  description: string
-  run(args: string[], flags: Record<string, string | boolean>): Promise<void>
-}
-
-export class CommandRunner {
-  #commands: Map<string, Command> = new Map()
-
-  register(command: Command): this {
-    this.#commands.set(command.name, command)
-    return this
-  }
-
-  async handle(argv: string[]): Promise<void> {
-    const { commandName, args, flags } = parseArgv(argv)
-
-    if (!commandName || commandName === 'help') {
-      this.#printHelp()
-      return
-    }
-
-    const command = this.#commands.get(commandName)
-    if (!command) {
-      console.error(`Unknown command: ${commandName}`)
-      console.error(`Run without arguments to see available commands.`)
-      process.exitCode = 1
-      return
-    }
-
-    await command.run(args, flags)
-  }
-
-  #printHelp(): void {
-    console.log('\nAvailable commands:\n')
-    for (const [name, cmd] of this.#commands) {
-      console.log(`  ${name.padEnd(25)} ${cmd.description}`)
-    }
-    console.log('')
-  }
-
-  getCommands(): Map<string, Command> {
-    return new Map(this.#commands)
-  }
-}
-
-function parseArgv(argv: string[]): {
-  commandName: string | undefined
-  args: string[]
-  flags: Record<string, string | boolean>
-} {
-  const flags: Record<string, string | boolean> = {}
-  const positional: string[] = []
-
-  for (const arg of argv) {
-    if (arg.startsWith('--')) {
-      const eqIdx = arg.indexOf('=')
-      if (eqIdx !== -1) {
-        flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1)
-      } else {
-        flags[arg.slice(2)] = true
-      }
-    } else if (arg.startsWith('-') && arg.length === 2) {
-      flags[arg.slice(1)] = true
-    } else {
-      positional.push(arg)
-    }
-  }
-
-  return {
-    commandName: positional[0],
-    args: positional.slice(1),
-    flags,
-  }
-}