@c9up/ream 0.2.17 → 0.2.18

package/src/http/Request.ts

@@ -13,6 +13,12 @@ import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Dict } from '../types/helpers.js'
 import { Macroable } from '../utils/Macroable.js'
 import { getPath, omitPaths, pickPaths } from '../utils/objectPath.js'
+import type {
+  RequestAwareValidator,
+  RequestValidationOptions,
+  ValidatableContext,
+} from './RequestValidator.js'
+import { RequestValidator } from './RequestValidator.js'
 import { unpackCookieValue } from './Response.js'
 
 export interface RawRequest {
@@ -789,6 +795,44 @@ export class Request extends Macroable {
     return { ...this.#merged }
   }
 
+  /**
+   * The context a validation hook is handed.
+   *
+   * The whole context when this request has one, because that is where a hook
+   * finds what it needs — `ctx.i18n` for a translated message. A Request built
+   * by hand for a test has none, and stands in for itself.
+   */
+  #validationContext(): ValidatableContext {
+    const ctx = this.ctx
+    // Handed back as it is, never spread: a context carries accessors
+    // (`ctx.i18n` is one), and a spread would freeze each into a plain value
+    // read at this instant instead of when the hook asks for it.
+    if (ctx !== undefined && carriesRequest(ctx)) return ctx
+    return { request: this }
+  }
+
+  /**
+   * Validate this request, throwing `E_VALIDATION_ERROR` on failure.
+   *
+   * The entry point that lets a schema stay ignorant of the request: the
+   * per-request messages provider and error reporter are filled in here, from
+   * hooks a package installed at boot. See {@link RequestValidator}.
+   */
+  validateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<T> {
+    return new RequestValidator(this.#validationContext()).validateUsing(validator, options)
+  }
+
+  /** Validate this request, answering `[error, null]` or `[null, data]`. */
+  tryValidateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<[unknown, null] | [null, T]> {
+    return new RequestValidator(this.#validationContext()).tryValidateUsing(validator, options)
+  }
+
   /**
    * The original request input, captured once and never mutated (AdonisJS
    * `request.original`) — the basis for flash "old input" on validation errors.
@@ -1174,3 +1218,13 @@ function languageMatches(entry: string, offered: string): boolean {
   if (primary && primary === o.split('-')[0]) return true
   return false
 }
+
+/**
+ * Whether an object is a context wrapped around a real request.
+ *
+ * `Request.ctx` is deliberately typed `object` — the request must not depend
+ * on the context's shape — so this is where that opacity is paid back.
+ */
+function carriesRequest(value: object): value is ValidatableContext {
+  return 'request' in value && value.request instanceof Request
+}

package/src/http/RequestValidator.ts

@@ -0,0 +1,143 @@
+/**
+ * Per-request validation.
+ *
+ * A validator compiled when its module loaded knows nothing about the request
+ * about to run through it — yet the two things it most often needs are per
+ * request: which language to answer in, and where the errors go. The two
+ * static hooks below are that seam. An i18n package installs one at boot:
+ *
+ * ```ts
+ * RequestValidator.messagesProvider = (ctx) => ctx.i18n.createMessagesProvider()
+ * ```
+ *
+ * and every `request.validateUsing(...)` call picks it up, without a single
+ * schema mentioning translation. Nothing else in the framework reads them, so
+ * a validator called directly keeps whatever provider it was built with.
+ *
+ * Structural on purpose: ream never imports a validation package. Anything
+ * with a `validate(data, options)` fits, which is also what makes this
+ * testable without one.
+ */
+
+import type { HttpContext } from './HttpContext.ts'
+
+/** What a validator has to expose to be usable here. */
+export interface RequestAwareValidator<T> {
+  validate(data: Record<string, unknown>, options?: RequestValidationOptions): Promise<T>
+}
+
+/** Options forwarded to the validator, plus the data override. */
+export interface RequestValidationOptions {
+  /** Validate this instead of the request's own data. */
+  data?: Record<string, unknown>
+  /** Per-call messages provider — beats the static hook. */
+  messagesProvider?: unknown
+  /** Per-call error reporter factory — beats the static hook. */
+  errorReporter?: unknown
+  /** Arbitrary metadata a rule can read off the field context. */
+  meta?: Record<string, unknown>
+}
+
+/**
+ * The slice this class reads. A real {@link HttpContext} satisfies it, and so
+ * does a bare `{ request }` pair — which is what a Request built by hand, with
+ * no context around it, can still offer.
+ */
+export interface ValidatableContext {
+  request: {
+    all(): Record<string, unknown>
+    params(): Readonly<Record<string, string | string[]>>
+    headers(): Readonly<Record<string, unknown>>
+    cookiesList(): Record<string, unknown>
+  }
+}
+
+/**
+ * What a hook is handed. The full context when there is one — an i18n package
+ * reads `ctx.i18n` off it — and the narrow shape otherwise, which is why this
+ * is a union rather than just `HttpContext`.
+ */
+export type ValidationHookContext = HttpContext | ValidatableContext
+
+export class RequestValidator {
+  readonly #ctx: ValidatableContext
+
+  constructor(ctx: ValidatableContext) {
+    this.#ctx = ctx
+  }
+
+  /**
+   * Picks the error reporter for a request. Assigned once, at boot, by
+   * whatever package owns error formatting.
+   */
+  static errorReporter?: (ctx: ValidationHookContext) => unknown
+
+  /**
+   * Picks the messages provider for a request. Assigned once, at boot, by
+   * whatever package owns translations.
+   */
+  static messagesProvider?: (ctx: ValidationHookContext) => unknown
+
+  /**
+   * Everything a rule might address, in one object.
+   *
+   * `params`, `headers` and `cookies` are nested under their own keys rather
+   * than merged: a form field named `params` is ordinary, and flattening them
+   * would let a request rename its own route parameters.
+   */
+  #requestData(): Record<string, unknown> {
+    const { request } = this.#ctx
+    return {
+      ...request.all(),
+      params: request.params(),
+      headers: request.headers(),
+      cookies: request.cookiesList(),
+    }
+  }
+
+  /**
+   * Fill in the request-scoped reporter and provider, without overwriting
+   * anything the caller passed — an explicit option is a deliberate choice
+   * for this one call and must outrank a process-wide default.
+   */
+  #processOptions(options?: RequestValidationOptions): RequestValidationOptions {
+    const resolved: RequestValidationOptions = { ...options }
+    if (RequestValidator.errorReporter && resolved.errorReporter === undefined) {
+      const reporter = RequestValidator.errorReporter(this.#ctx)
+      // The validator expects a FACTORY, so a fresh reporter is built per run
+      // rather than one instance accumulating across requests.
+      resolved.errorReporter = () => reporter
+    }
+    if (RequestValidator.messagesProvider && resolved.messagesProvider === undefined) {
+      resolved.messagesProvider = RequestValidator.messagesProvider(this.#ctx)
+    }
+    return resolved
+  }
+
+  /** Validate the request, throwing `E_VALIDATION_ERROR` on failure. */
+  validateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<T> {
+    const resolved = this.#processOptions(options)
+    return validator.validate(resolved.data ?? this.#requestData(), resolved)
+  }
+
+  /**
+   * Validate the request, returning `[error, null]` or `[null, data]`.
+   *
+   * The tuple form exists so a handler can answer a failure itself instead of
+   * letting the exception reach the error handler — a wizard step that
+   * re-renders the form, say.
+   */
+  async tryValidateUsing<T>(
+    validator: RequestAwareValidator<T>,
+    options?: RequestValidationOptions,
+  ): Promise<[unknown, null] | [null, T]> {
+    try {
+      return [null, await this.validateUsing(validator, options)]
+    } catch (error) {
+      return [error, null]
+    }
+  }
+}

package/src/index.ts

@@ -60,6 +60,13 @@ export { HttpContext } from './http/HttpContext.js'
 export { RedirectBuilder } from './http/RedirectBuilder.js'
 export type { RawRequest } from './http/Request.js'
 export { Request } from './http/Request.js'
+export type {
+  RequestAwareValidator,
+  RequestValidationOptions,
+  ValidatableContext,
+  ValidationHookContext,
+} from './http/RequestValidator.js'
+export { RequestValidator } from './http/RequestValidator.js'
 export { Response } from './http/Response.js'
 export type { SseStreamOptions } from './http/SseStream.js'
 export { SseStream } from './http/SseStream.js'
@@ -378,4 +385,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.17'
+export const VERSION = '0.2.18'

package/src/middleware/Pipeline.ts

@@ -32,7 +32,7 @@ export interface RuntimeValidationResult {
  * 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()`
+ * Three spellings are accepted because `@c9up/rune` offers all three: `validate()`
  * is async and throws, `validateResult()` is synchronous and never throws, and
  * `validateResultAsync()` is the async result-based form.
  *
@@ -46,7 +46,7 @@ export interface RuntimeValidator {
   validateResultAsync?(data: unknown): Promise<RuntimeValidationResult>
 }
 
-/** A thrown validation failure, as raised by rune/VineJS `validate()`. */
+/** A thrown validation failure, as raised by rune's `validate()`. */
 interface ThrownValidationFailure {
   messages: unknown[]
 }
@@ -66,7 +66,7 @@ function isValidationResult(value: unknown): value is RuntimeValidationResult {
  * 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
+ * `unique` / `exists`), then the synchronous one, then the throwing
  * `validate()` — awaited, and with its `E_VALIDATION_ERROR` translated back
  * into a result so callers keep a single shape to handle.
  */
@@ -85,7 +85,7 @@ export async function runValidator(
   if (typeof validator.validate === 'function') {
     try {
       const outcome = await validator.validate(data)
-      // A result-returning `validate()` (not the VineJS contract) is honoured
+      // A result-returning `validate()` (not the throwing contract) is honoured
       // as-is; the throwing contract resolves to the validated payload.
       return isValidationResult(outcome) ? outcome : { valid: true, errors: [], data: outcome }
     } catch (err) {

package/src/migrations/MigrationRegistry.ts

@@ -27,6 +27,29 @@ export class MigrationRegistry {
     return this
   }
 
+  /**
+   * Remove a store's runner — only while it is still the one that registered.
+   *
+   * `register` refuses a duplicate name, deliberately: two providers claiming
+   * one name means one of them migrates nothing while the run reports success.
+   * But nothing ever removed a source, so a provider that shut down left its
+   * name taken and its runner holding a connection it had already closed. A
+   * second boot in the same process — a hot reload, a test that restarts the
+   * app — then failed on "already registered", and the CLI would have driven a
+   * runner pointing at a dead pool.
+   *
+   * `source` is the ownership guard. Two applications can share a process, and
+   * the one shutting down must not unregister the survivor's runner that
+   * happens to carry the same name.
+   */
+  unregister(name: string, source?: RegisteredMigrationSource): boolean {
+    const current = this.#sources.get(name)
+    if (current === undefined) return false
+    if (source !== undefined && current !== source) return false
+    this.#sources.delete(name)
+    return true
+  }
+
   /** Every registered store, in registration order. */
   all(): RegisteredMigrationSource[] {
     return [...this.#sources.values()]

package/src/openapi/OpenApiGenerator.ts

@@ -56,6 +56,16 @@ export class OpenApiGenerator {
   #router: Router
   #config: OpenApiConfig
   #runeSchemas: Map<string, Record<string, unknown>>
+  /**
+   * Schemas a validator produced itself, already in JSON Schema form.
+   *
+   * Kept apart from {@link #runeSchemas}, which holds rune FIELD MAPS that
+   * {@link #runeToJsonSchema} still has to convert. One map for both would
+   * mean guessing which kind a value is, and guessing wrong sends a finished
+   * schema back through the converter, which reads its `type` and `properties`
+   * keys as if they were field names.
+   */
+  #jsonSchemas = new Map<string, Record<string, unknown>>()
 
   constructor(
     router: Router,
@@ -72,6 +82,30 @@ export class OpenApiGenerator {
     this.#runeSchemas.set(name, definition)
   }
 
+  /**
+   * Fill the schema map from the validators the routes already name.
+   *
+   * `route.validate('createUser')` records a container token, and the
+   * validator behind it can describe itself. Without this step every one of
+   * those routes documented its body as a bare `{ type: 'object' }` unless the
+   * app ALSO called `registerSchema` by hand with a definition it had to keep
+   * in step with the schema — two descriptions of one payload, and nothing
+   * checking they agreed.
+   *
+   * Resolution happens once, here, because `generate()` is synchronous and the
+   * container is not. A validator that cannot be resolved, or that cannot
+   * describe itself, is skipped: a missing section of documentation is a
+   * smaller problem than a boot that fails over one.
+   */
+  async hydrateSchemas(resolve: (token: string) => Promise<unknown>): Promise<void> {
+    const names = new Set(this.#getRoutes().flatMap((route) => route.validators))
+    for (const name of names) {
+      if (this.#runeSchemas.has(name) || this.#jsonSchemas.has(name)) continue
+      const definition = await describeValidator(resolve, name)
+      if (definition !== undefined) this.#jsonSchemas.set(name, definition)
+    }
+  }
+
   /** Generate the complete OpenAPI 3.1 spec. */
   generate(): OpenApiSpec {
     const spec: OpenApiSpec = {
@@ -171,13 +205,13 @@ export class OpenApiGenerator {
 
     if (route.validators.length > 0 && ['post', 'put', 'patch'].includes(method)) {
       const [validatorName] = route.validators
-      const schema = validatorName === undefined ? undefined : this.#runeSchemas.get(validatorName)
-      if (schema && validatorName !== undefined) {
+      const body = validatorName === undefined ? undefined : this.#bodySchema(validatorName)
+      if (body && validatorName !== undefined) {
         operation.requestBody = {
           required: true,
-          content: { 'application/json': { schema: this.#runeToJsonSchema(schema) } },
+          content: { 'application/json': { schema: body } },
         }
-        schemas[validatorName] = this.#runeToJsonSchema(schema)
+        schemas[validatorName] = body
       } else {
         operation.requestBody = {
           required: true,
@@ -211,6 +245,17 @@ export class OpenApiGenerator {
     return `${route.method} ${route.path}`
   }
 
+  /**
+   * The JSON Schema for a named validator: what it described about itself
+   * first, then a hand-registered field map converted here.
+   */
+  #bodySchema(name: string): Record<string, unknown> | undefined {
+    const described = this.#jsonSchemas.get(name)
+    if (described !== undefined) return described
+    const fields = this.#runeSchemas.get(name)
+    return fields === undefined ? undefined : this.#runeToJsonSchema(fields)
+  }
+
   /** Convert a Rune schema (Record<string, RuleChain>) to JSON Schema. */
   #runeToJsonSchema(schema: Record<string, unknown>): Record<string, unknown> {
     const properties: Record<string, unknown> = {}
@@ -254,3 +299,38 @@ export class OpenApiGenerator {
     return this.#router.getRoutes()
   }
 }
+
+/** A validator that can describe its own shape as JSON Schema. */
+interface SelfDescribingValidator {
+  toJSONSchema(): Record<string, unknown>
+}
+
+function describesItself(value: unknown): value is SelfDescribingValidator {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'toJSONSchema' in value &&
+    typeof value.toJSONSchema === 'function'
+  )
+}
+
+/** Resolve one validator and ask it for its schema, or answer undefined. */
+async function describeValidator(
+  resolve: (token: string) => Promise<unknown>,
+  name: string,
+): Promise<Record<string, unknown> | undefined> {
+  let validator: unknown
+  try {
+    validator = await resolve(`validator:${name}`)
+  } catch {
+    // An unregistered validator is already a hard error at request time; the
+    // documentation is not the place to raise it a second time.
+    return undefined
+  }
+  if (!describesItself(validator)) return undefined
+  try {
+    return validator.toJSONSchema()
+  } catch {
+    return undefined
+  }
+}

package/src/openapi/OpenApiProvider.ts

@@ -1,11 +1,12 @@
 /**
  * `OpenApiProvider` — serves an auto-generated OpenAPI 3.1 spec + Swagger UI.
  *
- * `boot()` mounts a global middleware that, on the first GET to `/api-docs`
+ * `start()` mounts a global middleware that, on the first GET to `/api-docs`
  * (JSON) or `/docs` (Swagger UI), lazily generates the spec from the router's
- * registered routes — so every route registered during boot/start is included
- * (the spec must NOT be generated eagerly at boot, before other providers have
- * registered their routes). Opt-out via `config.openapi.enabled = false`.
+ * registered routes — so every route registered while the application starts
+ * up is included (the spec must NOT be generated eagerly, before the other
+ * providers and the preloads have registered their routes). Opt-out via
+ * `config.openapi.enabled = false`.
  *
  * @implements Story 24.4
  */
@@ -43,7 +44,17 @@ export class OpenApiProvider extends Provider {
     this.#override = options.generator
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const config = this.app.config.get<OpenApiDocsConfig>('openapi') ?? {}
     if (config.enabled === false) return
 
@@ -59,10 +70,14 @@ export class OpenApiProvider extends Provider {
 
   async #buildGenerator(config: OpenApiDocsConfig): Promise<OpenApiGenerator> {
     const router = await this.app.container.make<Router>('router')
-    return new OpenApiGenerator(router, {
+    const generator = new OpenApiGenerator(router, {
       title: config.title ?? 'API',
       version: config.version ?? '1.0.0',
     })
+    // The routes already name their validators; ask each one to describe
+    // itself instead of making the app repeat the shape by hand.
+    await generator.hydrateSchemas((token) => this.app.container.make<unknown>(token))
+    return generator
   }
 }
 

package/src/rpc/RpcProvider.ts

@@ -9,8 +9,9 @@
  *       rpc.method('task.validate', handler).guard('jwt')
  *       rpc.namespace('user', UserController)
  *
- *   - `boot()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
+ *   - `start()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
  *     dispatching every request body (single or batch) to `RpcRouter.handle()`.
+ *     In `start`, which is the phase upstream documents for routes.
  *
  * @implements Story 24.1, 24.2
  */
@@ -68,7 +69,17 @@ export class RpcProvider extends Provider {
     this.#registered = true
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const config = this.app.config.get<RpcConfig>('rpc')
     const path = config?.path ?? '/rpc'
     const router = await this.app.container.make<Router>('router')

package/src/storage/StaticProvider.ts

@@ -2,7 +2,7 @@
  * `StaticProvider` — serves static files from a directory.
  *
  * Opt-in: does nothing unless `config.static.root` is set (or a middleware is
- * injected for tests). When configured, `boot()` mounts a global
+ * injected for tests). When configured, `start()` mounts a global
  * `StaticMiddleware` (path-traversal + symlink-escape guarded) that serves
  * matching requests and falls through (`next()`) otherwise.
  *
@@ -30,7 +30,17 @@ export class StaticProvider extends Provider {
     this.#override = options.middleware
   }
 
-  override async boot(): Promise<void> {
+  /**
+   * Routes and server middleware go in `start`, not `boot`.
+   *
+   * Upstream documents that phase for exactly this, and the order is what makes
+   * it matter: providers boot, then providers START, then the preloads run —
+   * and the preloads are where an application writes its own routes and kernel.
+   * Mounted in `boot`, a framework route landed ahead of every application
+   * route, so an overlapping path was answered by the framework rather than by
+   * the app that meant to override it.
+   */
+  override async start(): Promise<void> {
     const config = this.app.config.get<StaticConfig>('static')
     const middleware = this.#override ?? (config?.root ? new StaticMiddleware(config) : undefined)
     if (!middleware) return // not configured — opt-out