@c9up/ream 0.1.34 → 0.2.0

package/src/events/Emitter.ts

@@ -13,6 +13,7 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { type BufferedEventName, EventsBuffer } from './EventsBuffer.js'
 import type { EventBus } from './native.js'
 
 /** Per-request correlation ID stored in async context so concurrent requests don't corrupt each other. */
@@ -55,11 +56,26 @@ export type ContainerResolver = EmitterResolver
  */
 export type UnsubscribeFunction = () => void
 
+/**
+ * What `onAny` hands back. Same shape as {@link UnsubscribeFunction} — and
+ * assignable wherever one is expected — but awaitable, because dropping a
+ * wildcard subscription is a NAPI call into the Rust bus. Ignore the promise
+ * for the AdonisJS behaviour; await it when the next assertion depends on the
+ * subscription being gone.
+ */
+export type AsyncUnsubscribeFunction = () => Promise<void>
+
 export class Emitter {
   private bus: EventBus
   private resolver?: EmitterResolver
   private classListeners: Map<EventConstructor, Listener[]> = new Map()
   private stringListeners: Map<string, ListenerFn[]> = new Map()
+  /** Set while faking; every emission lands here instead of running. */
+  #buffer?: EventsBuffer
+  /** Which events are faked. `undefined` means all of them. */
+  #fakedEvents?: Set<BufferedEventName>
+  /** Wildcard subscriptions, so `offAny(listener)` can find its Rust handle. */
+  readonly #anySubscriptions = new Map<(eventName: string, data: unknown) => void, Set<number>>()
 
   constructor(bus: EventBus, resolver?: EmitterResolver) {
     this.bus = bus
@@ -122,8 +138,10 @@ export class Emitter {
    * 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)
+  listenIf<T>(condition: boolean | (() => boolean), event: string, listener: ListenerFn<T>): void {
+    // AdonisJS takes either — a thunk lets the flag be read at registration
+    // time rather than at the call site.
+    if (typeof condition === 'function' ? condition() : condition) this.on(event, listener)
   }
 
   /** Alias of {@link on} (AdonisJS names it `listen`). */
@@ -164,6 +182,20 @@ export class Emitter {
     this.classListeners.clear()
   }
 
+  /**
+   * Every event with the listeners registered for it (AdonisJS
+   * `eventsListeners`).
+   *
+   * Read-only copies: a caller inspecting the map — a debug screen, a test
+   * asserting nothing leaked — must not be able to unsubscribe by mutating it.
+   */
+  get eventsListeners(): Map<EventConstructor | string, Listener[]> {
+    const all = new Map<EventConstructor | string, Listener[]>()
+    for (const [event, listeners] of this.classListeners) all.set(event, [...listeners])
+    for (const [event, listeners] of this.stringListeners) all.set(event, [...listeners])
+    return all
+  }
+
   /** 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
@@ -213,6 +245,7 @@ export class Emitter {
    * Use it when order matters — a listener that seeds what the next one reads.
    */
   async emitSerial(event: string, data: unknown): Promise<void> {
+    if (this.#capture(event, data)) return
     await this.#dispatchListeners(event, data, true)
     this.#publishToBus(event, data)
   }
@@ -229,6 +262,7 @@ export class Emitter {
    * rejects is reported through `emitError`, never left unhandled.
    */
   async emit(event: string, data: unknown): Promise<void> {
+    if (this.#capture(event, data)) return
     await this.#dispatchListeners(event, data, false)
     this.#publishToBus(event, data)
   }
@@ -277,6 +311,9 @@ export class Emitter {
    */
   async dispatchEvent<T extends object>(event: T): Promise<void> {
     const EventClass = event.constructor as EventConstructor<T>
+    // Faked by the class, as AdonisJS does — `fake([TaskDeclared])` catches
+    // `new TaskDeclared(...).emit()`.
+    if (this.#capture(EventClass, event)) return
     const listeners = this.classListeners.get(EventClass) ?? []
     const name = (EventClass as { eventName?: string }).eventName ?? classToEventName(EventClass)
 
@@ -307,6 +344,51 @@ export class Emitter {
     await this.bus.emit(name, JSON.stringify(this.#wrapForBus(event)))
   }
 
+  // ─── Faking (AdonisJS `fake` / `restore`) ─────────────────
+
+  /**
+   * Stop the named events from reaching their listeners and the bus, and
+   * collect them instead.
+   *
+   * With no argument every event is faked. Calling it again drops the previous
+   * fake and starts a fresh buffer, as AdonisJS does.
+   *
+   * ```ts
+   * const events = emitter.fake(['user:registered'])
+   * await register(payload)
+   * events.assertEmitted('user:registered')
+   * emitter.restore()
+   * ```
+   */
+  fake(events?: BufferedEventName[]): EventsBuffer {
+    this.restore()
+    this.#fakedEvents = events === undefined ? undefined : new Set(events)
+    this.#buffer = new EventsBuffer(() => {
+      this.restore()
+    })
+    return this.#buffer
+  }
+
+  /** Let events through again (AdonisJS `restore`). */
+  restore(): void {
+    this.#buffer = undefined
+    this.#fakedEvents = undefined
+  }
+
+  /**
+   * Record the emission and report whether it was swallowed.
+   *
+   * Returns `true` when the event is faked — the caller must then return
+   * without dispatching or publishing, which is what "the listeners are not
+   * invoked" means.
+   */
+  #capture(event: BufferedEventName, data: unknown): boolean {
+    if (this.#buffer === undefined) return false
+    if (this.#fakedEvents !== undefined && !this.#fakedEvents.has(event)) return false
+    this.#buffer.add(event, data)
+    return true
+  }
+
   // ─── Wildcard subscriptions (via Rust NAPI) ───────────────
 
   /**
@@ -316,15 +398,15 @@ 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(listener: (eventName: string, data: unknown) => void): Promise<UnsubscribeFunction>
   async onAny(
     pattern: string,
     listener: (eventName: string, data: unknown) => void,
-  ): Promise<number>
+  ): Promise<UnsubscribeFunction>
   async onAny(
     patternOrListener: string | ((eventName: string, data: unknown) => void),
     maybeListener?: (eventName: string, data: unknown) => void,
-  ): Promise<number> {
+  ): Promise<UnsubscribeFunction> {
     // `onAny(listener)` — every event, the AdonisJS signature. `**` is the
     // deep-match pattern the Rust matcher already understands, so the two
     // forms share one implementation.
@@ -333,7 +415,21 @@ export class Emitter {
     if (listener === undefined) {
       throw new TypeError('onAny() requires a listener')
     }
-    return this.#subscribeAny(pattern, listener)
+    const id = await this.#subscribeAny(pattern, listener)
+
+    // AdonisJS hands back the unsubscribe function, not the handle. The Rust
+    // subscription id stays reachable through `offAny(id)` because that is what
+    // the bus needs, but a caller following the AdonisJS shape never sees it.
+    let ids = this.#anySubscriptions.get(listener)
+    if (!ids) {
+      ids = new Set()
+      this.#anySubscriptions.set(listener, ids)
+    }
+    ids.add(id)
+
+    return async () => {
+      await this.offAny(id)
+    }
   }
 
   async #subscribeAny(
@@ -363,9 +459,28 @@ export class Emitter {
     })
   }
 
-  /** Unsubscribe a wildcard subscription by ID. */
-  async offAny(subscriptionId: number): Promise<void> {
-    await this.bus.unsubscribe(subscriptionId)
+  /**
+   * Stop a wildcard subscription (AdonisJS `offAny`).
+   *
+   * Takes the listener, as AdonisJS does. The numeric handle the Rust bus
+   * issued is also accepted, because that is what the unsubscribe crosses NAPI
+   * with and `onAny`'s unsubscribe function closes over it.
+   *
+   * Async where AdonisJS is sync: dropping the subscription is a NAPI call, and
+   * returning before it lands would let an event through after `offAny`.
+   */
+  async offAny(listenerOrId: number | ((eventName: string, data: unknown) => void)): Promise<this> {
+    if (typeof listenerOrId === 'number') {
+      await this.bus.unsubscribe(listenerOrId)
+      for (const ids of this.#anySubscriptions.values()) ids.delete(listenerOrId)
+      return this
+    }
+
+    const ids = this.#anySubscriptions.get(listenerOrId)
+    if (!ids) return this
+    this.#anySubscriptions.delete(listenerOrId)
+    await Promise.all([...ids].map((id) => this.bus.unsubscribe(id)))
+    return this
   }
 
   /** Check if a pattern matches an event name (wildcard matching via Rust). */
@@ -446,10 +561,11 @@ export class Emitter {
   /**
    * Check if any listeners are registered for an event.
    */
-  hasListeners(event: EventConstructor | string): boolean {
-    if (typeof event === 'string') {
-      return (this.stringListeners.get(event)?.length ?? 0) > 0
-    }
+  hasListeners(event?: EventConstructor | string): boolean {
+    // AdonisJS makes the argument optional: no argument asks whether ANY event
+    // has a listener at all.
+    if (event === undefined) return this.listenerCount() > 0
+    if (typeof event === 'string') return (this.stringListeners.get(event)?.length ?? 0) > 0
     return (this.classListeners.get(event)?.length ?? 0) > 0
   }
 

package/src/events/EventsBuffer.ts

@@ -0,0 +1,131 @@
+/**
+ * What {@link import('./Emitter.js').Emitter.fake} hands back: the events that
+ * were emitted while faking, and the assertions to check them.
+ *
+ * AdonisJS parity (`@adonisjs/events` `EventsBuffer`). A faked event never
+ * reaches its listeners nor the bus — it lands here instead, so a test asserts
+ * on what the code decided to announce without running the reaction to it.
+ */
+
+import { AssertionError } from 'node:assert'
+
+/** An event name: a string, or the class of a class-based event. */
+export type BufferedEventName = string | (new (...args: never[]) => unknown)
+
+/** One captured emission. */
+export interface BufferedEvent<Data = unknown> {
+  event: BufferedEventName
+  data: Data
+}
+
+/** Narrows an assertion to one emission among several of the same event. */
+export type EventFinder<Data = unknown> = (event: BufferedEvent<Data>) => boolean
+
+export class EventsBuffer {
+  readonly #events: BufferedEvent[] = []
+  readonly #restore: () => void
+
+  constructor(restore: () => void) {
+    this.#restore = restore
+  }
+
+  /** Record an emission. Called by the emitter while faking. */
+  add(event: BufferedEventName, data: unknown): void {
+    this.#events.push({ event, data })
+  }
+
+  /** Every captured emission, in the order they happened. */
+  all(): BufferedEvent[] {
+    return [...this.#events]
+  }
+
+  /** How many emissions were captured. */
+  size(): number {
+    return this.#events.length
+  }
+
+  /** Was this event emitted (optionally, one matching `finder`)? */
+  exists<Data = unknown>(event: BufferedEventName, finder?: EventFinder<Data>): boolean {
+    return this.find(event, finder) !== null
+  }
+
+  /** The first matching emission, or `null`. */
+  find<Data = unknown>(
+    event: BufferedEventName,
+    finder?: EventFinder<Data>,
+  ): BufferedEvent<Data> | null {
+    for (const buffered of this.#events) {
+      if (buffered.event !== event) continue
+      const typed = buffered as BufferedEvent<Data>
+      if (finder === undefined || finder(typed)) return typed
+    }
+    return null
+  }
+
+  /** Fail unless the event was emitted. */
+  assertEmitted<Data = unknown>(event: BufferedEventName, finder?: EventFinder<Data>): void {
+    if (this.exists(event, finder)) return
+    throw new AssertionError({
+      message: `Expected "${nameOf(event)}" event to be emitted`,
+      operator: 'assertEmitted',
+      expected: nameOf(event),
+      actual: this.#emittedNames(),
+    })
+  }
+
+  /** Fail unless the event was emitted exactly `count` times. */
+  assertEmittedCount(event: BufferedEventName, count: number): void {
+    const actual = this.#events.filter((buffered) => buffered.event === event).length
+    if (actual === count) return
+    throw new AssertionError({
+      message: `Expected "${nameOf(event)}" event to be emitted "${count}" times, instead it was emitted "${actual}" times`,
+      operator: 'assertEmittedCount',
+      expected: count,
+      actual,
+    })
+  }
+
+  /** Fail if the event was emitted. */
+  assertNotEmitted<Data = unknown>(event: BufferedEventName, finder?: EventFinder<Data>): void {
+    if (!this.exists(event, finder)) return
+    throw new AssertionError({
+      message: `Unexpected "${nameOf(event)}" event was emitted`,
+      operator: 'assertNotEmitted',
+      expected: [],
+      actual: this.#emittedNames(),
+    })
+  }
+
+  /** Fail if anything at all was emitted. */
+  assertNoneEmitted(): void {
+    if (this.#events.length === 0) return
+    throw new AssertionError({
+      message: `Expected zero events to be emitted, instead received "${this.#events.length}" events`,
+      operator: 'assertNoneEmitted',
+      expected: 0,
+      actual: this.#events.length,
+    })
+  }
+
+  /** Drop the captured events, keeping the fake in place. */
+  flush(): void {
+    this.#events.length = 0
+  }
+
+  /**
+   * Restore the emitter when the buffer leaves a `using` block, so a test that
+   * throws mid-way cannot leave events faked for the next one.
+   */
+  [Symbol.dispose](): void {
+    this.#restore()
+  }
+
+  #emittedNames(): string[] {
+    return this.#events.map((buffered) => nameOf(buffered.event))
+  }
+}
+
+/** A readable name for an event, whether it is a string or a class. */
+function nameOf(event: BufferedEventName): string {
+  return typeof event === 'string' ? event : event.name
+}

package/src/events/index.ts

@@ -11,12 +11,19 @@
 
 export type { EventsConfig } from './config.js'
 export { defineConfig } from './config.js'
+export type { AsyncUnsubscribeFunction, UnsubscribeFunction } from './Emitter.js'
 export {
   BaseEvent,
   type ContainerResolver,
   Emitter,
   type ListenerClass,
 } from './Emitter.js'
+export {
+  type BufferedEvent,
+  type BufferedEventName,
+  type EventFinder,
+  EventsBuffer,
+} from './EventsBuffer.js'
 export type { EventsAppContext } from './EventsProvider.js'
 export { default as EventsProvider } from './EventsProvider.js'
 export { EventBus } from './native.js'

package/src/health/BaseCheck.ts

@@ -0,0 +1,30 @@
+import { durationToSeconds } from '../helpers/duration.js'
+import type { HealthCheckContract, HealthCheckResult } from './types.js'
+
+/**
+ * The base every check extends (AdonisJS `BaseCheck`).
+ */
+export abstract class BaseCheck implements HealthCheckContract {
+  abstract name: string
+  /** Seconds to reuse a previous result for. */
+  cacheDuration?: number
+
+  /** Rename the check, so two instances of one check stay distinguishable. */
+  as(name: string): this {
+    this.name = name
+    return this
+  }
+
+  /**
+   * Reuse this check's result for the given duration — `60`, `'1 minute'`,
+   * `'30s'`. An expensive check (a remote ping, a disk stat) should not run on
+   * every probe.
+   */
+  cacheFor(duration: string | number): this {
+    this.cacheDuration =
+      typeof duration === 'number' ? duration : durationToSeconds(duration, 'a health check cache')
+    return this
+  }
+
+  abstract run(): Promise<HealthCheckResult>
+}

package/src/health/HealthChecks.ts

@@ -0,0 +1,83 @@
+import { debuglog } from 'node:util'
+import { healthCheck } from './tracing.js'
+import type { HealthCheckContract, HealthCheckReport } from './types.js'
+
+const debug = debuglog('ream:health')
+
+/**
+ * Runs the registered checks and aggregates them into one report
+ * (AdonisJS `HealthChecks`).
+ */
+export class HealthChecks {
+  #checks: HealthCheckContract[] = []
+  #cachedResults = new Map<string, Awaited<ReturnType<HealthCheckContract['run']>>>()
+
+  /** Replace the registered checks. */
+  register(checks: HealthCheckContract[]): this {
+    this.#checks = checks
+    return this
+  }
+
+  /** Add to the registered checks. */
+  append(checks: HealthCheckContract[]): this {
+    this.#checks = this.#checks.concat(checks)
+    return this
+  }
+
+  #getDebugInfo(): HealthCheckReport['debugInfo'] {
+    return {
+      pid: process.pid,
+      ppid: process.ppid,
+      platform: process.platform,
+      uptime: process.uptime(),
+      version: process.version,
+    }
+  }
+
+  async #runCheck(check: HealthCheckContract): Promise<HealthCheckReport['checks'][number]> {
+    if (check.cacheDuration) {
+      const cached = this.#cachedResults.get(check.name)
+      const cacheMilliseconds = Math.floor(check.cacheDuration * 1000)
+      if (cached && Date.now() < cached.finishedAt.getTime() + cacheMilliseconds) {
+        debug('returning cached results for "%s" check', check.name)
+        return { name: check.name, isCached: true, ...cached }
+      }
+    }
+
+    const result = await healthCheck.tracePromise(
+      check.run,
+      healthCheck.hasSubscribers ? { check } : undefined,
+      check,
+    )
+    debug('executed "%s" check', check.name)
+    if (check.cacheDuration) this.#cachedResults.set(check.name, result)
+    return { name: check.name, isCached: false, ...result }
+  }
+
+  /** Run every check concurrently and aggregate the verdicts. */
+  async run(): Promise<HealthCheckReport> {
+    let isHealthy = true
+    let status: HealthCheckReport['status'] = 'ok'
+
+    const checks = await Promise.all(
+      this.#checks.map(async (check) => {
+        const result = await this.#runCheck(check)
+        if (result.status === 'error') {
+          status = 'error'
+          isHealthy = false
+        } else if (status === 'ok' && result.status === 'warning') {
+          status = 'warning'
+        }
+        return result
+      }),
+    )
+
+    return {
+      isHealthy,
+      status,
+      finishedAt: new Date(),
+      debugInfo: this.#getDebugInfo(),
+      checks,
+    }
+  }
+}

package/src/health/Result.ts

@@ -0,0 +1,69 @@
+import type { HealthCheckResult } from './types.js'
+
+/**
+ * A chainable builder for a check result (AdonisJS `Result`).
+ */
+export class Result implements HealthCheckResult {
+  message: string
+  status: HealthCheckResult['status']
+  finishedAt: Date
+  /** Free-form data attached to the result. */
+  meta?: HealthCheckResult['meta']
+
+  constructor(message: string, status: HealthCheckResult['status'], finishedAt: Date) {
+    this.message = message
+    this.status = status
+    this.finishedAt = finishedAt
+  }
+
+  /** A passing result. */
+  static ok(message: string): Result {
+    return new Result(message, 'ok', new Date())
+  }
+
+  /** A failing result. Accepts a message, a message and an error, or an error. */
+  static failed(message: string, error?: Error): Result
+  static failed(error: Error): Result
+  static failed(message: string | Error, error?: Error): Result {
+    const result = new Result(
+      typeof message === 'string' ? message : message.message,
+      'error',
+      new Date(),
+    )
+    if (error) result.setMetaData({ error })
+    if (typeof message !== 'string') result.setMetaData({ error: message })
+    return result
+  }
+
+  /** A result that is not yet failing but wants attention. */
+  static warning(message: string): Result {
+    return new Result(message, 'warning', new Date())
+  }
+
+  /** Override when the check finished. */
+  setFinishedAt(finishedAt: Date): this {
+    this.finishedAt = finishedAt
+    return this
+  }
+
+  /** Replace the meta-data wholesale. */
+  setMetaData(metaData: Record<string, unknown>): this {
+    this.meta = metaData
+    return this
+  }
+
+  /** Shallow-merge into the existing meta-data. */
+  mergeMetaData(metaData: Record<string, unknown>): this {
+    this.meta = { ...this.meta, ...metaData }
+    return this
+  }
+
+  toJSON(): HealthCheckResult {
+    return {
+      finishedAt: this.finishedAt,
+      message: this.message,
+      status: this.status,
+      ...(this.meta ? { meta: this.meta } : {}),
+    }
+  }
+}

package/src/health/checks/DiskSpaceCheck.ts

@@ -0,0 +1,69 @@
+import { statfs } from 'node:fs/promises'
+import { BaseCheck } from '../BaseCheck.js'
+import { Result } from '../Result.js'
+import type { HealthCheckResult } from '../types.js'
+
+/**
+ * Watches how full the disk is (AdonisJS `DiskSpaceCheck`).
+ *
+ * NAMED DEVIATION — upstream depends on the `check-disk-space` package, which
+ * shells out to `df` on POSIX and `wmic` on Windows. Ream reads Node's own
+ * `fs.statfs` instead: no dependency, no subprocess, and the same two numbers.
+ * `bavail` rather than `bfree` is deliberate — it is the space actually
+ * available to this process, which is what `df` reports and what an operator
+ * means by "free".
+ */
+export class DiskSpaceCheck extends BaseCheck {
+  #warnThreshold = 75
+  #failThreshold = 80
+  #computeFn: () => Promise<{ free: number; size: number }> = async () => {
+    const stats = await statfs(this.diskPath)
+    return { free: Number(stats.bavail) * stats.bsize, size: Number(stats.blocks) * stats.bsize }
+  }
+
+  name = 'Disk space check'
+  /** The mount point to measure. */
+  diskPath = process.platform === 'win32' ? 'C:\\' : '/'
+
+  /** Warn once this percentage of the disk is used. */
+  warnWhenExceeds(valueInPercentage: number): this {
+    this.#warnThreshold = valueInPercentage
+    return this
+  }
+
+  /** Fail once this percentage of the disk is used. */
+  failWhenExceeds(valueInPercentage: number): this {
+    this.#failThreshold = valueInPercentage
+    return this
+  }
+
+  /** Replace how the reading is taken, so a test can drive the thresholds. */
+  compute(callback: () => Promise<{ free: number; size: number }>): this {
+    this.#computeFn = callback
+    return this
+  }
+
+  async run(): Promise<HealthCheckResult> {
+    const { free, size } = await this.#computeFn()
+    const usedPercentage = Math.floor(((size - free) / size) * 100)
+    const metaData = {
+      sizeInPercentage: {
+        used: usedPercentage,
+        failureThreshold: this.#failThreshold,
+        warningThreshold: this.#warnThreshold,
+      },
+    }
+
+    if (usedPercentage >= this.#failThreshold) {
+      return Result.failed(
+        `Disk usage is ${usedPercentage}%, which is above the threshold of ${this.#failThreshold}%`,
+      ).mergeMetaData(metaData)
+    }
+    if (usedPercentage >= this.#warnThreshold) {
+      return Result.warning(
+        `Disk usage is ${usedPercentage}%, which is above the threshold of ${this.#warnThreshold}%`,
+      ).mergeMetaData(metaData)
+    }
+    return Result.ok('Disk usage is under defined thresholds').mergeMetaData(metaData)
+  }
+}