@c9up/ream 0.2.4 → 0.2.6

package/src/env/Env.ts

@@ -68,6 +68,12 @@ export class Env<Values extends Record<string, unknown>> {
 
   readonly #values: Values
 
+  /**
+   * Private on purpose: an `Env` is only ever built by {@link create}, which is
+   * what validates. `private` and not `#` because a private CONSTRUCTOR has no
+   * native form — this is the one place the keyword carries a meaning `#`
+   * cannot express.
+   */
   private constructor(values: Values) {
     this.#values = values
   }

package/src/events/Emitter.ts

@@ -66,10 +66,10 @@ export type UnsubscribeFunction = () => void
 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()
+  #bus: EventBus
+  #resolver?: EmitterResolver
+  #classListeners: Map<EventConstructor, Listener[]> = new Map()
+  #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. */
@@ -78,8 +78,8 @@ export class Emitter {
   readonly #anySubscriptions = new Map<(eventName: string, data: unknown) => void, Set<number>>()
 
   constructor(bus: EventBus, resolver?: EmitterResolver) {
-    this.bus = bus
-    this.resolver = resolver
+    this.#bus = bus
+    this.#resolver = resolver
   }
 
   // ─── Class-based events ───────────────────────────────────
@@ -102,18 +102,18 @@ export class Emitter {
   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) ?? []
+      const list = this.#stringListeners.get(event) ?? []
       list.push(listener as ListenerFn)
-      this.stringListeners.set(event, list)
+      this.#stringListeners.set(event, list)
       return () => {
         this.off(event, listener as ListenerFn)
       }
     }
-    const list = this.classListeners.get(event) ?? []
+    const list = this.#classListeners.get(event) ?? []
     list.push(listener)
-    this.classListeners.set(event, list)
+    this.#classListeners.set(event, list)
     return () => {
-      const current = this.classListeners.get(event)
+      const current = this.#classListeners.get(event)
       if (!current) return
       const index = current.indexOf(listener)
       if (index !== -1) current.splice(index, 1)
@@ -159,11 +159,11 @@ export class Emitter {
 
   /** Remove one listener from an event (AdonisJS `off`). */
   off(event: string, listener: ListenerFn): void {
-    const list = this.stringListeners.get(event)
+    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)
+    if (list.length === 0) this.#stringListeners.delete(event)
   }
 
   /** Alias of {@link off} (AdonisJS `clearListener`). */
@@ -173,13 +173,13 @@ export class Emitter {
 
   /** Drop every listener of one event (AdonisJS `clearListeners`). */
   clearListeners(event: string): void {
-    this.stringListeners.delete(event)
+    this.#stringListeners.delete(event)
   }
 
   /** Drop every listener of every event (AdonisJS `clearAllListeners`). */
   clearAllListeners(): void {
-    this.stringListeners.clear()
-    this.classListeners.clear()
+    this.#stringListeners.clear()
+    this.#classListeners.clear()
   }
 
   /**
@@ -191,17 +191,17 @@ export class Emitter {
    */
   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])
+    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
+    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
+    for (const list of this.#stringListeners.values()) total += list.length
+    for (const list of this.#classListeners.values()) total += list.length
     return total
   }
 
@@ -216,7 +216,7 @@ export class Emitter {
    */
   async #dispatchListeners(event: string, data: unknown, serial: boolean): Promise<void> {
     const listeners = [
-      ...(this.stringListeners.get(event) ?? []),
+      ...(this.#stringListeners.get(event) ?? []),
       ...this.#wildcardListenersFor(event),
     ]
     if (listeners.length === 0) return
@@ -224,7 +224,7 @@ export class Emitter {
       try {
         await fn(data)
       } catch (err) {
-        this.emitError(event, err)
+        this.#emitError(event, err)
       }
     }
     if (serial) {
@@ -281,17 +281,17 @@ export class Emitter {
     try {
       payload = JSON.stringify(this.#wrapForBus(data))
     } catch (err) {
-      this.emitError(event, err)
+      this.#emitError(event, err)
       return
     }
-    void this.bus.emit(event, payload).catch((err: unknown) => {
-      this.emitError(event, err)
+    void this.#bus.emit(event, payload).catch((err: unknown) => {
+      this.#emitError(event, err)
     })
   }
 
   /** Emit an error event for listener failures. */
-  private emitError(event: string, error: unknown): void {
-    const errorListeners = this.stringListeners.get('emitter:error')
+  #emitError(event: string, error: unknown): void {
+    const errorListeners = this.#stringListeners.get('emitter:error')
     if (errorListeners && errorListeners.length > 0) {
       for (const fn of errorListeners) {
         try {
@@ -314,7 +314,7 @@ export class Emitter {
     // 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 listeners = this.#classListeners.get(EventClass) ?? []
     const name = (EventClass as { eventName?: string }).eventName ?? classToEventName(EventClass)
 
     // Per-listener error isolation — mirrors the string `emit()` contract.
@@ -326,22 +326,22 @@ export class Emitter {
       try {
         if (isListenerClass(listener)) {
           // Listener class — resolve via container for @inject() support
-          const instance = this.resolver
-            ? await this.resolver.make(listener as ListenerConstructor<T>)
+          const instance = this.#resolver
+            ? await this.#resolver.make(listener as ListenerConstructor<T>)
             : new (listener as ListenerConstructor<T>)()
           await instance.handle(event)
         } else {
           await (listener as ListenerFn<T>)(event)
         }
       } catch (err) {
-        this.emitError(name, err)
+        this.#emitError(name, err)
       }
     }
 
     // Also push through EventBus — same correlation-envelope wrapping as
     // the string-event path so distributed tracing covers class events too.
     // Reached unconditionally: a listener failure above no longer skips it.
-    await this.bus.emit(name, JSON.stringify(this.#wrapForBus(event)))
+    await this.#bus.emit(name, JSON.stringify(this.#wrapForBus(event)))
   }
 
   // ─── Faking (AdonisJS `fake` / `restore`) ─────────────────
@@ -436,7 +436,7 @@ export class Emitter {
     pattern: string,
     listener: (eventName: string, data: unknown) => void,
   ): Promise<number> {
-    return this.bus.subscribe(pattern, (eventJson: string) => {
+    return this.#bus.subscribe(pattern, (eventJson: string) => {
       try {
         const event = JSON.parse(eventJson)
         // The bus delivers a Rust `Event` envelope whose `correlationId`
@@ -471,7 +471,7 @@ export class Emitter {
    */
   async offAny(listenerOrId: number | ((eventName: string, data: unknown) => void)): Promise<this> {
     if (typeof listenerOrId === 'number') {
-      await this.bus.unsubscribe(listenerOrId)
+      await this.#bus.unsubscribe(listenerOrId)
       for (const ids of this.#anySubscriptions.values()) ids.delete(listenerOrId)
       return this
     }
@@ -479,13 +479,13 @@ export class Emitter {
     const ids = this.#anySubscriptions.get(listenerOrId)
     if (!ids) return this
     this.#anySubscriptions.delete(listenerOrId)
-    await Promise.all([...ids].map((id) => this.bus.unsubscribe(id)))
+    await Promise.all([...ids].map((id) => this.#bus.unsubscribe(id)))
     return this
   }
 
   /** Check if a pattern matches an event name (wildcard matching via Rust). */
   matchesPattern(pattern: string, eventName: string): boolean {
-    return this.bus.matchesWildcard(pattern, eventName)
+    return this.#bus.matchesWildcard(pattern, eventName)
   }
 
   // ─── Request / Reply ──────────────────────────────────────
@@ -499,7 +499,7 @@ export class Emitter {
     // Same correlation injection as `emit()` so a `setCorrelationId`
     // preceding a request actually reaches the responder via the
     // top-level `correlationId` field on the parsed payload.
-    const result = await this.bus.request(name, JSON.stringify(this.#wrapForBus(data)), timeoutMs)
+    const result = await this.#bus.request(name, JSON.stringify(this.#wrapForBus(data)), timeoutMs)
     try {
       return JSON.parse(result) as T
     } catch {
@@ -519,7 +519,7 @@ export class Emitter {
     name: string,
     handler: (eventJson: string, reply: (response: string) => void) => void,
   ): void {
-    this.bus.onRequest(name, handler)
+    this.#bus.onRequest(name, handler)
   }
 
   // ─── Correlation context ──────────────────────────────────
@@ -565,13 +565,13 @@ export class Emitter {
     // 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
+    if (typeof event === 'string') return (this.#stringListeners.get(event)?.length ?? 0) > 0
+    return (this.#classListeners.get(event)?.length ?? 0) > 0
   }
 
   /** Get the number of Rust-side subscriptions. */
   async subscriptionCount(): Promise<number> {
-    return this.bus.subscriptionCount()
+    return this.#bus.subscriptionCount()
   }
 }
 

package/src/events/native.ts

@@ -10,22 +10,28 @@
 
 import { loadNapi } from '../helpers/napi-loader.js'
 
-/** Rust-backed bus surface (mirrors the napi `#[napi] EventBus` exports). */
-export interface EventBus {
-  emit(name: string, data: string): Promise<string>
-  subscribe(pattern: string, callback: (eventJson: string) => void): number
-  unsubscribe(subscriptionId: number): Promise<void>
-  onRequest(
-    name: string,
-    callback: (eventJson: string, reply: (response: string) => void) => void,
-  ): void
-  request(name: string, data: string, timeoutMs?: number): Promise<string>
-  matchesWildcard(pattern: string, eventName: string): boolean
-  subscriptionCount(): Promise<number>
-}
+/**
+ * Rust-backed bus surface.
+ *
+ * Re-exported from the generated declarations rather than restated here: the
+ * shape is derived from the `#[napi]` items themselves, so it cannot drift
+ * from the Rust. It did before — making `Bus::on_request` synchronous changed
+ * the Rust with nothing on this side to notice.
+ *
+ * Run `pnpm build:napi-types` after touching a `#[napi]` signature.
+ */
+import type { EventBus as NativeEventBus } from '../native/generated.js'
 
+/**
+ * What the `events` binary exports.
+ *
+ * The instance shape comes from the generated declarations — derived from the
+ * `#[napi]` items, so it cannot drift from the Rust without the generated file
+ * changing. Only the constructor is named here, because the binary is a module
+ * object rather than a class the loader can see.
+ */
 interface EventsNative {
-  EventBus: new (requestHandlerTimeoutMs?: number) => EventBus
+  EventBus: new (requestHandlerTimeoutMs?: number) => NativeEventBus
 }
 
 const native = loadNapi<EventsNative>({
@@ -35,3 +41,4 @@ const native = loadNapi<EventsNative>({
 })
 
 export const EventBus = native.EventBus
+export type EventBus = NativeEventBus

package/src/helpers/compose.ts

@@ -0,0 +1,84 @@
+/**
+ * Compose a class by applying mixins to it.
+ *
+ *   class User extends compose(BaseModel, SoftDeletes, Sluggable) {}
+ *
+ * Each mixin is a function taking the class built so far and returning a
+ * subclass of it, so the chain is a plain left fold. Written out by hand that
+ * is `Sluggable(SoftDeletes(BaseModel))`, which reads inside-out and gets
+ * worse with every mixin — the whole point of the helper.
+ *
+ * The overloads exist so the RETURN type is the last mixin's, not the base
+ * class's: without them a composed class would lose every member the mixins
+ * added, statics included.
+ *
+ * Note there is no `Constructor` bound on `T`. The mixin's own parameter type
+ * already constrains what can be passed, and a bound would have to be written
+ * with `any` to admit a class with typed constructor arguments.
+ */
+
+/** A mixin: takes the class built so far, returns a subclass of it. */
+type Mixin<T, R> = (superclass: T) => R
+
+export function compose<T, A>(superclass: T, a: Mixin<T, A>): A
+export function compose<T, A, B>(superclass: T, a: Mixin<T, A>, b: Mixin<A, B>): B
+export function compose<T, A, B, C>(
+  superclass: T,
+  a: Mixin<T, A>,
+  b: Mixin<A, B>,
+  c: Mixin<B, C>,
+): C
+export function compose<T, A, B, C, D>(
+  superclass: T,
+  a: Mixin<T, A>,
+  b: Mixin<A, B>,
+  c: Mixin<B, C>,
+  d: Mixin<C, D>,
+): D
+export function compose<T, A, B, C, D, E>(
+  superclass: T,
+  a: Mixin<T, A>,
+  b: Mixin<A, B>,
+  c: Mixin<B, C>,
+  d: Mixin<C, D>,
+  e: Mixin<D, E>,
+): E
+export function compose<T, A, B, C, D, E, F>(
+  superclass: T,
+  a: Mixin<T, A>,
+  b: Mixin<A, B>,
+  c: Mixin<B, C>,
+  d: Mixin<C, D>,
+  e: Mixin<D, E>,
+  f: Mixin<E, F>,
+): F
+export function compose<T, A, B, C, D, E, F, G>(
+  superclass: T,
+  a: Mixin<T, A>,
+  b: Mixin<A, B>,
+  c: Mixin<B, C>,
+  d: Mixin<C, D>,
+  e: Mixin<D, E>,
+  f: Mixin<E, F>,
+  g: Mixin<F, G>,
+): G
+export function compose<T, A, B, C, D, E, F, G, H>(
+  superclass: T,
+  a: Mixin<T, A>,
+  b: Mixin<A, B>,
+  c: Mixin<B, C>,
+  d: Mixin<C, D>,
+  e: Mixin<D, E>,
+  f: Mixin<E, F>,
+  g: Mixin<F, G>,
+  h: Mixin<G, H>,
+): H
+
+/**
+ * The single implementation. Its parameters are deliberately looser than the
+ * overloads above — a variadic fold cannot express "each mixin takes what the
+ * previous one returned" — and the overloads are what callers see.
+ */
+export function compose(superclass: unknown, ...mixins: Mixin<unknown, unknown>[]): unknown {
+  return mixins.reduce((applied, mixin) => mixin(applied), superclass)
+}

package/src/helpers/index.ts

@@ -1,5 +1,6 @@
 export { Secret } from '../env/Secret.js'
 export { base64 } from './base64.js'
+export { compose } from './compose.js'
 export { defineStaticProperty } from './defineStaticProperty.js'
 export { milliseconds, seconds } from './duration.js'
 export type { ImportAllFilesOptions, ReadAllFilesOptions } from './fs.js'

package/src/helpers/is.ts

@@ -140,23 +140,94 @@ export function isEmpty(v: unknown): boolean {
   return false
 }
 
+/**
+ * Returns true if value is a string with at least one character.
+ * @example isNonEmptyString('hi') // true; isNonEmptyString('') // false
+ */
+export function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.length > 0
+}
+
+/**
+ * Returns true if value is an array with at least one element.
+ * @example isNonEmptyArray([1]) // true; isNonEmptyArray([]) // false
+ */
+export function isNonEmptyArray<T = unknown>(v: unknown): v is [T, ...T[]] {
+  return Array.isArray(v) && v.length > 0
+}
+
+/**
+ * Returns true if value is an integer. `Number.isInteger` already excludes NaN
+ * and the infinities.
+ * @example isInteger(42) // true; isInteger(4.2) // false
+ */
+export function isInteger(v: unknown): v is number {
+  return Number.isInteger(v)
+}
+
+/**
+ * Returns true if value is a number greater than zero. Zero is NOT positive
+ * here, matching `@sindresorhus/is`.
+ * @example isPositive(1) // true; isPositive(0) // false
+ */
+export function isPositive(v: unknown): v is number {
+  return typeof v === 'number' && !Number.isNaN(v) && v > 0
+}
+
+/**
+ * Returns true if `key` is an OWN property of `value`.
+ *
+ * Own, not inherited: an inherited `toString` is not something the caller put
+ * there, and treating it as present is how a prototype member gets mistaken
+ * for data.
+ * @example hasProperty({ a: 1 }, 'a') // true; hasProperty({}, 'toString') // false
+ */
+export function hasProperty<K extends PropertyKey>(
+  value: unknown,
+  key: K,
+): value is Record<K, unknown> {
+  return value !== null && typeof value === 'object' && Object.hasOwn(value, key)
+}
+
+/**
+ * The `is` namespace, keyed the way AdonisJS keys it.
+ *
+ * Adonis re-exports `@sindresorhus/is`, whose members read `is.string(v)`,
+ * `is.plainObject(v)`, `is.nonEmptyArray(v)`. This object used to mirror the
+ * function names instead — `is.isString(v)` — which stutters, and which turns
+ * `is.string(value)` ported from an Adonis app into "is.string is not a
+ * function" at runtime rather than a compile error.
+ *
+ * The standalone `isX` functions above keep their names: they read correctly
+ * on their own, and this object is the namespace form.
+ */
 const is = {
-  isString,
-  isNumber,
-  isBoolean,
-  isFunction,
-  isObject,
-  isPlainObject,
-  isArray,
-  isPromise,
-  isNull,
-  isUndefined,
-  isNullOrUndefined,
-  isBuffer,
-  isDate,
-  isRegExp,
-  isError,
-  isEmpty,
+  string: isString,
+  number: isNumber,
+  boolean: isBoolean,
+  function: isFunction,
+  object: isObject,
+  plainObject: isPlainObject,
+  array: isArray,
+  promise: isPromise,
+  null: isNull,
+  undefined: isUndefined,
+  nullOrUndefined: isNullOrUndefined,
+  buffer: isBuffer,
+  date: isDate,
+  regExp: isRegExp,
+  error: isError,
+  nonEmptyString: isNonEmptyString,
+  nonEmptyArray: isNonEmptyArray,
+  integer: isInteger,
+  positive: isPositive,
+  hasProperty: hasProperty,
+  /**
+   * Named deviation: `@sindresorhus/is` has `emptyString` / `emptyArray` /
+   * `emptyObject` / `emptyMap` / `emptySet` but no umbrella. This is the
+   * umbrella, and the one member here that is not a type guard.
+   */
+  empty: isEmpty,
 }
 
 export default is

package/src/index.ts

@@ -8,6 +8,7 @@ import 'reflect-metadata'
 
 // ─── Core ───────────────────────────────────────────────────
 
+export type { AppEnvironment, ApplicationMode, ApplicationState } from './Application.js'
 export { Application } from './Application.js'
 export { ConfigStore, configProvider, defineModuleConfig, env } from './ConfigLoader.js'
 export { Container } from './container/Container.js'
@@ -201,7 +202,7 @@ export {
 // ─── Middleware ──────────────────────────────────────────────
 
 export type { MiddlewareFunction } from './middleware/Pipeline.js'
-export { compose, MiddlewareRegistry } from './middleware/Pipeline.js'
+export { composeMiddleware, MiddlewareRegistry } from './middleware/Pipeline.js'
 
 // ─── HttpKernel ─────────────────────────────────────────────
 
@@ -242,7 +243,6 @@ export type {
   FlagMetaData,
 } from './console/types.js'
 export type {
-  AppEnvironment,
   HyperServerLike,
   IgnitorConfig,
   ReamrcConfig,
@@ -371,4 +371,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.4'
+export const VERSION = '0.2.6'

package/src/middleware/Pipeline.ts

@@ -170,12 +170,18 @@ export class MiddlewareRegistry {
       handler,
     ]
 
-    return compose(stack)
+    return composeMiddleware(stack)
   }
 }
 
-/** Compose middleware into a single handler (onion pattern). */
-function compose(middleware: MiddlewareFunction[]): MiddlewareFunction {
+/**
+ * Compose middleware into a single handler (onion pattern).
+ *
+ * NOT `compose` — that name means mixin composition in `helpers`, the way it
+ * does in AdonisJS, and the two were one import away from each other on the
+ * barrel.
+ */
+function composeMiddleware(middleware: MiddlewareFunction[]): MiddlewareFunction {
   return async (ctx: HttpContext, finalNext: () => Promise<void>) => {
     let index = -1
 
@@ -257,4 +263,4 @@ function createValidationMiddleware(validators: RuntimeValidator[]): MiddlewareF
   }
 }
 
-export { compose }
+export { composeMiddleware }