@c9up/ream 0.1.24 → 0.1.26

package/src/rpc/RpcProvider.ts

@@ -42,6 +42,7 @@ export interface RpcConfig {
 
 export class RpcProvider extends Provider {
   readonly rpc: RpcRouter
+  #registered = false
 
   constructor(app: AppContext, options: RpcProviderOptions = {}) {
     super(app)
@@ -51,7 +52,9 @@ export class RpcProvider extends Provider {
   override register(): void {
     const container = this.app.container
     if (container.has('rpc')) {
-      if (container.resolve('rpc') === this.rpc) return // re-register is idempotent
+      // Idempotent re-register: tracked with a flag rather than
+      // `container.resolve('rpc')` because resolution is now async.
+      if (this.#registered) return
       throw new ReamError(
         'RPC_PROVIDER_ALREADY_REGISTERED',
         "Container token 'rpc' is already bound to a different instance",
@@ -62,12 +65,13 @@ export class RpcProvider extends Provider {
     }
     this.rpc.useContainer(container)
     container.singleton('rpc', () => this.rpc)
+    this.#registered = true
   }
 
   override async boot(): Promise<void> {
     const config = this.app.config.get<RpcConfig>('rpc')
     const path = config?.path ?? '/rpc'
-    const router = this.app.container.make<Router>('router')
+    const router = await this.app.container.make<Router>('router')
     // RpcRouter.handle() reads the registered methods at request time, so the
     // mount can happen before apps finish registering methods.
     const route = router.post(path, (ctx: HttpContext) => this.rpc.handle(ctx))

package/src/rpc/RpcRouter.ts

@@ -29,8 +29,8 @@ export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown>
  * the shared `'middleware'` registry, and `validator:<name>` schemas.
  */
 interface RpcContainer {
-  make<T>(target: new (...args: unknown[]) => T): T
-  resolve<T>(token: string): T
+  make<T>(target: new (...args: unknown[]) => T): Promise<T>
+  resolve<T>(token: string): Promise<T>
   has(token: string): boolean
 }
 
@@ -101,7 +101,7 @@ function checkRpcAuthorization(
   def: RpcMethodDefinition,
 ): { code: number; message: string } | undefined {
   const needsAuth = def.guards.length > 0 || def.roles.length > 0 || def.permissions.length > 0
-  if (needsAuth && !ctx.auth?.authenticated) {
+  if (needsAuth && !ctx.auth?.isAuthenticated) {
     return { code: -32003, message: 'Unauthorized' }
   }
   if (def.roles.length > 0) {
@@ -163,7 +163,7 @@ export class RpcRouter {
       this.method(`${prefix}.${methodName}`, async (ctx, params) => {
         // Resolve through the container on every call (fresh DI per request,
         // like GraphQLEngine), falling back to a bare `new` when unset.
-        const instance = this.#container ? this.#container.make(controller) : new controller()
+        const instance = this.#container ? await this.#container.make(controller) : new controller()
         return instance[methodName](ctx, params)
       })
     }
@@ -238,7 +238,7 @@ export class RpcRouter {
    */
   async #runMiddleware(ctx: HttpContext, names: string[]): Promise<void> {
     const registry = this.#container?.has('middleware')
-      ? this.#container.resolve<MiddlewareRegistry>('middleware')
+      ? await this.#container.resolve<MiddlewareRegistry>('middleware')
       : undefined
     if (!registry) {
       throw new Error(
@@ -285,7 +285,8 @@ export class RpcRouter {
             id,
           )
         }
-        const outcome = this.#container.resolve<RuntimeValidator>(token).validate(params)
+        const validator = await this.#container.resolve<RuntimeValidator>(token)
+        const outcome = validator.validate(params)
         if (!outcome.valid) return rpcError(-32602, 'Invalid params', id, outcome.errors)
         effectiveParams = outcome.data ?? params
       }

package/src/scheduler/ScheduleProvider.ts

@@ -41,6 +41,7 @@ let activeProvider: ScheduleProvider | undefined
 export class ScheduleProvider extends Provider {
   readonly scheduler: Scheduler
   #booted = false
+  #registered = false
 
   constructor(app: AppContext, options: ScheduleProviderOptions = {}) {
     super(app)
@@ -65,20 +66,10 @@ export class ScheduleProvider extends Provider {
   override register(): void {
     const scheduler = this.scheduler
     const container = this.app.container
-    // Probe for an existing binding. The `make` / `resolve` API
-    // throws when unbound; use it to distinguish "same instance"
-    // from "another provider already claimed the token".
-    let existing: unknown
-    try {
-      existing = container.resolve('scheduler')
-    } catch {
-      existing = undefined
-    }
-    if (existing !== undefined) {
-      if (existing === scheduler) {
-        // Same provider re-running its register phase — no-op.
-        return
-      }
+    if (container.has('scheduler')) {
+      // Idempotent re-register: tracked with a flag rather than
+      // `container.resolve('scheduler')` because resolution is now async.
+      if (this.#registered) return
       throw new ReamError(
         'SCHEDULE_PROVIDER_ALREADY_REGISTERED',
         "Container token 'scheduler' is already bound to a different instance",
@@ -88,6 +79,7 @@ export class ScheduleProvider extends Provider {
       )
     }
     container.singleton('scheduler', () => scheduler)
+    this.#registered = true
   }
 
   override async boot(): Promise<void> {
@@ -130,7 +122,7 @@ export class ScheduleProvider extends Provider {
             this.scheduler.register(taskName, cronExpr, async () => {
               // Resolve from the container on every fire so transient
               // services get a fresh instance each run.
-              const instance = this.app.container.make<Record<string, unknown>>(target)
+              const instance = await this.app.container.make<Record<string, unknown>>(target)
               const method = instance[methodName]
               if (typeof method !== 'function') {
                 throw new ReamError(

package/src/server/Server.ts

@@ -12,11 +12,12 @@ import type { MiddlewareFunction } from '../middleware/Pipeline.js'
 import type { Router } from '../router/Router.js'
 
 /**
- * A middleware class with a handle method.
- * This is the pattern used by AdonisJS middleware.
+ * A middleware class with a handle method. The optional third argument carries
+ * per-route configuration passed through a named-middleware factory (AdonisJS
+ * `handle(ctx, next, args)`).
  */
 export interface MiddlewareClass {
-  handle(ctx: HttpContext, next: () => Promise<void>): Promise<void> | void
+  handle(ctx: HttpContext, next: () => Promise<void>, args?: unknown): Promise<void> | void
 }
 
 /** Lazy import returning a module with a default export. */
@@ -109,7 +110,11 @@ export class Server {
 
 /**
  * Convert a MiddlewareEntry (lazy import or function) into a MiddlewareFunction.
- * Lazy imports are resolved on first call and cached.
+ * The imported class is cached on first call; the INSTANCE is resolved through
+ * the request's IoC container so `@inject()` constructor dependencies are wired
+ * (AdonisJS resolves middleware via the container — a plain `new Class()` gives
+ * every injected dependency `undefined`). Falls back to `new Class()` only when
+ * no container is present (mock contexts in unit tests).
  */
 export function resolveMiddlewareEntry(entry: MiddlewareEntry): MiddlewareFunction {
   // Direct middleware function (2 params: ctx, next)
@@ -117,16 +122,50 @@ export function resolveMiddlewareEntry(entry: MiddlewareEntry): MiddlewareFuncti
     return entry
   }
 
-  // Lazy import of a middleware class — resolve + cache on first invocation
-  // After isMiddlewareFunction returns false, entry is narrowed to LazyImport<MiddlewareClassConstructor>
+  // Lazy import of a middleware class — cache the CLASS on first invocation,
+  // then resolve the instance per request through the container (DI). The
+  // container's own singleton bindings still cache instances where desired.
   const lazyImport = entry
-  let cached: MiddlewareClass | undefined
+  let cachedClass: MiddlewareClassConstructor | undefined
   return async (ctx: HttpContext, next: () => Promise<void>) => {
-    if (!cached) {
+    if (!cachedClass) {
       const mod = await lazyImport()
-      cached = new mod.default()
+      cachedClass = mod.default
+    }
+    const instance = ctx.containerResolver
+      ? await ctx.containerResolver.make<MiddlewareClass>(cachedClass)
+      : new cachedClass()
+    await instance.handle(ctx, next)
+  }
+}
+
+/**
+ * Turn a middleware entry into a FACTORY `(args?) => MiddlewareFunction`
+ * (AdonisJS named-middleware factories). The returned function bakes `args` in
+ * and forwards them to the class's `handle(ctx, next, args)`. A plain function
+ * middleware ignores `args` (it has no third parameter). Class resolution +
+ * caching mirror {@link resolveMiddlewareEntry} (imported once, instance via DI).
+ */
+export function resolveParametrizedMiddlewareEntry(
+  entry: MiddlewareEntry,
+): (args?: unknown) => MiddlewareFunction {
+  if (isMiddlewareFunction(entry)) {
+    return () => entry
+  }
+
+  const lazyImport = entry
+  let cachedClass: MiddlewareClassConstructor | undefined
+  return (args?: unknown): MiddlewareFunction => {
+    return async (ctx: HttpContext, next: () => Promise<void>) => {
+      if (!cachedClass) {
+        const mod = await lazyImport()
+        cachedClass = mod.default
+      }
+      const instance = ctx.containerResolver
+        ? await ctx.containerResolver.make<MiddlewareClass>(cachedClass)
+        : new cachedClass()
+      await instance.handle(ctx, next, args)
     }
-    await cached.handle(ctx, next)
   }
 }
 

package/src/session/SessionMiddleware.ts

@@ -56,7 +56,7 @@ export default class SessionMiddleware {
     const isProduction = process.env.NODE_ENV === 'production'
 
     // Read session ID from cookie — pre-parsed by the Rust HyperServer.
-    let sessionId = ctx.request.cookie(cookieName)
+    let sessionId = ctx.request.plainCookie(cookieName)
     const hadIncomingCookie = sessionId !== null
 
     // Cookie driver: the cookie value IS the session data (encrypted)
@@ -65,7 +65,7 @@ export default class SessionMiddleware {
       sessionId = sessionId ?? generateSessionId()
       const session = new Session(sessionId, data)
       ctx.store.set('session', session)
-    ctx.session = session
+      ctx.session = session
 
       await next()
 
@@ -85,7 +85,7 @@ export default class SessionMiddleware {
               'Switch to a server-side driver (memory/redis) or reduce session data.\n',
           )
         }
-        ctx.response.cookie(cookieName, encoded, {
+        ctx.response.plainCookie(cookieName, encoded, {
           maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
           path: '/',
           httpOnly: true,
@@ -145,7 +145,7 @@ export default class SessionMiddleware {
     // defeats HTTP caching, and leaks a Set-Cookie to CDNs. This mirrors
     // the cookie-driver path above (which already omits `isNew`).
     if (session.isDirty() || regenerated || (rolling && hadIncomingCookie)) {
-      ctx.response.cookie(cookieName, session.sessionId, {
+      ctx.response.plainCookie(cookieName, session.sessionId, {
         maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
         path: '/',
         httpOnly: true,

package/src/storage/StaticProvider.ts

@@ -34,7 +34,7 @@ export class StaticProvider extends Provider {
     const config = this.app.config.get<StaticConfig>('static')
     const middleware = this.#override ?? (config?.root ? new StaticMiddleware(config) : undefined)
     if (!middleware) return // not configured — opt-out
-    const server = this.app.container.make<Server>('server')
+    const server = await this.app.container.make<Server>('server')
     server.use([(ctx, next) => middleware.handle(ctx, next)])
   }
 }

package/src/testing/RequestBuilder.ts

@@ -38,6 +38,16 @@ class ExpectationError extends Error {
 
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
 
+/** Cookie the signed CSRF token is issued in (blackhole default: `XSRF-TOKEN`). */
+const CSRF_COOKIE_NAME = 'XSRF-TOKEN'
+/** Header the client echoes the token back in (Axios/Angular default). */
+const CSRF_HEADER_NAME = 'x-xsrf-token'
+
+/** Primitive accepted as a query-string value (mirrors `.qs()` in japa/api-client). */
+type QueryValue = string | number | boolean
+/** Query-string map — a value or an array of values (repeated key). */
+export type QueryParams = Record<string, QueryValue | ReadonlyArray<QueryValue>>
+
 /**
  * Internal low-level sender — matches what the TestClient exposes.
  * Accepting it as an injected callable keeps RequestBuilder framework-agnostic.
@@ -72,6 +82,7 @@ export class RequestBuilder {
   #body: Buffer = Buffer.alloc(0)
   #multipart: MultipartPart[] = []
   #cookies: Record<string, string> = {}
+  #query = new URLSearchParams()
   #authStrategy: AuthStrategy | null
   #pendingAuth: AuthSubject | null = null
   #sent: Promise<TestResponse> | null = null
@@ -159,6 +170,58 @@ export class RequestBuilder {
     return this
   }
 
+  /**
+   * Append query-string params — mirrors japa/api-client's `.qs()`. Values are
+   * URL-encoded; arrays repeat the key (`?tag=a&tag=b`). Merges with any query
+   * string already on the path and with earlier `.qs()` calls.
+   */
+  qs(params: QueryParams): this {
+    for (const [key, value] of Object.entries(params)) {
+      if (Array.isArray(value)) {
+        for (const item of value) this.#query.append(key, String(item))
+      } else {
+        this.#query.append(key, String(value))
+      }
+    }
+    return this
+  }
+
+  /** Pass a bearer token as the `Authorization` header — japa `.bearerToken()`. */
+  bearerToken(token: string): this {
+    this.#headers.authorization = `Bearer ${token}`
+    return this
+  }
+
+  /** Pass HTTP Basic credentials as the `Authorization` header — japa `.basicAuth()`. */
+  basicAuth(user: string, password: string): this {
+    const encoded = Buffer.from(`${user}:${password}`, 'utf8').toString('base64')
+    this.#headers.authorization = `Basic ${encoded}`
+    return this
+  }
+
+  /**
+   * Satisfy blackhole's signed double-submit CSRF check: echo the `XSRF-TOKEN`
+   * cookie back in the `X-XSRF-TOKEN` header (the pair the server compares).
+   *
+   * With a `token` argument, sets both the cookie and the header — useful when
+   * you already hold a signed token. Without one, reads the token from a cookie
+   * set earlier on this request (typically extracted from a prior safe GET's
+   * `Set-Cookie`); throws if none is present so the mistake is caught at the
+   * call site instead of surfacing as a confusing 403.
+   */
+  withCsrf(token?: string): this {
+    if (token !== undefined) this.#cookies[CSRF_COOKIE_NAME] = token
+    const value = this.#cookies[CSRF_COOKIE_NAME]
+    if (value === undefined) {
+      throw new Error(
+        `RequestBuilder: withCsrf() found no '${CSRF_COOKIE_NAME}' cookie. Set it first via ` +
+          `.cookie('${CSRF_COOKIE_NAME}', token) (extracted from a prior safe GET) or pass the token: withCsrf(token).`,
+      )
+    }
+    this.#headers[CSRF_HEADER_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
@@ -250,6 +313,152 @@ export class RequestBuilder {
     return this
   }
 
+  // ─── japa/api-client status shortcuts ──────────────────────
+  // Thin aliases over expectStatus() — one per common HTTP status, matching
+  // @japa/api-client's assertOk()/assertCreated()/… surface.
+
+  /** Assert a 200 OK response. */
+  assertOk(): Promise<this> {
+    return this.expectStatus(200)
+  }
+
+  /** Assert a 201 Created response. */
+  assertCreated(): Promise<this> {
+    return this.expectStatus(201)
+  }
+
+  /** Assert a 204 No Content response. */
+  assertNoContent(): Promise<this> {
+    return this.expectStatus(204)
+  }
+
+  /** Assert a 400 Bad Request response. */
+  assertBadRequest(): Promise<this> {
+    return this.expectStatus(400)
+  }
+
+  /** Assert a 401 Unauthorized response. */
+  assertUnauthorized(): Promise<this> {
+    return this.expectStatus(401)
+  }
+
+  /** Assert a 403 Forbidden response. */
+  assertForbidden(): Promise<this> {
+    return this.expectStatus(403)
+  }
+
+  /** Assert a 404 Not Found response. */
+  assertNotFound(): Promise<this> {
+    return this.expectStatus(404)
+  }
+
+  /**
+   * Assert a redirect (3xx) whose `Location` resolves to `path`. Compares the
+   * pathname (query/host ignored), mirroring japa's `assertRedirectsTo`.
+   */
+  async assertRedirectsTo(path: string): Promise<this> {
+    const res = await this.send()
+    if (res.status < 300 || res.status >= 400) {
+      throw new ExpectationError(
+        `Expected a redirect (3xx) to "${path}", got status ${res.status}.`,
+      )
+    }
+    const location = res.headers.location
+    if (location === undefined) {
+      throw new ExpectationError(
+        `Expected a redirect to "${path}", but the response has no Location header.`,
+      )
+    }
+    // Location may be absolute or path-only; compare pathnames either way.
+    const actual = location.startsWith('http')
+      ? new URL(location).pathname
+      : (location.split('?')[0] ?? location)
+    if (actual !== path) {
+      throw new ExpectationError(`Expected redirect to "${path}", got "${actual}".`)
+    }
+    return this
+  }
+
+  /** Assert the JSON body contains `subset` (deep partial) — japa `assertBodyContains`. */
+  async assertBodyContains(subset: unknown): Promise<this> {
+    const actual = await this.#bodyJson()
+    if (!partialMatch(actual, subset)) {
+      throw new ExpectationError(
+        `Expected body to contain subset.\nSubset: ${JSON.stringify(subset)}\nActual: ${capBody(JSON.stringify(actual))}`,
+      )
+    }
+    return this
+  }
+
+  /** Assert the JSON body does NOT contain `subset` — japa `assertBodyNotContains`. */
+  async assertBodyNotContains(subset: unknown): Promise<this> {
+    const actual = await this.#bodyJson()
+    if (partialMatch(actual, subset)) {
+      throw new ExpectationError(
+        `Expected body NOT to contain subset, but it did.\nSubset: ${JSON.stringify(subset)}\nActual: ${capBody(JSON.stringify(actual))}`,
+      )
+    }
+    return this
+  }
+
+  /**
+   * Assert a response header is present, and equals `value` when given. Unlike
+   * {@link expectHeader}, the value is optional (presence-only check).
+   */
+  async assertHeader(name: string, value?: string): Promise<this> {
+    if (value !== undefined) return this.expectHeader(name, value)
+    const res = await this.send()
+    if (res.headers[name.toLowerCase()] === undefined) {
+      throw new ExpectationError(
+        `Expected header ${name}, not present in: ${Object.keys(res.headers).join(', ')}`,
+      )
+    }
+    return this
+  }
+
+  /** Assert a response header is absent — japa `assertHeaderMissing`. */
+  async assertHeaderMissing(name: string): Promise<this> {
+    const res = await this.send()
+    if (res.headers[name.toLowerCase()] !== undefined) {
+      throw new ExpectationError(`Expected header ${name} to be absent, but it was present.`)
+    }
+    return this
+  }
+
+  /** Assert the response set a cookie, optionally with a given value — japa `assertCookie`. */
+  assertCookie(name: string, value?: string): Promise<this> {
+    return this.expectCookie(name, value)
+  }
+
+  /** Assert the response did NOT set a cookie — japa `assertCookieMissing`. */
+  async assertCookieMissing(name: string): Promise<this> {
+    const res = await this.send()
+    const setCookie = res.headers['set-cookie']
+    if (setCookie) {
+      const present = setCookie
+        .split(/,(?=\s*\w+=)/)
+        .some((c) => c.trimStart().startsWith(`${name}=`))
+      if (present) {
+        throw new ExpectationError(
+          `Expected cookie ${name} to be absent, but it was set: ${setCookie}`,
+        )
+      }
+    }
+    return this
+  }
+
+  /** Send (once) and parse the body as JSON, wrapping parse errors as ExpectationError. */
+  async #bodyJson(): Promise<unknown> {
+    const res = await this.send()
+    try {
+      return 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)})`,
+      )
+    }
+  }
+
   async #execute(): Promise<TestResponse> {
     // Resolve auth before sending.
     if (this.#pendingAuth !== null) {
@@ -287,7 +496,15 @@ export class RequestBuilder {
       this.#headers.cookie = cookieEntries.map(([k, v]) => `${k}=${v}`).join('; ')
     }
 
-    return this.#sender(this.#method, this.#path, {
+    // Merge `.qs()` params into the path, preserving any query string it
+    // already carries.
+    let path = this.#path
+    const qs = this.#query.toString()
+    if (qs) {
+      path += (path.includes('?') ? '&' : '?') + qs
+    }
+
+    return this.#sender(this.#method, path, {
       headers: this.#headers,
       body: this.#body,
     })

package/src/testing/TestClient.ts

@@ -51,18 +51,27 @@ export interface TestRequestBuilder extends PromiseLike<TestResponse> {
   send(): Promise<TestResponse>
 }
 
+/**
+ * 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.
+ */
+export type RouteManifest = Record<string, string>
+
 export class TestClient {
   #port = 0
   #headers: Dict = {}
   #bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>
   #auth: AuthStrategy | null
+  #routes: RouteManifest | null
 
   constructor(
     bootFn: (port: number) => Promise<{ port: number; close: () => Promise<void> | void }>,
-    options: { auth?: AuthStrategy } = {},
+    options: { auth?: AuthStrategy; routes?: RouteManifest } = {},
   ) {
     this.#bootFn = bootFn
     this.#auth = options.auth ?? null
+    this.#routes = options.routes ?? null
   }
 
   #server: { port: number; close: () => Promise<void> | void } | null = null
@@ -140,6 +149,21 @@ export class TestClient {
     return new RequestBuilder(sender, method, path, this.#auth)
   }
 
+  /**
+   * GET a named route — japa/api-client's `.visit()`. Resolves `name` against
+   * the `routes` manifest (`router.namedManifest()`), fills `:param`
+   * placeholders, and returns the rich chainable builder. Throws a clear error
+   * when no manifest was configured or the name is unknown.
+   */
+  visit(name: string, params?: Record<string, string>): RequestBuilder {
+    if (!this.#routes) {
+      throw new Error(
+        'TestClient: visit() needs a named-route manifest. Pass `routes: router.namedManifest()` in the client options.',
+      )
+    }
+    return this.fluent('GET', 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 }
@@ -198,9 +222,41 @@ export {
   type HttpMethod,
   type HttpSender,
   partialMatch,
+  type QueryParams,
   RequestBuilder,
 } from './RequestBuilder.js'
 
+/**
+ * Resolve a named route against a manifest — the client-side twin of
+ * `Router.urlFor`. Fills `:param` placeholders (word-boundary safe), strips
+ * unprovided `:optional?` segments, and throws on an unknown name or a missing
+ * required param.
+ */
+export function resolveNamedRoute(
+  manifest: RouteManifest,
+  name: string,
+  params?: Record<string, string>,
+): string {
+  const pattern = manifest[name]
+  if (pattern === undefined) {
+    const available = Object.keys(manifest).join(', ') || '(none)'
+    throw new Error(`Route '${name}' not found. Available: ${available}`)
+  }
+  let url = pattern
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      url = url.replace(new RegExp(`:${escaped}\\??(?![\\w])`, 'g'), encodeURIComponent(value))
+    }
+  }
+  url = url.replace(/\/:[A-Za-z_][\w]*\?/g, '')
+  const missing = url.match(/:[A-Za-z_][\w]*/g)
+  if (missing && missing.length > 0) {
+    throw new Error(`Cannot generate URL for route '${name}': missing params ${missing.join(', ')}`)
+  }
+  return url
+}
+
 /** Send an HTTP request using raw TCP (no external dependencies). */
 async function sendRequest(
   port: number,

package/src/utils/Macroable.ts

@@ -0,0 +1,54 @@
+/**
+ * Macroable — lets a package extend a class at runtime with extra methods
+ * (`macro`) and computed properties (`getter`), AdonisJS-style. A framework
+ * class (Request, Response, HttpContext, Router, …) extends this so an add-on
+ * can attach behaviour without a subclass:
+ *
+ *   Request.macro('wantsJson', function () { return this.accepts(['json']) === 'json' })
+ *   HttpContext.getter('tenant', function () { return resolveTenant(this) })
+ *
+ * TypeScript sees only the base class; consumers type their macros with
+ * declaration merging (`declare module`) exactly as in AdonisJS.
+ */
+
+/**
+ * A macro method. When invoked, `this` is the instance it's attached to —
+ * declare it explicitly in your callback (`function (this: Request) { … }`) to
+ * type the receiver; the alias itself leaves `this` open so any class fits.
+ */
+export type MacroFn = (...args: unknown[]) => unknown
+
+/** A getter implementation — declare `this` in your callback to type the receiver. */
+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, {
+      value: fn,
+      writable: true,
+      configurable: true,
+    })
+  }
+
+  /**
+   * Attach a computed property to every instance (AdonisJS `getter`). With
+   * `singleton`, the value is computed once per instance and cached.
+   */
+  static getter(name: string, fn: GetterFn, singleton = false): void {
+    if (!singleton) {
+      Object.defineProperty(this.prototype, name, { get: fn, configurable: true })
+      return
+    }
+    const cacheKey = Symbol(name)
+    Object.defineProperty(this.prototype, name, {
+      configurable: true,
+      get(this: Record<symbol, unknown>) {
+        if (!(cacheKey in this)) {
+          Object.defineProperty(this, cacheKey, { value: fn.call(this), configurable: true })
+        }
+        return this[cacheKey]
+      },
+    })
+  }
+}