@c9up/ream 0.1.26 → 0.1.28

package/src/index.ts

@@ -169,9 +169,35 @@ export { resolveMiddlewareEntry, Server } from './server/Server.js'
 
 // ─── Ignitor ────────────────────────────────────────────────
 
-export type { Command } from './console/CommandRunner.js'
-export { CommandRunner } from './console/CommandRunner.js'
-export type { AppEnvironment, HyperServerLike, IgnitorConfig, ReamrcConfig } from './Ignitor.js'
+export { BaseCommand } from './console/BaseCommand.js'
+export { Logger, Ui } from './console/cliui.js'
+export { args, flags } from './console/decorators.js'
+// Renamed at the root: Ream already exports an HTTP `ExceptionHandler`, and
+// two different things under one name is worse than a longer one. It keeps its
+// Console name on the console entry point.
+export { ExceptionHandler as ConsoleExceptionHandler } from './console/ExceptionHandler.js'
+export { default as HelpCommand } from './console/HelpCommand.js'
+export { IndexGenerator } from './console/IndexGenerator.js'
+export { Kernel } from './console/Kernel.js'
+export { default as ListCommand } from './console/ListCommand.js'
+export { FsLoader, ListLoader } from './console/loaders.js'
+export { Parser } from './console/parser.js'
+export { Prompt, PromptTrap } from './console/prompts.js'
+export type {
+  ArgumentMetaData,
+  CommandClass,
+  CommandInstance,
+  CommandOptions,
+  FlagMetaData,
+} from './console/types.js'
+export type {
+  AppEnvironment,
+  HyperServerLike,
+  IgnitorConfig,
+  ReamrcConfig,
+  TestSuiteConfig,
+  TestsConfig,
+} from './Ignitor.js'
 export { ConsoleKernel, defineConfig, Ignitor, prettyPrintError } from './Ignitor.js'
 
 // ─── Providers ──────────────────────────────────────────────
@@ -205,7 +231,7 @@ export {
   PIPELINE_STAGES,
   validatePipelineConfig,
 } from './errors/PipelineStageError.js'
-export { ReamError } from './errors/ReamError.js'
+export { isReamError, ReamError } from './errors/ReamError.js'
 
 // ─── Utilities ──────────────────────────────────────────────
 

package/src/middleware/Pipeline.ts

@@ -20,13 +20,84 @@ export type MiddlewareFunction = (
   next: () => Promise<void>,
 ) => Promise<void> | void
 
+/** What a route validator must hand back, whichever method it exposes. */
+export interface RuntimeValidationResult {
+  valid: boolean
+  errors: unknown[]
+  data?: unknown
+}
+
 /**
- * Structural contract for a route validator. A `@c9up/rune` schema matches this
- * shape, so ream stays decoupled from the validation engine — any object with a
- * `validate(data)` returning `{ valid, errors, data? }` works.
+ * Structural contract for a route validator. ream stays decoupled from the
+ * validation engine — any object exposing a result-returning check works.
+ *
+ * Three spellings are accepted because `@c9up/rune` follows VineJS: `validate()`
+ * is async and throws, `validateResult()` is synchronous and never throws, and
+ * `validateResultAsync()` is the async result-based form.
+ *
+ * `validateResultAsync` is preferred. The synchronous `validateResult()` cannot
+ * run async rules — with `unique`, `exists` or `useAsync` in the schema it
+ * throws a plain Error, which would surface as a 500 instead of a 422.
  */
 export interface RuntimeValidator {
-  validate(data: unknown): { valid: boolean; errors: unknown[]; data?: unknown }
+  validate?(data: unknown): RuntimeValidationResult | Promise<unknown>
+  validateResult?(data: unknown): RuntimeValidationResult
+  validateResultAsync?(data: unknown): Promise<RuntimeValidationResult>
+}
+
+/** A thrown validation failure, as raised by rune/VineJS `validate()`. */
+interface ThrownValidationFailure {
+  messages: unknown[]
+}
+
+function isThrownValidationFailure(value: unknown): value is ThrownValidationFailure {
+  return (
+    value instanceof Error && 'messages' in value && Array.isArray(Reflect.get(value, 'messages'))
+  )
+}
+
+function isValidationResult(value: unknown): value is RuntimeValidationResult {
+  return typeof value === 'object' && value !== null && 'valid' in value
+}
+
+/**
+ * Run a validator whatever contract it exposes, and always come back with a
+ * result object.
+ *
+ * Order matters: the async result form first (it is the only one that can run
+ * `unique` / `exists`), then the synchronous one, then VineJS's throwing
+ * `validate()` — awaited, and with its `E_VALIDATION_ERROR` translated back
+ * into a result so callers keep a single shape to handle.
+ */
+export async function runValidator(
+  validator: RuntimeValidator,
+  data: unknown,
+): Promise<RuntimeValidationResult> {
+  if (typeof validator.validateResultAsync === 'function') {
+    return validator.validateResultAsync(data)
+  }
+
+  if (typeof validator.validateResult === 'function') {
+    return validator.validateResult(data)
+  }
+
+  if (typeof validator.validate === 'function') {
+    try {
+      const outcome = await validator.validate(data)
+      // A result-returning `validate()` (not the VineJS contract) is honoured
+      // as-is; the throwing contract resolves to the validated payload.
+      return isValidationResult(outcome) ? outcome : { valid: true, errors: [], data: outcome }
+    } catch (err) {
+      if (isThrownValidationFailure(err)) {
+        return { valid: false, errors: err.messages }
+      }
+      throw err
+    }
+  }
+
+  throw new TypeError(
+    'Route validator exposes none of validateResultAsync(), validateResult() or validate().',
+  )
 }
 
 /** Named middleware registry. */
