@c9up/ream 0.2.13 → 0.2.15

package/src/container/Container.ts

@@ -32,8 +32,8 @@ const RESERVED_TOKEN_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
 
 /** One resolution chain: the tokens on it, and a set for O(1) membership. */
 interface ResolutionChain {
-  stack: string[]
-  set: Set<string>
+  stack: ServiceToken[]
+  set: Set<ServiceToken>
   /**
    * Values bound on the {@link ContainerResolver} that opened this chain.
    *
@@ -42,7 +42,7 @@ interface ResolutionChain {
    * a controller's constructor dependency sees the same `HttpContext` the
    * middleware bound — and to nothing outside it.
    */
-  values?: ReadonlyMap<string, unknown>
+  values?: ReadonlyMap<ServiceToken, unknown>
   /**
    * How many scoped values this chain has handed out so far.
    *
@@ -63,14 +63,14 @@ interface ResolutionChain {
    * down. Saved and restored around each construction, so a dependency's own
    * dependencies see IT as their parent, not its parent.
    */
-  parent?: new (
+  parent?: abstract new (
     ...args: never[]
   ) => unknown
 }
 
 export class Container {
-  #bindings: Map<string, Binding> = new Map()
-  #singletons: Map<string, unknown> = new Map()
+  #bindings: Map<ServiceToken, Binding> = new Map()
+  #singletons: Map<ServiceToken, unknown> = new Map()
   /**
    * Singletons currently being built, by key.
    *
@@ -79,22 +79,26 @@ export class Container {
    * point is one, and silently discarding the first (a second connection
    * pool, a second scheduler). Concurrent callers await the same promise.
    */
-  #pendingSingletons: Map<string, Promise<unknown>> = new Map()
-  #overrides: Map<string, ServiceFactory> = new Map()
+  #pendingSingletons: Map<ServiceToken, Promise<unknown>> = new Map()
+  #overrides: Map<ServiceToken, ServiceFactory> = new Map()
   /**
    * Snapshot of singletons taken when `swap`/`override` shadows a previously
    * resolved instance. `restore()` re-seats them without re-invoking the
    * original factory, so callers that captured the live reference keep
    * pointing at the same object after the test ends.
    */
-  #singletonBackup: Map<string, unknown> = new Map()
+  #singletonBackup: Map<ServiceToken, unknown> = new Map()
   /** Alias key → the token it forwards to (AdonisJS `container.alias`). */
-  #aliases: Map<string, ServiceToken> = new Map()
+  #aliases: Map<ServiceToken, ServiceToken> = new Map()
   /** parent class → (binding key → the factory that class gets instead). */
-  #contextualBindings: Map<new (...args: never[]) => unknown, Map<string, ServiceFactory>> =
-    new Map()
+  #contextualBindings: Map<
+    abstract new (
+      ...args: never[]
+    ) => unknown,
+    Map<ServiceToken, ServiceFactory>
+  > = new Map()
   /** token key → post-resolution callbacks (AdonisJS `container.resolving`). */
-  #resolvingHooks: Map<string, Array<(value: unknown) => void | Promise<void>>> = new Map()
+  #resolvingHooks: Map<ServiceToken, Array<(value: unknown) => void | Promise<void>>> = new Map()
   /**
    * The resolution chain currently being walked, for cycle detection.
    *
@@ -176,7 +180,7 @@ export class Container {
     else this.#resolvingHooks.set(key, [callback])
   }
 
-  async #runResolvingHooks(key: string, value: unknown): Promise<void> {
+  async #runResolvingHooks(key: ServiceToken, value: unknown): Promise<void> {
     const hooks = this.#resolvingHooks.get(key)
     if (hooks) for (const hook of hooks) await hook(value)
   }
@@ -235,7 +239,7 @@ export class Container {
     }
   }
 
-  #restoreOne(key: string): void {
+  #restoreOne(key: ServiceToken): void {
     this.#overrides.delete(key)
     this.#singletons.delete(key)
     if (this.#singletonBackup.has(key)) {
@@ -272,7 +276,7 @@ export class Container {
     // `alias('b','a')` overflowed the stack instead of naming the cycle.
     let resolvedToken = token
     let key = this.#tokenToKey(resolvedToken)
-    const seenAliases = new Set<string>([key])
+    const seenAliases = new Set<ServiceToken>([key])
     for (
       let target = this.#aliases.get(key);
       target !== undefined;
@@ -281,7 +285,7 @@ export class Container {
       resolvedToken = target
       key = this.#tokenToKey(target)
       if (seenAliases.has(key)) {
-        const cycle = [...seenAliases, key].join(' → ')
+        const cycle = [...seenAliases, key].map(describeToken).join(' → ')
         throw new ReamError('E_CIRCULAR_DEPENDENCY', `Circular alias detected: ${cycle}`, {
           hint: 'An alias chain must end at a real binding — remove one of the aliases.',
           context: { chain: cycle },
@@ -301,7 +305,7 @@ export class Container {
     }
 
     if (chain.set.has(key)) {
-      const cycle = [...chain.stack, key].join(' → ')
+      const cycle = [...chain.stack, key].map(describeToken).join(' → ')
       throw new ReamError('E_CIRCULAR_DEPENDENCY', `Circular dependency detected: ${cycle}`, {
         hint: 'Break the cycle by resolving one dependency lazily inside a method (`await container.make(Dep)`) instead of injecting it in the constructor.',
         context: { chain: cycle },
@@ -401,7 +405,10 @@ export class Container {
    * Reuses an open chain rather than starting a second one, so cycle detection
    * still spans the whole resolution when a resolver is used inside a factory.
    */
-  runWithScopedValues<T>(values: ReadonlyMap<string, unknown>, fn: () => Promise<T>): Promise<T> {
+  runWithScopedValues<T>(
+    values: ReadonlyMap<ServiceToken, unknown>,
+    fn: () => Promise<T>,
+  ): Promise<T> {
     const chain = this.#chain.getStore()
     return this.#chain.run(
       chain === undefined ? { stack: [], set: new Set(), values } : { ...chain, values },
@@ -409,8 +416,8 @@ export class Container {
     )
   }
 
-  /** @internal Normalise a token the way the container keys it. */
-  keyFor(token: ServiceToken): string {
+  /** @internal Validate a token and hand back the value the container keys on. */
+  keyFor(token: ServiceToken): ServiceToken {
     return this.#tokenToKey(token)
   }
 
@@ -434,6 +441,41 @@ export class Container {
 
   // ─── Introspection ────────────────────────────────────────
 
+  /**
+   * Every token the container holds, sorted, with the kind beside it.
+   *
+   * `ream inspect` advertised a section for these and rendered none, because
+   * nothing could enumerate them — `has()` answers about one token you already
+   * know the name of, which is no help when the question is what is in there.
+   *
+   * These are bindings, not every `@inject()`-decorated class: a decorated
+   * class is discovered when it is resolved, and nothing registers it before
+   * that, so no complete list of those exists to return.
+   */
+  get bindings(): ReadonlyArray<{ token: string; scope: string; target?: string }> {
+    const seen = new Map<ServiceToken, { scope: string; target?: string }>()
+    for (const [key, binding] of this.#bindings) seen.set(key, { scope: binding.scope })
+    for (const key of this.#singletons.keys()) {
+      if (!seen.has(key)) seen.set(key, { scope: 'value' })
+    }
+    // Aliases LAST and overwriting, because that is the order `resolve()` uses:
+    // it follows an alias before it ever looks at a binding. Reporting the
+    // binding for a token that also has an alias showed a definition nobody
+    // gets — `service` listed as transient while resolving it hands back
+    // `target`. Where both exist the alias is what runs, and the binding it
+    // shadows is named beside it rather than dropped.
+    for (const [key, target] of this.#aliases) {
+      const shadowed = seen.get(key)
+      seen.set(key, {
+        scope: shadowed === undefined ? 'alias' : `alias (shadows ${shadowed.scope})`,
+        target: describeToken(target),
+      })
+    }
+    return [...seen.entries()]
+      .map(([token, entry]) => ({ token: describeToken(token), ...entry }))
+      .sort((a, b) => a.token.localeCompare(b.token))
+  }
+
   /** Check if a token is registered or resolvable. */
   has(token: ServiceToken): boolean {
     const key = this.#tokenToKey(token)
@@ -472,7 +514,7 @@ export class Container {
   /** Auto-register all @Service() decorated classes from the global registry. */
   autoRegister(): void {
     for (const [target, metadata] of getServiceRegistry()) {
-      const key = metadata.as ?? target.name
+      const key = metadata.as ?? target
       if (!this.#bindings.has(key)) {
         const targetClass = target
         this.#bindings.set(key, {
@@ -487,7 +529,11 @@ export class Container {
 
   // ─── Internal resolution ──────────────────────────────────
 
-  async #resolveInner<T>(key: string, token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
+  async #resolveInner<T>(
+    key: ServiceToken,
+    token: ServiceToken,
+    runtimeValues?: unknown[],
+  ): Promise<T> {
     // 1. Check swaps (test overrides) — a swap factory may be async.
     if (this.#overrides.has(key)) {
       const swapped = await this.#overrides.get(key)?.(this)
@@ -562,11 +608,12 @@ export class Container {
     }
 
     // 7. Not found
-    const allKeys = [...this.#bindings.keys(), ...this.#overrides.keys()]
-    const suggestion = didYouMean(key, allKeys)
+    const name = describeToken(key)
+    const allKeys = [...this.#bindings.keys(), ...this.#overrides.keys()].map(describeToken)
+    const suggestion = didYouMean(name, allKeys)
     throw new ReamError(
       'E_CONTAINER_NOT_FOUND',
-      `No binding found for '${key}'.${suggestion ? ` ${suggestion}` : ''}`,
+      `No binding found for '${name}'.${suggestion ? ` ${suggestion}` : ''}`,
       {
         hint: 'Register it with container.singleton() or decorate with @inject().',
       },
@@ -582,7 +629,7 @@ export class Container {
    * 3. No params → plain `new Class()`
    */
   async #autoConstruct(
-    target: new (...args: never[]) => unknown,
+    target: abstract new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
   ): Promise<unknown> {
     // Everything resolved inside is a dependency OF `target`, which is what a
@@ -599,12 +646,14 @@ export class Container {
   }
 
   async #constructWithDeps(
-    target: new (...args: never[]) => unknown,
+    target: abstract new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
   ): Promise<unknown> {
     const metadata = getServiceMetadata(target)
     const scope = metadata?.scope ?? 'transient'
-    const key = metadata?.as ?? target.name
+    // The class itself, not `target.name`: two classes called `Service` share a
+    // name and must not share a singleton cache entry.
+    const key = metadata?.as ?? target
 
     if (scope === 'singleton' && this.#singletons.has(key)) {
       return this.#singletons.get(key)
@@ -674,7 +723,12 @@ export class Container {
         )
       }
       // (d) Genuine zero-argument class.
-      const instance = new target()
+      //
+      // `Reflect.construct`, not `new target()`: a token may be an abstract
+      // class (that is what a contextual binding binds against), and `new` on
+      // one is a compile error even though the runtime constructs it happily —
+      // `abstract` exists only at compile time.
+      const instance = Reflect.construct(target, [])
       this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
       return instance
     }
@@ -712,7 +766,7 @@ export class Container {
    */
   #cacheIfAppWide(
     scope: string,
-    key: string,
+    key: ServiceToken,
     instance: unknown,
     store: ResolutionChain | undefined,
     readsBefore: number,
@@ -722,39 +776,36 @@ export class Container {
     this.#singletons.set(key, instance)
   }
 
-  #tokenToKey(token: ServiceToken): string {
-    if (typeof token === 'string') {
-      this.#assertNotReserved(token, 'string')
-      return token
-    }
-    if (typeof token === 'symbol') {
-      // Reject unique `Symbol(x)` — two `Symbol("foo")` calls create distinct
-      // symbols, so an override registered with one would be invisible to a
-      // resolver holding the other. Force callers onto `Symbol.for(x)` which
-      // is the global registry and round-trips across modules.
-      if (Symbol.keyFor(token) === undefined) {
-        throw new ReamError(
-          'E_CONTAINER_INVALID_TOKEN',
-          `Unique Symbol() tokens are not supported — use Symbol.for("${token.description ?? 'name'}") so different modules see the same symbol.`,
-        )
-      }
-      const desc = token.description
-      if (desc === undefined) {
-        throw new ReamError('E_CONTAINER_INVALID_TOKEN', 'Symbol tokens must have a description.')
-      }
-      this.#assertNotReserved(desc, 'symbol description')
-      return `Symbol(${desc})`
-    }
-    return token.name
+  /**
+   * Validate a token and hand back the value every map keys on: the token.
+   *
+   * Fold's stores are `Map<string | symbol | AbstractConstructor, …>`, so a
+   * token IS its own key and identity is preserved. Deriving a string key
+   * instead cost exactly what identity buys: `Symbol.for('cache')` became
+   * `"Symbol(cache)"` and collided with the plain string `"Symbol(cache)"`,
+   * and a unique `Symbol()` had to be refused because its description is all a
+   * string key can carry. Both go away when the token is the key.
+   */
+  #tokenToKey(token: ServiceToken): ServiceToken {
+    if (typeof token === 'string') this.#assertNotReserved(token)
+    return token
   }
 
-  #assertNotReserved(name: string, kind: 'string' | 'symbol description'): void {
+  /**
+   * NAMED DEVIATION from Fold, kept deliberately.
+   *
+   * These three read as prototype keys, and a token named after one is far
+   * likelier to be a mistake than a deliberate binding. Nothing indexes tokens
+   * on a plain object any more — every store above is a `Map` — so this is a
+   * tripwire for a caller error, not a pollution guard.
+   */
+  #assertNotReserved(name: string): void {
     if (RESERVED_TOKEN_NAMES.has(name)) {
       throw new ReamError(
         'E_CONTAINER_RESERVED_TOKEN',
         `Reserved container token name '${name}'.`,
         {
-          hint: `'${name}' would collide with an Object.prototype key. Pick a different ${kind}.`,
+          hint: `'${name}' reads as an Object.prototype key. Pick a different token name.`,
         },
       )
     }
@@ -781,6 +832,18 @@ const NON_INJECTABLE_CONSTRUCTORS = new Set<unknown>([
   Error,
 ])
 
+/**
+ * A token as it reads in an error message or in `ream inspect`.
+ *
+ * Display only — the container keys on the token itself, so two distinct
+ * classes that share a name are two bindings that happen to print alike.
+ */
+function describeToken(token: ServiceToken): string {
+  if (typeof token === 'string') return token
+  if (typeof token === 'symbol') return token.toString()
+  return token.name === '' ? 'AnonymousClass' : token.name
+}
+
 /** True for a real, injectable class token (excludes native primitive constructors). */
 function isInjectableClass(value: unknown): value is new (...args: never[]) => unknown {
   return typeof value === 'function' && !NON_INJECTABLE_CONSTRUCTORS.has(value)

package/src/container/ContainerResolver.ts

@@ -20,7 +20,7 @@ import type { ServiceToken } from './types.js'
 export class ContainerResolver {
   readonly #container: Container
   /** Values bound here, keyed the way the container keys its tokens. */
-  readonly #values = new Map<string, unknown>()
+  readonly #values = new Map<ServiceToken, unknown>()
 
   constructor(container: Container) {
     this.#container = container

package/src/container/types.ts

@@ -16,7 +16,17 @@ export interface ServiceMetadata {
 /** Token used to resolve a service — class constructor, string name, or registered symbol. */
 // `never[]` accepts every constructor shape — parameters are contravariant, so
 // a rest of `never` is assignable from any concrete list.
-export type ServiceToken = (new (...args: never[]) => unknown) | string | symbol
+/**
+ * What the container accepts as a token.
+ *
+ * `abstract new`, not `new`: binding an implementation against an abstract base
+ * is the whole point of a contextual binding — `@Inject(Hash)` where `Hash` is
+ * the abstract class and `Bcrypt` is what the container provides. An abstract
+ * class has no construct signature, so spelt `new (...)` the type rejected
+ * exactly the pattern the feature exists for. `abstract new` admits concrete
+ * classes too.
+ */
+export type ServiceToken = (abstract new (...args: never[]) => unknown) | string | symbol
 
 /**
  * What a binding factory is handed so it can resolve its own dependencies

package/src/decorators/Service.ts

@@ -14,7 +14,7 @@ const INJECT_METADATA_KEY = Symbol('ream:inject')
 // `never[]` accepts every constructor shape: parameters are contravariant, so a
 // rest of `never` is assignable from any concrete list. Same spelling as the
 // router's, so a class flows between the two without an assertion.
-type AnyConstructor = new (...args: never[]) => unknown
+type AnyConstructor = abstract new (...args: never[]) => unknown
 
 /** Registry of all decorated services. */
 const serviceRegistry: Map<AnyConstructor, ServiceMetadata> = new Map()

package/src/env/Env.ts

@@ -108,9 +108,11 @@ export class Env<Values extends Record<string, unknown>> {
       validate(values: Record<string, string | undefined>): EnvRecord<S> {
         const failures: string[] = []
         const collected: Record<string, unknown> = {}
-        for (const key of Object.keys(schema)) {
+        // `entries` rather than `keys` plus a lookup: the validator comes back
+        // already known to be there instead of read again as maybe-missing.
+        for (const [key, node] of Object.entries(schema)) {
           try {
-            collected[key] = schema[key].validate(key, values[key])
+            collected[key] = node.validate(key, values[key])
           } catch (err) {
             failures.push(err instanceof Error ? err.message : String(err))
           }

package/src/env/interpolate.ts

@@ -46,9 +46,11 @@ export function interpolate(value: string, lookup: (name: string) => string | un
   })
 
   const prefixed = /^([A-Za-z_][A-Za-z0-9_]*):([\s\S]*)$/.exec(substituted)
-  if (prefixed) {
-    const resolver = identifiers.get(prefixed[1])
-    if (resolver) return resolver(prefixed[2])
+  // Both groups are required by the pattern, so a match carries both.
+  const [, identifier, rest] = prefixed ?? []
+  if (identifier !== undefined && rest !== undefined) {
+    const resolver = identifiers.get(identifier)
+    if (resolver) return resolver(rest)
   }
   return substituted
 }

package/src/errors/FuzzyMatcher.ts

@@ -14,23 +14,43 @@ export function levenshtein(a: string, b: string): number {
   if (m === 0) return n
   if (n === 0) return m
 
-  const dp: number[][] = Array.from({ length: m + 1 }, () => Array<number>(n + 1).fill(0))
-
-  for (let i = 0; i <= m; i++) dp[i][0] = i
-  for (let j = 0; j <= n; j++) dp[0][j] = j
+  // Two rows rather than the whole matrix: the recurrence only ever reads the
+  // row above and the cell to the left, so the rest was allocated and never
+  // looked at again.
+  let previous: number[] = Array.from({ length: n + 1 }, (_, j) => j)
 
   for (let i = 1; i <= m; i++) {
+    const current: number[] = [i]
     for (let j = 1; j <= n; j++) {
       const cost = a[i - 1] === b[j - 1] ? 0 : 1
-      dp[i][j] = Math.min(
-        dp[i - 1][j] + 1, // deletion
-        dp[i][j - 1] + 1, // insertion
-        dp[i - 1][j - 1] + cost, // substitution
+      current.push(
+        Math.min(
+          cell(previous, j) + 1, // deletion
+          cell(current, j - 1) + 1, // insertion
+          cell(previous, j - 1) + cost, // substitution
+        ),
       )
     }
+    previous = current
   }
 
-  return dp[m][n]
+  return cell(previous, n)
+}
+
+/**
+ * One cell of a row that has already been filled.
+ *
+ * Each row is built left to right and every column is written before it is
+ * read, so a miss cannot happen — and this is where that invariant is stated
+ * rather than asserted past it. Reading the row directly would have every
+ * access typed "a number, or nothing", which is not what the algorithm knows.
+ */
+function cell(row: number[], index: number): number {
+  const value = row[index]
+  if (value === undefined) {
+    throw new RangeError(`levenshtein: column ${index} was read before it was written`)
+  }
+  return value
 }
 
 /**
@@ -81,12 +101,13 @@ export function findClosestMatches(
  * @returns Formatted suggestion string, or empty string if no matches
  */
 export function didYouMean(input: string, candidates: string[]): string {
-  const matches = findClosestMatches(input, candidates)
-  if (matches.length === 0) return ''
+  const [best, ...rest] = findClosestMatches(input, candidates)
+  if (best === undefined) return ''
 
-  if (matches.length === 1) {
-    return `Did you mean '${matches[0].candidate}'?`
+  if (rest.length === 0) {
+    return `Did you mean '${best.candidate}'?`
   }
+  const matches = [best, ...rest]
 
   const suggestions = matches.map((m) => `'${m.candidate}'`).join(', ')
   return `Did you mean one of: ${suggestions}?`

package/src/errors/PipelineStageError.ts

@@ -42,9 +42,11 @@ export function createPipelineError(
 ): ReamError {
   const total = PIPELINE_STAGES.length
   const clampedIndex = Math.max(0, Math.min(stageIndex, total - 1))
-  const stageName = PIPELINE_STAGES[clampedIndex]
+  // The index is clamped into the list just above, so the lookup lands — the
+  // fallback is what says so without asserting past the read.
+  const stageName = PIPELINE_STAGES[clampedIndex] ?? '(unknown)'
   const position = `${clampedIndex + 1}/${total}`
-  const nextStage = clampedIndex + 1 < total ? PIPELINE_STAGES[clampedIndex + 1] : '(end)'
+  const nextStage = PIPELINE_STAGES[clampedIndex + 1] ?? '(end)'
 
   const errorCode = originalError instanceof ReamError ? originalError.code : 'E_PIPELINE_ERROR'
 

package/src/events/Emitter.ts

@@ -23,14 +23,25 @@ const correlationStorage = new AsyncLocalStorage<string | undefined>()
  * Listener class interface — must have a handle() method.
  */
 export interface ListenerClass<T = unknown> {
-  handle(event: T): Promise<void> | void
+  handle(event: T): unknown
 }
 
 type EventConstructor<T = unknown> = new (...args: never[]) => T
 
-type ListenerFn<T = unknown> = (event: T) => Promise<void> | void
+/**
+ * A listener. Whatever it returns is awaited and dropped.
+ *
+ * `unknown`, not `Promise<void> | void`: a bare `void` return type accepts a
+ * function returning anything, but a UNION containing it does not — so
+ * `emitter.on('x', (d) => received.push(d))` was a type error for returning
+ * what `push` returns, which nothing reads.
+ */
+type ListenerFn<T = unknown> = (event: T) => unknown
 
-type ListenerConstructor<T = unknown> = new (...args: never[]) => ListenerClass<T>
+// `abstract new`: a listener bound against an abstract base is as valid a
+// registration as one bound against a concrete class, and the container builds
+// either.
+type ListenerConstructor<T = unknown> = abstract new (...args: never[]) => ListenerClass<T>
 
 type Listener<T = unknown> = ListenerFn<T> | ListenerConstructor<T>
 
@@ -41,7 +52,16 @@ type Listener<T = unknown> = ListenerFn<T> | ListenerConstructor<T>
  * satisfies it.
  */
 export interface EmitterResolver {
-  make<T>(target: new (...args: never[]) => T): Promise<T>
+  /**
+   * Build a listener.
+   *
+   * Not generic: a generic method must work for every `T`, so nothing but a
+   * real container could implement it — the fake in the tests could not, and
+   * this file's own call site reached for `as ListenerConstructor<T>` to get
+   * past it. What comes back is checked below, which is what a container's
+   * answer deserves anyway.
+   */
+  make(target: abstract new (...args: never[]) => object): Promise<object>
 }
 
 /**
@@ -327,9 +347,15 @@ export class Emitter {
         if (isListenerClass(listener)) {
           // Listener class — resolve via container for @inject() support
           const instance = this.#resolver
-            ? await this.#resolver.make(listener as ListenerConstructor<T>)
-            : new (listener as ListenerConstructor<T>)()
-          await instance.handle(event)
+            ? await this.#resolver.make(listener)
+            : Reflect.construct(listener, [])
+          const handle = Reflect.get(instance, 'handle')
+          if (typeof handle !== 'function') {
+            throw new Error(
+              `Listener ${String(Reflect.get(listener, 'name'))} resolved to something with no handle()`,
+            )
+          }
+          await handle.call(instance, event)
         } else {
           await (listener as ListenerFn<T>)(event)
         }
@@ -651,7 +677,7 @@ function classToEventName(cls: EventConstructor): string {
 }
 
 /** Check if a listener entry is a class (has prototype.handle) vs a function. */
-function isListenerClass(listener: Listener): boolean {
+function isListenerClass(listener: Listener): listener is ListenerConstructor {
   return typeof listener === 'function' && typeof listener.prototype?.handle === 'function'
 }
 

package/src/events/testing/FakeBus.ts

@@ -41,10 +41,17 @@ export type FakeBusPredicateArg = FakeBusPredicate | ((event: CapturedEmit) => b
 
 interface Subscription {
   pattern: string
-  /** Subscribers may return `void` (sync) or `PromiseLike<void>` (async).
-   *  Async rejections are logged via `console.error` to keep them from
-   *  escaping to `unhandledRejection`. */
-  callback: (eventJson: string) => void | PromiseLike<void>
+  /**
+   * Subscribers may be sync or async; whatever they return is awaited and
+   * dropped, and an async rejection is logged via `console.error` rather than
+   * escaping to `unhandledRejection`.
+   *
+   * `unknown`, not `void | PromiseLike<void>`: a bare `void` return type
+   * accepts a function returning anything, but a UNION containing it does not
+   * — so widening the native bus's `=> void` to that union made it NARROWER in
+   * practice, and `(json) => received.push(json)` stopped compiling.
+   */
+  callback: (eventJson: string) => unknown
 }
 
 /** Request handler may return `void` (sync, fire-and-forget after `reply`)
@@ -106,7 +113,7 @@ export class FakeBus {
     return Promise.resolve('ok')
   }
 
-  subscribe(pattern: string, callback: (eventJson: string) => void | PromiseLike<void>): number {
+  subscribe(pattern: string, callback: (eventJson: string) => unknown): number {
     const id = this.#nextSubId++
     this.#subscribers.set(id, { pattern, callback })
     return id