@c9up/ream 0.1.31 → 0.1.33

package/src/testing/RequestBuilder.ts

@@ -46,6 +46,35 @@ export interface AuthSubject {
   extraHeaders?: Record<string, string>
 }
 
+/**
+ * What a guard answers when asked to authenticate a test client
+ * (AdonisJS `AuthClientResponse`).
+ */
+export interface ClientAuthResponse {
+  headers?: Record<string, string>
+  session?: Record<string, unknown>
+  cookies?: Record<string, string>
+}
+
+/**
+ * The little `loginAs()` needs of a guard.
+ *
+ * Structurally typed: the test client must not import warden, and an app with
+ * its own guard satisfies this by exposing the same method.
+ */
+export interface ClientAuthenticatable {
+  authenticateAsClient(...args: never[]): ClientAuthResponse | Promise<ClientAuthResponse>
+}
+
+/**
+ * Persists session values for a test request and returns the cookie that
+ * addresses them. Given the session driver, it writes an entry and hands back
+ * `{ <cookieName>: <sessionId> }`.
+ */
+export type SessionSeeder = (
+  values: Record<string, unknown>,
+) => Record<string, string> | Promise<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>>
@@ -156,7 +185,12 @@ export class RequestBuilder {
   #cookies: Record<string, string> = {}
   #query = new URLSearchParams()
   #authStrategy: AuthStrategy | null
+  #sessionSeeder: SessionSeeder | null
   #pendingAuth: AuthSubject | null = null
+  #pendingClientAuth: {
+    guard: ClientAuthenticatable
+    args: never[]
+  } | null = null
   #timeoutMs: number | undefined
   #maxRedirects = DEFAULT_MAX_REDIRECTS
   #sent: Promise<ApiResponse> | null = null
@@ -170,11 +204,13 @@ export class RequestBuilder {
     method: HttpMethod,
     path: string,
     authStrategy: AuthStrategy | null = null,
+    sessionSeeder: SessionSeeder | null = null,
   ) {
     this.#sender = sender
     this.#method = method
     this.#path = path
     this.#authStrategy = authStrategy
+    this.#sessionSeeder = sessionSeeder
     applyRequestExtensions(this)
   }
 
@@ -421,6 +457,23 @@ export class RequestBuilder {
     return this
   }
 