@@ -174,7 +245,7 @@ function createGuardMiddleware(
 function createValidationMiddleware(validators: RuntimeValidator[]): MiddlewareFunction {
   return async (ctx, next) => {
     for (const validator of validators) {
-      const result = validator.validate(ctx.request.body())
+      const result = await runValidator(validator, ctx.request.body())
       if (!result.valid) {
         throw new E_VALIDATION_ERROR(result.errors)
       }

package/src/rpc/RpcRouter.ts

@@ -20,7 +20,7 @@ import {
 } from '@c9up/comet'
 import type { HttpContext } from '../http/HttpContext.js'
 import type { MiddlewareRegistry, RuntimeValidator } from '../middleware/Pipeline.js'
-import { compose } from '../middleware/Pipeline.js'
+import { compose, runValidator } from '../middleware/Pipeline.js'
 
 export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown> | unknown
 
@@ -286,7 +286,21 @@ export class RpcRouter {
           )
         }
         const validator = await this.#container.resolve<RuntimeValidator>(token)
-        const outcome = validator.validate(params)
+        // `runValidator` picks the async result form first — the synchronous
+        // one cannot run `unique` / `exists` and throws outright when the schema
+        // carries them.
+        let outcome: Awaited<ReturnType<typeof runValidator>>
+        try {
+          outcome = await runValidator(validator, params)
+        } catch (err) {
+          return rpcError(
+            -32603,
+            err instanceof TypeError
+              ? `Validator '${def.validator}' exposes no usable validate method.`
+              : `Validator '${def.validator}' failed: ${err instanceof Error ? err.message : String(err)}`,
+            id,
+          )
+        }
         if (!outcome.valid) return rpcError(-32602, 'Invalid params', id, outcome.errors)
         effectiveParams = outcome.data ?? params
       }

package/src/services/app.ts

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   import app from '@c9up/ream/services/app'
- *   const logger = app.container.make('logger')
+ *   const logger = await app.container.make('logger')
  *   if (app.inProduction) { ... }
  */
 

package/src/services/console.ts

@@ -0,0 +1,42 @@
+/**
+ * Console singleton service.
+ *
+ * Usage:
+ *   import consoleApp from '@c9up/ream/services/console'
+ *   if (await consoleApp.hasCommand('make:controller')) {
+ *     const command = await consoleApp.exec('make:controller', ['user', '--resource'])
+ *   }
+ */
+
+import type { Console } from '../console/Console.js'
+
+let instance: Console | undefined
+
+/** @internal Set the consoleApp instance (called by Ignitor). */
+export function setConsole(consoleApp: Console): void {
+  instance = consoleApp
+}
+
+/**
+ * @internal Unset the locator IF it still points at `consoleApp` (called by
+ * Ignitor.stop()) — same ownership guard as the app service: a second Ignitor
+ * rebinding the locator must not be torn down by the first one stopping.
+ */
+export function clearConsole(consoleApp: Console): void {
+  if (instance === consoleApp) instance = undefined
+}
+
+const consoleApp: Console = new Proxy({} as Console, {
+  get(_target, prop) {
+    if (!instance) {
+      throw new Error(
+        'Console accessed before initialization. ' +
+          'Ensure this code runs during or after the boot phase.',
+      )
+    }
+    const value = Reflect.get(instance, prop, instance)
+    return typeof value === 'function' ? value.bind(instance) : value
+  },
+})
+
+export default consoleApp