@c9up/ream 0.2.11 → 0.2.12

package/src/container/Container.ts

@@ -282,7 +282,7 @@ export class Container {
       key = this.#tokenToKey(target)
       if (seenAliases.has(key)) {
         const cycle = [...seenAliases, key].join(' → ')
-        throw new ReamError('CIRCULAR_DEPENDENCY', `Circular alias detected: ${cycle}`, {
+        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 },
         })
@@ -302,7 +302,7 @@ export class Container {
 
     if (chain.set.has(key)) {
       const cycle = [...chain.stack, key].join(' → ')
-      throw new ReamError('CIRCULAR_DEPENDENCY', `Circular dependency detected: ${cycle}`, {
+      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 },
       })
@@ -565,7 +565,7 @@ export class Container {
     const allKeys = [...this.#bindings.keys(), ...this.#overrides.keys()]
     const suggestion = didYouMean(key, allKeys)
     throw new ReamError(
-      'CONTAINER_NOT_FOUND',
+      'E_CONTAINER_NOT_FOUND',
       `No binding found for '${key}'.${suggestion ? ` ${suggestion}` : ''}`,
       {
         hint: 'Register it with container.singleton() or decorate with @inject().',
@@ -666,7 +666,7 @@ export class Container {
       //     instead of `new target()` with undefined deps.
       if (target.length > 0) {
         throw new ReamError(
-          'CONTAINER_MISSING_METADATA',
+          'E_CONTAINER_MISSING_METADATA',
           `Cannot auto-construct ${target.name}: it declares ${target.length} constructor parameter(s) but no dependency metadata was found.`,
           {
             hint: 'Enable decorator metadata (swc/tsc emitDecoratorMetadata), annotate constructor params with @Inject(token), or declare static containerInjections.',
@@ -734,13 +734,13 @@ export class Container {
       // is the global registry and round-trips across modules.
       if (Symbol.keyFor(token) === undefined) {
         throw new ReamError(
-          'CONTAINER_INVALID_TOKEN',
+          '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('CONTAINER_INVALID_TOKEN', 'Symbol tokens must have a description.')
+        throw new ReamError('E_CONTAINER_INVALID_TOKEN', 'Symbol tokens must have a description.')
       }
       this.#assertNotReserved(desc, 'symbol description')
       return `Symbol(${desc})`
@@ -750,9 +750,13 @@ export class Container {
 
   #assertNotReserved(name: string, kind: 'string' | 'symbol description'): void {
     if (RESERVED_TOKEN_NAMES.has(name)) {
-      throw new ReamError('CONTAINER_RESERVED_TOKEN', `Reserved container token name '${name}'.`, {
-        hint: `'${name}' would collide with an Object.prototype key. Pick a different ${kind}.`,
-      })
+      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}.`,
+        },
+      )
     }
   }
 }

package/src/errors/ModuleErrors.ts

@@ -3,6 +3,10 @@
  *
  * Each module gets its own error class with appropriate defaults.
  *
+ * Every code these produce is `E_<MODULE>_<REASON>`: `E_` because that is what
+ * every framework code carries, the module name because a bare `E_NOT_FOUND`
+ * would not say which half of the framework raised it.
+ *
  * @implements FR71
  */
 
@@ -11,7 +15,7 @@ import { ReamError } from './ReamError.js'
 /** Container / IoC errors */
 export class ContainerError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`CONTAINER_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_CONTAINER_${code}`, message, options)
     this.name = 'ContainerError'
   }
 }
@@ -19,7 +23,7 @@ export class ContainerError extends ReamError {
 /** Router errors */
 export class RouterError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`ROUTER_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_ROUTER_${code}`, message, options)
     this.name = 'RouterError'
   }
 }
@@ -27,7 +31,7 @@ export class RouterError extends ReamError {
 /** Pipeline / Middleware errors */
 export class PipelineError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`PIPELINE_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_PIPELINE_${code}`, message, options)
     this.name = 'PipelineError'
   }
 }
@@ -35,7 +39,7 @@ export class PipelineError extends ReamError {
 /** Atlas ORM errors */
 export class AtlasError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`ATLAS_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_ATLAS_${code}`, message, options)
     this.name = 'AtlasError'
   }
 }
@@ -43,7 +47,7 @@ export class AtlasError extends ReamError {
 /** Rune validation errors */
 export class RuneError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`RUNE_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_RUNE_${code}`, message, options)
     this.name = 'RuneError'
   }
 }
@@ -51,7 +55,7 @@ export class RuneError extends ReamError {
 /** Warden auth errors */
 export class WardenError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`WARDEN_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_WARDEN_${code}`, message, options)
     this.name = 'WardenError'
   }
 }
@@ -59,7 +63,7 @@ export class WardenError extends ReamError {
 /** Event bus errors */
 export class EventsError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`EVENTS_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_EVENTS_${code}`, message, options)
     this.name = 'EventsError'
   }
 }
@@ -67,7 +71,7 @@ export class EventsError extends ReamError {
 /** Forge CLI errors */
 export class ForgeError extends ReamError {
   constructor(code: string, message: string, options?: ConstructorParameters<typeof ReamError>[2]) {
-    super(`FORGE_${code}`, message, options)
+    super(code.startsWith('E_') ? code : `E_FORGE_${code}`, message, options)
     this.name = 'ForgeError'
   }
 }

package/src/errors/PipelineStageError.ts

@@ -7,7 +7,7 @@
 import { ReamError } from './ReamError.js'
 
 /** Pipeline stage names in execution order. */
-export const PIPELINE_STAGES = [
+export const E_PIPELINE_STAGES = [
   'Security (Blackhole)',
   'Logging',
   'Global Middleware',
@@ -20,12 +20,12 @@ export const PIPELINE_STAGES = [
   'Response Logging',
 ] as const
 
-export type PipelineStageName = (typeof PIPELINE_STAGES)[number]
+export type PipelineStageName = (typeof E_PIPELINE_STAGES)[number]
 
 /**
  * Create a pipeline stage error with position context.
  *
- * @param stageIndex - Zero-based index in PIPELINE_STAGES (clamped to valid range)
+ * @param stageIndex - Zero-based index in E_PIPELINE_STAGES (clamped to valid range)
  * @param originalError - The error that occurred
  * @param context - Additional context
  */
@@ -34,13 +34,13 @@ export function createPipelineError(
   originalError: Error,
   context?: Record<string, string>,
 ): ReamError {
-  const total = PIPELINE_STAGES.length
+  const total = E_PIPELINE_STAGES.length
   const clampedIndex = Math.max(0, Math.min(stageIndex, total - 1))
-  const stageName = PIPELINE_STAGES[clampedIndex]
+  const stageName = E_PIPELINE_STAGES[clampedIndex]
   const position = `${clampedIndex + 1}/${total}`
-  const nextStage = clampedIndex + 1 < total ? PIPELINE_STAGES[clampedIndex + 1] : '(end)'
+  const nextStage = clampedIndex + 1 < total ? E_PIPELINE_STAGES[clampedIndex + 1] : '(end)'
 
-  const errorCode = originalError instanceof ReamError ? originalError.code : 'PIPELINE_ERROR'
+  const errorCode = originalError instanceof ReamError ? originalError.code : 'E_PIPELINE_ERROR'
 
   return new ReamError(errorCode, originalError.message, {
     pipelineStage: `${position} (${stageName})`,
@@ -80,7 +80,7 @@ export function validatePipelineConfig(config: {
         if (!registered.has(mw) && !reported.has(mw)) {
           reported.add(mw)
           errors.push(
-            new ReamError('PIPELINE_UNKNOWN_MIDDLEWARE', `Middleware '${mw}' is not registered`, {
+            new ReamError('E_PIPELINE_UNKNOWN_MIDDLEWARE', `Middleware '${mw}' is not registered`, {
               hint: `Register it with middleware.register('${mw}', handler) before using it on routes.`,
               context: {
                 middleware: mw,

package/src/errors/ReamError.ts

@@ -42,10 +42,20 @@ export function isReamError(error: unknown, ...codes: string[]): boolean {
 
 export class ReamError extends Error {
   /**
-   * Error code, `E_`-prefixed as every framework code is — an application
-   * matching on one should never have to remember which convention a
-   * particular package followed (e.g. "E_ATLAS_QUERY_ERROR",
-   * "E_CONTAINER_NOT_FOUND").
+   * Error code: `E_<NAMESPACE>_<REASON>`.
+   *
+   * `E_` because every framework code carries it, so an application can filter
+   * on one rule instead of remembering which convention a package followed.
+   * The namespace after it says which package raised the error — without it
+   * `E_FORBIDDEN` would mean three different things across the ecosystem and a
+   * consumer could not tell them apart (e.g. "E_ATLAS_QUERY_ERROR",
+   * "E_CONTAINER_NOT_FOUND", "E_WARDEN_UNKNOWN_POLICY").
+   *
+   * The exception is an identifier that already exists upstream —
+   * `E_UNAUTHORIZED_ACCESS`, `E_INVALID_CREDENTIALS`, `E_VALIDATION_ERROR`.
+   * Those are passed through verbatim, so code branching on one sees the same
+   * string it would elsewhere, and two packages naming the same upstream
+   * failure legitimately share it.
    */
   readonly code: string
 
@@ -98,7 +108,7 @@ export class ReamError extends Error {
     try {
       const parsed = JSON.parse(error.message)
       if (typeof parsed !== 'object' || parsed === null || typeof parsed.code !== 'string') {
-        return new ReamError('UNKNOWN', error.message)
+        return new ReamError('E_UNKNOWN', error.message)
       }
       return new ReamError(parsed.code, parsed.message ?? error.message, {
         context:
@@ -110,7 +120,7 @@ export class ReamError extends Error {
       })
     } catch {
       // Not a JSON error — wrap as generic
-      return new ReamError('UNKNOWN', error.message)
+      return new ReamError('E_UNKNOWN', error.message)
     }
   }
 

package/src/graphql/GraphQLProvider.ts

@@ -53,7 +53,7 @@ export class GraphQLProvider extends Provider {
         return
       }
       throw new ReamError(
-        'GRAPHQL_PROVIDER_ALREADY_REGISTERED',
+        'E_GRAPHQL_PROVIDER_ALREADY_REGISTERED',
         "Container token 'graphql' is already bound to a different instance",
         {
           hint: 'Only one GraphQLProvider can own the graphql binding. Remove the duplicate provider from your reamrc.ts.',

package/src/index.ts

@@ -286,7 +286,7 @@ export {
 export type { PipelineStageName } from './errors/PipelineStageError.js'
 export {
   createPipelineError,
-  PIPELINE_STAGES,
+  E_PIPELINE_STAGES,
   validatePipelineConfig,
 } from './errors/PipelineStageError.js'
 export { isReamError, ReamError } from './errors/ReamError.js'
@@ -378,4 +378,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.11'
+export const VERSION = '0.2.12'

package/src/middleware/Pipeline.ts

@@ -188,7 +188,7 @@ function composeMiddleware(middleware: MiddlewareFunction[]): MiddlewareFunction
 
     async function dispatch(i: number): Promise<void> {
       if (i <= index) {
-        throw new ReamError('PIPELINE_DOUBLE_NEXT', 'next() called multiple times', {
+        throw new ReamError('E_PIPELINE_DOUBLE_NEXT', 'next() called multiple times', {
           hint: 'A middleware called next() more than once. Each middleware should call next() at most once.',
         })
       }

package/src/rpc/RpcProvider.ts

@@ -56,7 +56,7 @@ export class RpcProvider extends Provider {
       // `container.resolve('rpc')` because resolution is now async.
       if (this.#registered) return
       throw new ReamError(
-        'RPC_PROVIDER_ALREADY_REGISTERED',
+        'E_RPC_PROVIDER_ALREADY_REGISTERED',
         "Container token 'rpc' is already bound to a different instance",
         {
           hint: 'Only one RpcProvider can own the rpc binding. Remove the duplicate provider from your reamrc.ts.',

package/src/scheduler/Schedule.ts

@@ -55,7 +55,7 @@ export function Schedule(cronExpr: string): MethodDecorator {
     // prototype. We need the real class either way.
     if (typeof target === 'function') {
       throw new ReamError(
-        'SCHEDULE_INVALID_TARGET',
+        'E_SCHEDULE_INVALID_TARGET',
         `@Schedule cannot be applied to static method '${String(propertyKey)}'`,
         {
           hint: 'Move the scheduled logic to an instance method, or register the task manually via Scheduler.register().',
@@ -67,7 +67,7 @@ export function Schedule(cronExpr: string): MethodDecorator {
     // accessors, and the ticker needs a callable method.
     if (descriptor && typeof descriptor.value !== 'function') {
       throw new ReamError(
-        'SCHEDULE_INVALID_TARGET',
+        'E_SCHEDULE_INVALID_TARGET',
         `@Schedule cannot be applied to non-method '${String(propertyKey)}' (getters and setters are not supported)`,
         {
           hint: 'Apply @Schedule to a regular method, not to an accessor.',

package/src/scheduler/ScheduleProvider.ts

@@ -63,7 +63,7 @@ export class ScheduleProvider extends Provider {
    * reload, repeated `app.start()` in tests) re-binds the same
    * scheduler without error. A DIFFERENT `ScheduleProvider` trying
    * to claim the `'scheduler'` token throws
-   * `SCHEDULE_PROVIDER_ALREADY_REGISTERED` so dueling providers do
+   * `E_SCHEDULE_PROVIDER_ALREADY_REGISTERED` so dueling providers do
    * not silently overwrite each other.
    */
   override register(): void {
@@ -74,7 +74,7 @@ export class ScheduleProvider extends Provider {
       // `container.resolve('scheduler')` because resolution is now async.
       if (this.#registered) return
       throw new ReamError(
-        'SCHEDULE_PROVIDER_ALREADY_REGISTERED',
+        'E_SCHEDULE_PROVIDER_ALREADY_REGISTERED',
         "Container token 'scheduler' is already bound to a different instance",
         {
           hint: 'Only one ScheduleProvider can own the scheduler binding. Remove the duplicate provider from your reamrc.ts.',
@@ -133,7 +133,7 @@ export class ScheduleProvider extends Provider {
 
         if (!target.name) {
           throw new ReamError(
-            'SCHEDULE_ANONYMOUS_CLASS',
+            'E_SCHEDULE_ANONYMOUS_CLASS',
             'Anonymous classes cannot declare @Schedule — task names would collide',
             {
               hint: 'Name the class explicitly (e.g. `export class Jobs { ... }`) so task names are unique and debuggable.',
@@ -148,7 +148,7 @@ export class ScheduleProvider extends Provider {
           // documented contract.
           if (typeof methodName === 'symbol') {
             throw new ReamError(
-              'SCHEDULE_SYMBOL_METHOD',
+              'E_SCHEDULE_SYMBOL_METHOD',
               `@Schedule on symbol-keyed method is not supported on class '${target.name}'`,
               {
                 hint: 'Use a regular named method so the task can be addressed uniquely.',
@@ -167,7 +167,7 @@ export class ScheduleProvider extends Provider {
               const method = instance[methodName]
               if (typeof method !== 'function') {
                 throw new ReamError(
-                  'SCHEDULE_METHOD_NOT_FOUND',
+                  'E_SCHEDULE_METHOD_NOT_FOUND',
                   `Scheduled method ${taskName} is not callable on resolved instance`,
                 )
               }
@@ -178,7 +178,7 @@ export class ScheduleProvider extends Provider {
           } catch (cause) {
             const inner = cause as ReamError & { message?: string; hint?: string }
             throw new ReamError(
-              'SCHEDULE_INVALID_CRON',
+              'E_SCHEDULE_INVALID_CRON',
               `Failed to register scheduled task '${taskName}': ${inner.message ?? String(cause)}`,
               {
                 context: { task: taskName, cronExpr },

package/src/scheduler/Scheduler.ts

@@ -62,7 +62,7 @@ export interface RunTaskOptions {
   /**
    * Cancel the on-demand run after `timeoutMs` milliseconds. On
    * timeout, `runTaskNow` returns `{ outcome: 'failed', error: ... }`
-   * with a `SCHEDULE_TASK_TIMEOUT` error. The user callback continues
+   * with a `E_SCHEDULE_TASK_TIMEOUT` error. The user callback continues
    * running in the background — JavaScript does not support
    * pre-emptive cancellation; the timeout is observational only.
    */
@@ -140,18 +140,18 @@ function loadNative(): NativeModule {
 /**
  * Convert a thrown native error into a `ReamError`. Prefers parsing the
  * JSON payload shipped by Rust (`ream_napi_core::ReamError::into()`);
- * falls back to wrapping opaque errors under `SCHEDULER_NATIVE_ERROR`
+ * falls back to wrapping opaque errors under `E_SCHEDULER_NATIVE_ERROR`
  * so scheduler context is never lost.
  */
 function translateNativeError(e: unknown): ReamError {
   const asError = e as Error
   const parsed = ReamError.fromNapi(asError)
-  // `fromNapi` returns an `UNKNOWN`-coded error when the message is not
+  // `fromNapi` returns an `E_UNKNOWN`-coded error when the message is not
   // a JSON payload. Preserve that context under a scheduler-specific
   // code so callers can trace the failure back to this layer.
-  if (parsed.code === 'UNKNOWN') {
+  if (parsed.code === 'E_UNKNOWN') {
     return new ReamError(
-      'SCHEDULER_NATIVE_ERROR',
+      'E_SCHEDULER_NATIVE_ERROR',
       `ream-scheduler NAPI call failed: ${asError.message}`,
       {
         hint: 'This is likely a bug in the scheduler. Please file an issue with the stack trace.',
@@ -204,7 +204,7 @@ export class Scheduler {
       const be = options.lockBackend as Partial<LockBackend>
       if (typeof be.acquire !== 'function' || typeof be.release !== 'function') {
         throw new ReamError(
-          'SCHEDULE_INVALID_LOCK_BACKEND',
+          'E_SCHEDULE_INVALID_LOCK_BACKEND',
           'Scheduler options.lockBackend must implement acquire(name, ttlMs) and release(name)',
         )
       }
@@ -212,7 +212,7 @@ export class Scheduler {
     if (options.defaultLockTtlMs !== undefined) {
       if (!Number.isFinite(options.defaultLockTtlMs) || options.defaultLockTtlMs <= 0) {
         throw new ReamError(
-          'SCHEDULE_INVALID_LOCK_TTL',
+          'E_SCHEDULE_INVALID_LOCK_TTL',
           `Scheduler options.defaultLockTtlMs must be a finite positive number, got ${options.defaultLockTtlMs}`,
           {
             hint: 'Use a millisecond value greater than zero (typical range 1_000 – 600_000).',
@@ -224,14 +224,14 @@ export class Scheduler {
       const sink = options.eventSink as Partial<ScheduleEventSink>
       if (typeof sink.emit !== 'function') {
         throw new ReamError(
-          'SCHEDULE_INVALID_EVENT_SINK',
+          'E_SCHEDULE_INVALID_EVENT_SINK',
           'Scheduler options.eventSink must implement emit(event)',
         )
       }
     }
     if (options.errorReporter !== undefined && typeof options.errorReporter !== 'function') {
       throw new ReamError(
-        'SCHEDULE_INVALID_ERROR_REPORTER',
+        'E_SCHEDULE_INVALID_ERROR_REPORTER',
         'Scheduler options.errorReporter must be a function',
       )
     }
@@ -376,13 +376,13 @@ export class Scheduler {
   ): void {
     if (typeof callback !== 'function') {
       throw new ReamError(
-        'SCHEDULE_INVALID_CALLBACK',
+        'E_SCHEDULE_INVALID_CALLBACK',
         `Scheduler.register expected a function callback for task '${name}', got ${typeof callback}`,
       )
     }
     if (name === '') {
       throw new ReamError(
-        'SCHEDULE_INVALID_TASK_NAME',
+        'E_SCHEDULE_INVALID_TASK_NAME',
         'Scheduler.register requires a non-empty task name',
       )
     }
@@ -451,7 +451,7 @@ export class Scheduler {
       // thrown error here is unexpected. Drop the local entry anyway
       // — the doc promises idempotence — but surface any unexpected
       // native failure that is not a missing-task situation.
-      if (err.code !== 'UNKNOWN_TASK' && err.code !== 'SCHEDULER_NATIVE_ERROR') {
+      if (err.code !== 'UNKNOWN_TASK' && err.code !== 'E_SCHEDULER_NATIVE_ERROR') {
         this.#tasks.delete(name)
         throw err
       }
@@ -538,7 +538,7 @@ export class Scheduler {
       // real task invocations.
       this.#report(
         new ReamError(
-          'SCHEDULE_TASK_UNKNOWN',
+          'E_SCHEDULE_TASK_UNKNOWN',
           `runTaskNow called with unknown task name: '${name}'`,
         ),
         name,
@@ -560,7 +560,7 @@ export class Scheduler {
                   outcome: 'failed',
                   durationMs: options.timeoutMs ?? 0,
                   error: new ReamError(
-                    'SCHEDULE_TASK_TIMEOUT',
+                    'E_SCHEDULE_TASK_TIMEOUT',
                     `Task '${name}' did not complete within ${options.timeoutMs} ms (background execution continues)`,
                   ),
                 })

package/src/scheduler/locks/LockBackend.ts

@@ -51,7 +51,7 @@ export interface LockBackend {
 export function assertValidTtl(ttlMs: number): void {
   if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
     throw new ReamError(
-      'SCHEDULE_INVALID_LOCK_TTL',
+      'E_SCHEDULE_INVALID_LOCK_TTL',
       `Lock TTL must be a finite positive number, got ${ttlMs}`,
       {
         hint: 'Use a millisecond value greater than zero (typical range 1_000 - 600_000).',