+  /**
+   * Send this request as an authenticated user (AdonisJS `loginAs`).
+   *
+   *     await client.get('/dashboard').loginAs(sessionGuard, user)
+   *     await client.get('/api/me').loginAs(jwtGuard, user)
+   *     await client.get('/admin').loginAs(basicGuard, 'ada', 'secret')
+   *
+   * The GUARD answers what to send — a header, a session entry, a cookie — so
+   * the test never reproduces how that guard authenticates. A test that forges
+   * its own header proves only that the forgery works; this one travels the
+   * same verification path as production.
+   */
+  loginAs(guard: ClientAuthenticatable, ...args: never[]): this {
+    this.#pendingClientAuth = { guard, args }
+    return this
+  }
+
   /** Fire the request (once) and return the rich response. Idempotent. */
   send(): Promise<ApiResponse> {
     if (this.#sent === null) this.#sent = this.#execute()
@@ -560,6 +613,29 @@ export class RequestBuilder {
       }
     }
 
+    if (this.#pendingClientAuth !== null) {
+      const { guard, args } = this.#pendingClientAuth
+      const answer = await guard.authenticateAsClient(...args)
+      for (const [k, v] of Object.entries(answer.headers ?? {})) {
+        this.#headers[k.toLowerCase()] = v
+      }
+      Object.assign(this.#cookies, answer.cookies ?? {})
+      // A session guard answers with session VALUES, which only something
+      // holding the session driver can persist. Without a seeder the request
+      // would go out unauthenticated and the test would fail somewhere far from
+      // the cause — so say it here instead.
+      if (answer.session && Object.keys(answer.session).length > 0) {
+        if (!this.#sessionSeeder) {
+          throw new Error(
+            'RequestBuilder: `loginAs()` was given a session-based guard, which needs a session to be written before the request. ' +
+              'Pass `sessionSeeder` in the client options (it receives the values and returns the session cookie).',
+          )
+        }
+        const cookie = await this.#sessionSeeder(answer.session)
+        Object.assign(this.#cookies, cookie)
+      }
+    }
+
     // Multipart parts (.field()/.file()) take precedence over any body set by
     // json()/form()/body(); encode them with a fresh boundary at send time.
     if (this.#multipart.length > 0) {

package/src/testing/TestClient.ts

@@ -23,6 +23,7 @@ import {
   type HttpMethod,
   type HttpSender,
   RequestBuilder,
+  type SessionSeeder,
   type TestResponse,
 } from './RequestBuilder.js'
 
@@ -47,15 +48,22 @@ export class TestClient {
   #headers: Dict = {}
   #bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>
   #auth: AuthStrategy | null
+  #sessionSeeder: SessionSeeder | null
   #routes: RouteManifest | null
 
   constructor(
     bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>,
-    options: { auth?: AuthStrategy; routes?: RouteManifest } = {},
+    options: {
+      auth?: AuthStrategy
+      routes?: RouteManifest
+      /** Writes session values for `loginAs()` with a session-based guard. */
+      sessionSeeder?: SessionSeeder
+    } = {},
   ) {
     this.#bootFn = bootFn
     this.#auth = options.auth ?? null
     this.#routes = options.routes ?? null
+    this.#sessionSeeder = options.sessionSeeder ?? null
   }
 
   #server: { port: number; close: () => Promise<void> | void } | null = null
@@ -149,7 +157,7 @@ export class TestClient {
         init.body.toString('utf8'),
         init.timeoutMs,
       )
-    return new RequestBuilder(sender, method, path, this.#auth)
+    return new RequestBuilder(sender, method, path, this.#auth, this.#sessionSeeder)
   }
 
   /**

package/src/types/helpers.ts

@@ -28,7 +28,10 @@ export type UnwrapOpaque<T> = T extends Opaque<infer Base, string> ? Base : T
 export type AsyncOrSync<T> = T | Promise<T>
 
 /** Constructor type. */
-export type Constructor<T = unknown, Args extends unknown[] = unknown[]> = new (...args: Args) => T
+// The default `Args` is `never[]`, not `unknown[]`: parameters are
+// contravariant, so only a rest of `never` accepts EVERY concrete parameter
+// list. Pass `Args` explicitly when you need to call the constructor.
+export type Constructor<T = unknown, Args extends unknown[] = never[]> = new (...args: Args) => T
 
 /** Abstract constructor type. */
 export type AbstractConstructor<T = unknown> = abstract new (...args: unknown[]) => T

package/src/utils/Macroable.ts

@@ -1,3 +1,9 @@
+// biome-ignore-all lint/complexity/noThisInStatic: `this` inside a static method
+// IS the calling class, and that is the whole mechanism here — `this.prototype`
+// is what scopes a macro to the subclass that declared it. Using
+// `Macroable.prototype` put every macro on all eight subclasses at once.
+// Removing the `this` reintroduces that bug.
+
 /**
  * Macroable — lets a package extend a class at runtime with extra methods
  * (`macro`) and computed properties (`getter`), AdonisJS-style. A framework
@@ -22,9 +28,17 @@ export type MacroFn = (...args: unknown[]) => unknown
 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(Macroable.prototype, name, {
+  /**
+   * Attach a method to every instance of THIS class (AdonisJS `macro`).
+   *
+   * `this.prototype`, not `Macroable.prototype`: eight classes extend this one,
+   * and defining on the base put every macro on all of them — a
+   * `Response.macro('json', …)` also landed on `Request`, `Router` and
+   * `HttpContext`, and two subclasses declaring the same name clobbered each
+   * other silently.
+   */
+  static macro(this: typeof Macroable, name: string, fn: MacroFn): void {
+    Object.defineProperty(this.prototype, name, {
       value: fn,
       writable: true,
       configurable: true,
@@ -32,16 +46,17 @@ export class Macroable {
   }
 
   /**
-   * Attach a computed property to every instance (AdonisJS `getter`). With
-   * `singleton`, the value is computed once per instance and cached.
+   * Attach a computed property to every instance of THIS class (AdonisJS
+   * `getter`). With `singleton`, the value is computed once per instance and
+   * cached.
    */
-  static getter(name: string, fn: GetterFn, singleton = false): void {
+  static getter(this: typeof Macroable, name: string, fn: GetterFn, singleton = false): void {
     if (!singleton) {
-      Object.defineProperty(Macroable.prototype, name, { get: fn, configurable: true })
+      Object.defineProperty(this.prototype, name, { get: fn, configurable: true })
       return
     }
     const cacheKey = Symbol(name)
-    Object.defineProperty(Macroable.prototype, name, {
+    Object.defineProperty(this.prototype, name, {
       configurable: true,
       get(this: Record<symbol, unknown>) {
         if (!(cacheKey in this)) {

package/dist/utils/inflect.d.ts

@@ -1,17 +0,0 @@
-/**
- * Minimal zero-dependency string inflection — the two operations resourceful
- * routing needs from AdonisJS's `@poppinss/utils/string`: `snakeCase` (route
- * name normalisation) and `singular` (nested-resource param naming, `photos`
- * → `photo_id`).
- *
- * Deviation from AdonisJS (named): `singular` covers regular English plurals
- * only (`-ies→-y`, `-(s|x|z|ch|sh)es→drop es`, trailing `-s→drop`). Irregular
- * plurals (`people→person`, `geese→goose`) are NOT handled — resource names in
- * REST APIs are overwhelmingly regular, and a full inflector (irregular tables,
- * uncountables) would be a dependency-sized rabbit hole for a niche case.
- */
-/** Convert `camelCase`/`PascalCase`/`kebab-case`/spaced text to `snake_case`. */
-export declare function snakeCase(value: string): string;
-/** Singularize a regular English plural (see module deviation note). */
-export declare function singular(word: string): string;
-//# sourceMappingURL=inflect.d.ts.map

package/dist/utils/inflect.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"inflect.d.ts","sourceRoot":"","sources":["../../src/utils/inflect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM7C"}

package/dist/utils/inflect.js

@@ -1,32 +0,0 @@
-/**
- * Minimal zero-dependency string inflection — the two operations resourceful
- * routing needs from AdonisJS's `@poppinss/utils/string`: `snakeCase` (route
- * name normalisation) and `singular` (nested-resource param naming, `photos`
- * → `photo_id`).
- *
- * Deviation from AdonisJS (named): `singular` covers regular English plurals
- * only (`-ies→-y`, `-(s|x|z|ch|sh)es→drop es`, trailing `-s→drop`). Irregular
- * plurals (`people→person`, `geese→goose`) are NOT handled — resource names in
- * REST APIs are overwhelmingly regular, and a full inflector (irregular tables,
- * uncountables) would be a dependency-sized rabbit hole for a niche case.
- */
-/** Convert `camelCase`/`PascalCase`/`kebab-case`/spaced text to `snake_case`. */
-export function snakeCase(value) {
-    return value
-        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-        .replace(/[-\s]+/g, '_')
-        .toLowerCase();
-}
-/** Singularize a regular English plural (see module deviation note). */
-export function singular(word) {
-    if (word.length > 3 && /ies$/i.test(word))
-        return word.replace(/ies$/i, 'y');
-    if (/(?:s|x|z|ch|sh)es$/i.test(word))
-        return word.replace(/es$/i, '');
-    if (/ss$/i.test(word))
-        return word;
-    if (/s$/i.test(word))
-        return word.replace(/s$/i, '');
-    return word;
-}
-//# sourceMappingURL=inflect.js.map

package/dist/utils/inflect.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"inflect.js","sourceRoot":"","sources":["../../src/utils/inflect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK;SACT,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,WAAW,EAAE,CAAA;AAClB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IAC5E,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACrE,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACpD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/src/utils/inflect.ts

@@ -1,29 +0,0 @@
-/**
- * Minimal zero-dependency string inflection — the two operations resourceful
- * routing needs from AdonisJS's `@poppinss/utils/string`: `snakeCase` (route
- * name normalisation) and `singular` (nested-resource param naming, `photos`
- * → `photo_id`).
- *
- * Deviation from AdonisJS (named): `singular` covers regular English plurals
- * only (`-ies→-y`, `-(s|x|z|ch|sh)es→drop es`, trailing `-s→drop`). Irregular
- * plurals (`people→person`, `geese→goose`) are NOT handled — resource names in
- * REST APIs are overwhelmingly regular, and a full inflector (irregular tables,
- * uncountables) would be a dependency-sized rabbit hole for a niche case.
- */
-
-/** Convert `camelCase`/`PascalCase`/`kebab-case`/spaced text to `snake_case`. */
-export function snakeCase(value: string): string {
-  return value
-    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-    .replace(/[-\s]+/g, '_')
-    .toLowerCase()
-}
-
-/** Singularize a regular English plural (see module deviation note). */
-export function singular(word: string): string {
-  if (word.length > 3 && /ies$/i.test(word)) return word.replace(/ies$/i, 'y')
-  if (/(?:s|x|z|ch|sh)es$/i.test(word)) return word.replace(/es$/i, '')
-  if (/ss$/i.test(word)) return word
-  if (/s$/i.test(word)) return word.replace(/s$/i, '')
-  return word
-}