@c9up/ream 0.1.32 → 0.1.34

package/src/events/Emitter.ts

@@ -33,18 +33,35 @@ type ListenerConstructor<T = unknown> = new (...args: never[]) => ListenerClass<
 
 type Listener<T = unknown> = ListenerFn<T> | ListenerConstructor<T>
 
-/** Resolver for instantiating listener classes with DI. */
-export interface ContainerResolver {
+/**
+ * Resolver for instantiating listener classes with DI — the narrow shape the
+ * emitter needs, so a test can hand it a fake without building a container.
+ * The real {@link import('../container/ContainerResolver.js').ContainerResolver}
+ * satisfies it.
+ */
+export interface EmitterResolver {
   make<T>(target: new (...args: never[]) => T): Promise<T>
 }
 
+/**
+ * @deprecated Use {@link EmitterResolver}. The name now belongs to the real
+ * per-request resolver exported from `@c9up/ream`, as in AdonisJS.
+ */
+export type ContainerResolver = EmitterResolver
+
+/**
+ * What `on` / `once` / `onAny` hand back: call it to stop listening. Named
+ * after the AdonisJS type of the same shape.
+ */
+export type UnsubscribeFunction = () => void
+
 export class Emitter {
   private bus: EventBus
-  private resolver?: ContainerResolver
+  private resolver?: EmitterResolver
   private classListeners: Map<EventConstructor, Listener[]> = new Map()
   private stringListeners: Map<string, ListenerFn[]> = new Map()
 
-  constructor(bus: EventBus, resolver?: ContainerResolver) {
+  constructor(bus: EventBus, resolver?: EmitterResolver) {
     this.bus = bus
     this.resolver = resolver
   }
@@ -56,46 +73,184 @@ export class Emitter {
    *   emitter.on(TaskDeclared, SendNotification)        // listener class
    *   emitter.on(TaskDeclared, (event) => { ... })       // inline function
    */
-  on<T>(event: EventConstructor<T>, listener: Listener<T>): void
+  on<T>(event: EventConstructor<T>, listener: Listener<T>): UnsubscribeFunction
   /**
    * Listen for a string-based event.
    *   emitter.on('user:registered', (user) => { ... })
    *   emitter.on<User>('user:registered', (user) => { ... })  // typed payload
+   *
+   * Returns an unsubscribe function, as AdonisJS does — keeping the listener
+   * reference around just to pass it back to `off` is the boilerplate that
+   * function removes.
    */
-  on<T>(event: string, listener: ListenerFn<T>): void
-  on(event: EventConstructor | string, listener: Listener): void {
+  on<T>(event: string, listener: ListenerFn<T>): UnsubscribeFunction
+  on(event: EventConstructor | string, listener: Listener): UnsubscribeFunction {
     if (typeof event === 'string') {
       const list = this.stringListeners.get(event) ?? []
       list.push(listener as ListenerFn)
       this.stringListeners.set(event, list)
-    } else {
-      const list = this.classListeners.get(event) ?? []
-      list.push(listener)
-      this.classListeners.set(event, list)
+      return () => {
+        this.off(event, listener as ListenerFn)
+      }
+    }
+    const list = this.classListeners.get(event) ?? []
+    list.push(listener)
+    this.classListeners.set(event, list)
+    return () => {
+      const current = this.classListeners.get(event)
+      if (!current) return
+      const index = current.indexOf(listener)
+      if (index !== -1) current.splice(index, 1)
+    }
+  }
+
+  /**
+   * Listen for the NEXT occurrence only (AdonisJS `once`).
+   *
+   * The listener removes itself before running, so a handler that emits the
+   * same event does not re-enter it.
+   */
+  once<T>(event: string, listener: ListenerFn<T>): void {
+    const wrapper: ListenerFn = (data) => {
+      this.off(event, wrapper)
+      return (listener as ListenerFn)(data)
     }
+    this.on(event, wrapper as ListenerFn<T>)
+  }
+
+  /**
+   * Register the listener only when `condition` holds (AdonisJS `listenIf`) —
+   * the shape a feature flag takes at boot, without an `if` around every call.
+   */
+  listenIf<T>(condition: boolean, event: string, listener: ListenerFn<T>): void {
+    if (condition) this.on(event, listener)
+  }
+
+  /** Alias of {@link on} (AdonisJS names it `listen`). */
+  listen<T>(event: string, listener: ListenerFn<T>): void {
+    this.on(event, listener)
+  }
+
+  /** Report listener failures (AdonisJS `onError`). */
+  onError(listener: (event: string, error: unknown) => void): void {
+    this.on('emitter:error', (payload) => {
+      const detail = payload as { event?: string; error?: unknown }
+      listener(detail?.event ?? 'unknown', detail?.error)
+    })
+  }
+
+  /** Remove one listener from an event (AdonisJS `off`). */
+  off(event: string, listener: ListenerFn): void {
+    const list = this.stringListeners.get(event)
+    if (!list) return
+    const index = list.indexOf(listener)
+    if (index !== -1) list.splice(index, 1)
+    if (list.length === 0) this.stringListeners.delete(event)
+  }
+
+  /** Alias of {@link off} (AdonisJS `clearListener`). */
+  clearListener(event: string, listener: ListenerFn): void {
+    this.off(event, listener)
+  }
+
+  /** Drop every listener of one event (AdonisJS `clearListeners`). */
+  clearListeners(event: string): void {
+    this.stringListeners.delete(event)
+  }
+
+  /** Drop every listener of every event (AdonisJS `clearAllListeners`). */
+  clearAllListeners(): void {
+    this.stringListeners.clear()
+    this.classListeners.clear()
+  }
+
+  /** How many listeners an event has, or all of them (AdonisJS `listenerCount`). */
+  listenerCount(event?: string): number {
+    if (event !== undefined) return this.stringListeners.get(event)?.length ?? 0
+    let total = 0
+    for (const list of this.stringListeners.values()) total += list.length
+    for (const list of this.classListeners.values()) total += list.length
+    return total
   }
 
   // ─── Emit ─────────────────────────────────────────────────
 
   /**
-   * Emit a string-based event.
+   * Run an event's listeners, in parallel or one after another.
+   *
+   * A listener that throws is reported and does NOT stop the others: one
+   * failing subscriber must not silently cancel the rest of the reaction to an
+   * event it does not own.
    */
-  emit(event: string, data: unknown): void {
-    // Dispatch to string listeners
-    const listeners = this.stringListeners.get(event)
-    if (listeners) {
-      for (const fn of listeners) {
-        Promise.resolve(fn(data)).catch((err) => {
-          // Surface listener errors instead of swallowing them
-          this.emitError(event, err)
-        })
+  async #dispatchListeners(event: string, data: unknown, serial: boolean): Promise<void> {
+    const listeners = [
+      ...(this.stringListeners.get(event) ?? []),
+      ...this.#wildcardListenersFor(event),
+    ]
+    if (listeners.length === 0) return
+    const run = async (fn: ListenerFn): Promise<void> => {
+      try {
+        await fn(data)
+      } catch (err) {
+        this.emitError(event, err)
       }
     }
+    if (serial) {
+      for (const fn of listeners) await run(fn)
+      return
+    }
+    await Promise.all(listeners.map(run))
+  }
+
+  /** Listeners registered through `onAny` whose pattern matches `event`. */
+  #wildcardListenersFor(_event: string): ListenerFn[] {
+    return []
+  }
 
-    // Also push through EventBus for cross-service / Rust subscribers.
-    // `#wrapForBus` prepends the correlation envelope when set so the ID
-    // reaches the other side; without it `setCorrelationId()` was a no-op.
-    void this.bus.emit(event, JSON.stringify(this.#wrapForBus(data))).catch((err: unknown) => {
+  /**
+   * Emit and run the listeners ONE AT A TIME (AdonisJS `emitSerial`).
+   *
+   * Use it when order matters — a listener that seeds what the next one reads.
+   */
+  async emitSerial(event: string, data: unknown): Promise<void> {
+    await this.#dispatchListeners(event, data, true)
+    this.#publishToBus(event, data)
+  }
+
+  /**
+   * Emit a string-based event.
+   *
+   * Returns a promise resolving once every listener has finished, as AdonisJS
+   * does — awaiting it is how a handler makes sure the work it triggered
+   * actually happened before it answers. Listeners run in PARALLEL; use
+   * {@link emitSerial} when one has to finish before the next starts.
+   *
+   * Not awaiting it keeps the old fire-and-forget behaviour: a listener that
+   * rejects is reported through `emitError`, never left unhandled.
+   */
+  async emit(event: string, data: unknown): Promise<void> {
+    await this.#dispatchListeners(event, data, false)
+    this.#publishToBus(event, data)
+  }
+
+  /**
+   * Push the event onto the bus for cross-service / Rust subscribers.
+   *
+   * `#wrapForBus` prepends the correlation envelope when set so the ID reaches
+   * the other side; without it `setCorrelationId()` was a no-op.
+   */
+  #publishToBus(event: string, data: unknown): void {
+    // Serialize INSIDE the guard. `JSON.stringify` throws synchronously on a
+    // cycle or a BigInt, and it was evaluated as an argument — so the throw
+    // escaped past the `.catch` and crashed the caller.
+    let payload: string
+    try {
+      payload = JSON.stringify(this.#wrapForBus(data))
+    } catch (err) {
+      this.emitError(event, err)
+      return
+    }
+    void this.bus.emit(event, payload).catch((err: unknown) => {
       this.emitError(event, err)
     })
   }
@@ -161,7 +316,27 @@ export class Emitter {
    *   emitter.onAny('order.*', (name, data) => { ... })   // single segment
    *   emitter.onAny('order.**', (name, data) => { ... })  // deep match
    */
+  async onAny(listener: (eventName: string, data: unknown) => void): Promise<number>
+  async onAny(
+    pattern: string,
+    listener: (eventName: string, data: unknown) => void,
+  ): Promise<number>
   async onAny(
+    patternOrListener: string | ((eventName: string, data: unknown) => void),
+    maybeListener?: (eventName: string, data: unknown) => void,
+  ): Promise<number> {
+    // `onAny(listener)` — every event, the AdonisJS signature. `**` is the
+    // deep-match pattern the Rust matcher already understands, so the two
+    // forms share one implementation.
+    const pattern = typeof patternOrListener === 'string' ? patternOrListener : '**'
+    const listener = typeof patternOrListener === 'string' ? maybeListener : patternOrListener
+    if (listener === undefined) {
+      throw new TypeError('onAny() requires a listener')
+    }
+    return this.#subscribeAny(pattern, listener)
+  }
+
+  async #subscribeAny(
     pattern: string,
     listener: (eventName: string, data: unknown) => void,
   ): Promise<number> {

package/src/graphql/GraphQLEngine.ts

@@ -509,6 +509,11 @@ export class GraphQLEngine {
 }
 
 /** Parse and validate an unknown request body as a GraphQL request object. */
+/** GraphQL `variables` must be a keyed object — never an array or null. */
+function isVariablesRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
 function parseGraphQLBody(body: unknown): GraphQLRequest | null {
   if (!body || typeof body !== 'object' || Array.isArray(body)) return null
   // After typeof check, body is a non-null non-array object; index via 'in' narrowing
@@ -516,14 +521,8 @@ function parseGraphQLBody(body: unknown): GraphQLRequest | null {
   if (typeof q !== 'string') return null
 
   let variables: Record<string, unknown> | undefined
-  if (
-    'variables' in body &&
-    body.variables !== null &&
-    typeof body.variables === 'object' &&
-    !Array.isArray(body.variables)
-  ) {
-    // biome-ignore lint/suspicious/noExplicitAny: narrowed to non-null non-array object above; branded as Record for safe spreading
-    variables = body.variables as any as Record<string, unknown>
+  if ('variables' in body && isVariablesRecord(body.variables)) {
+    variables = body.variables
   }
 
   const rawOpName = 'operationName' in body ? body.operationName : undefined

package/src/helpers/duration.ts

@@ -0,0 +1,71 @@
+/**
+ * Duration parsing, matching what AdonisJS accepts.
+ *
+ * Adonis runs every duration through `string.seconds.parse()`
+ * (`@poppinss/string`), which delegates string forms to `@lukeed/ms`. A config
+ * carrying `age: '2 hours'` or `maxAge: '30 mins'` therefore has to work here
+ * too — this is a value an app moves over verbatim.
+ *
+ * Two rules taken straight from that implementation, both easy to get wrong:
+ *
+ *  - A **number is already in seconds** and is returned untouched. It is NOT
+ *    milliseconds, whatever a reading of the guides suggests: `seconds.parse`
+ *    starts with `if (typeof duration === 'number') return duration`.
+ *  - A **string with no unit is in milliseconds**. `@lukeed/ms` falls through
+ *    its unit branches and returns the bare number as ms, so Adonis' `'7200'`
+ *    is seven seconds, not two hours. Treating it as seconds — which is the
+ *    intuitive reading — would silently stretch every such value by 1000.
+ */
+
+/**
+ * The unit vocabulary of `@lukeed/ms`, in the order its regex tests them.
+ * Written out rather than reusing its regex so the accepted spellings are
+ * readable: `2h`, `2 hrs`, `2 hours` all mean the same thing.
+ */
+const DURATION_PATTERN =
+  /^(-?(?:\d+)?\.?\d+) *(m(?:illiseconds?|s(?:ecs?)?))?(s(?:ec(?:onds?|s)?)?)?(m(?:in(?:utes?|s)?)?)?(h(?:ours?|rs?)?)?(d(?:ays?)?)?(w(?:eeks?|ks?)?)?(y(?:ears?|rs?)?)?$/
+
+const SECOND = 1000
+const MINUTE = SECOND * 60
+const HOUR = MINUTE * 60
+const DAY = HOUR * 24
+const YEAR = DAY * 365.25
+
+/**
+ * Parse a duration string to MILLISECONDS, or `undefined` when it is not a
+ * duration. Mirrors `@lukeed/ms`'s `parse`, including its quirk that a value
+ * with no unit is milliseconds.
+ */
+export function parseDurationMs(value: string): number | undefined {
+  const matched = DURATION_PATTERN.exec(value.toLowerCase())
+  if (matched === null) return undefined
+  const amount = Number.parseFloat(matched[1] ?? '')
+  // `@lukeed/ms` rejects a zero amount here (`(num = parseFloat(...))` is
+  // falsy), and so must we, or `'0 hours'` would part company with Adonis.
+  if (!amount) return undefined
+  if (matched[3] !== undefined) return amount * SECOND
+  if (matched[4] !== undefined) return amount * MINUTE
+  if (matched[5] !== undefined) return amount * HOUR
+  if (matched[6] !== undefined) return amount * DAY
+  if (matched[7] !== undefined) return amount * DAY * 7
+  if (matched[8] !== undefined) return amount * YEAR
+  // No unit — and `matched[2]` (an explicit `ms`) lands here too.
+  return amount
+}
+
+/**
+ * A duration as SECONDS, the way `string.seconds.parse` returns it: a number
+ * passes through untouched, a string is parsed and floored.
+ *
+ * @param label - what is being parsed, for the error message.
+ */
+export function durationToSeconds(value: number | string, label: string): number {
+  if (typeof value === 'number') return Math.trunc(value)
+  const milliseconds = parseDurationMs(value)
+  if (milliseconds === undefined) {
+    throw new Error(
+      `Cannot read "${value}" as ${label}. Use a number of seconds, or a duration such as '30m', '2 hours' or '7 days'.`,
+    )
+  }
+  return Math.floor(milliseconds / SECOND)
+}

package/src/helpers/napi-loader.ts

@@ -13,7 +13,16 @@ import { arch, platform } from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { ReamError } from '../errors/ReamError.js'
 
-/** Platform triple suffix (matches napi-rs naming). */
+/**
+ * Platform triple suffix (matches napi-rs naming).
+ *
+ * The ONE map for `@c9up/ream`. Every native package carries its own — they are
+ * independently publishable and must not import each other — so a new target
+ * still has to be added per package; within ream it is added here once.
+ *
+ * Linux binaries target GLIBC. musl (Alpine) is not a supported target, and the
+ * loader says so rather than reporting a bare "not found".
+ */
 export const NAPI_PLATFORM_MAP: Record<string, string> = {
   'linux-x64': 'linux-x64-gnu',
   'linux-arm64': 'linux-arm64-gnu',
@@ -94,13 +103,20 @@ export function loadNapi<T>(options: LoadNapiOptions): T {
     }
   }
 
+  // On a musl host the glibc binary is present but never loads, so "not found"
+  // sends the reader looking for a missing file that is right there. Name the
+  // real reason instead.
+  const muslHint = suffix.endsWith('-gnu')
+    ? ' If you are on Alpine/musl, note the prebuilt Linux binaries target glibc — musl is not a supported target.'
+    : ''
   throw new ReamError(
     `${errorCodePrefix}_NAPI_NOT_FOUND`,
     `${binaryName} NAPI binary not found. Expected ${binaryName}.${suffix}.node`,
     {
-      hint:
+      hint: `${
         options.notFoundHint ??
-        "Run 'pnpm --filter @c9up/ream build:rust' to build the native module.",
+        "Run 'pnpm --filter @c9up/ream build:rust' to build the native module."
+      }${muslHint}`,
     },
   )
 }

package/src/helpers/types.ts

@@ -25,7 +25,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/http/Exception.ts

@@ -42,11 +42,23 @@ export class Exception extends Error {
   constructor(message: string, options?: { status?: number; code?: string }) {
     super(message)
     this.name = this.constructor.name
-    // biome-ignore lint/suspicious/noExplicitAny: this.constructor is typed as Function; subclass pattern requires the cast
-    const ctor = this.constructor as any as typeof Exception
-    this.status = options?.status ?? ctor.status
-    this.code = options?.code ?? ctor.code
-    if (ctor.help !== undefined) this.help = ctor.help
+    // `this.constructor` is typed `Function`, which carries none of the statics
+    // a subclass sets (`status`, `code`, `help`). Reading them through
+    // `Reflect.get` states that we are looking at OPTIONAL statics, which is
+    // exactly the contract — a subclass need not define any of them.
+    const ctor = this.constructor
+    const staticNumber = (key: string): number | undefined => {
+      const v = Reflect.get(ctor, key)
+      return typeof v === 'number' ? v : undefined
+    }
+    const staticString = (key: string): string | undefined => {
+      const v = Reflect.get(ctor, key)
+      return typeof v === 'string' ? v : undefined
+    }
+    this.status = options?.status ?? staticNumber('status') ?? Exception.status
+    this.code = options?.code ?? staticString('code') ?? Exception.code
+    const help = staticString('help')
+    if (help !== undefined) this.help = help
   }
 
   /** Override to self-handle the exception (convert to HTTP response). */

package/src/http/HttpContext.ts

@@ -10,6 +10,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import type { ServiceToken } from '../container/types.js'
 import type { Emitter } from '../events/Emitter.js'
+import type { MatchedParams } from '../router/Router.js'
 import type { CookieSigner } from '../security/CookieSigner.js'
 import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Session } from '../session/Session.js'
@@ -87,7 +88,19 @@ export interface Authorizer {
 // pattern as warden/blackhole middleware), so nothing cross-imports it.
 interface ContainerResolver {
   /** Resolve/construct a service by token (class, string, or symbol). Async (AdonisJS parity). */
-  make<T>(token: ServiceToken): Promise<T>
+  make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T>
+  /** Call a method with its dependencies injected (AdonisJS `resolver.call`). */
+  call<T, K extends string & keyof T>(
+    instance: T,
+    method: K,
+    runtimeValues?: unknown[],
+  ): Promise<unknown>
+  /** Bind a value for THIS request only (AdonisJS `resolver.bindValue`). */
+  bindValue<T>(token: ServiceToken, value: T): void
+  /** Whether the token resolves (AdonisJS `resolver.hasBinding`). */
+  hasBinding(token: ServiceToken): boolean
+  /** Whether every token resolves (AdonisJS `resolver.hasAllBindings`). */
+  hasAllBindings(tokens: ServiceToken[]): boolean
 }
 
 /**
@@ -204,7 +217,16 @@ export class HttpContext extends Macroable {
   readonly response: Response
 
   /** Route parameters extracted from the URL pattern. */
-  readonly params: Record<string, string>
+  /** Matched route parameters — `*` holds the segments it swallowed, as an array. */
+  /**
+   * Route parameters.
+   *
+   * `string | string[]`, not AdonisJS's `any`: a catch-all `*` really is the
+   * ARRAY of segments on both sides, so the `any` upstream only hides it. Use
+   * {@link Request.param} when you want the single-value form — it joins a
+   * catch-all with `/` and returns `string | undefined`.
+   */
+  readonly params: MatchedParams
 
   /** Information about the matched route. */
   readonly route: RouteInfo
@@ -246,8 +268,9 @@ export class HttpContext extends Macroable {
 
   /**
    * Per-request IoC resolver (Adonis idiom: `ctx.containerResolver.make(...)`).
-   * Populated by `HttpKernel` from the application container. Undefined only
-   * when the context was built without one (e.g. a mock in a unit test).
+   * Built by `HttpKernel` with `container.createResolver()`, so a value bound
+   * on it belongs to THIS request and no other. Undefined only when the context
+   * was built without one (e.g. a mock in a unit test).
    * Agnostic middleware resolves host services through this, never by importing
    * `@c9up/ream`. See {@link ContainerResolver}.
    */
@@ -303,7 +326,7 @@ export class HttpContext extends Macroable {
   constructor(
     id: string,
     rawRequest: RawRequest,
-    params: Record<string, string>,
+    params: MatchedParams,
     route: RouteInfo,
     containerResolver?: ContainerResolver,
   ) {