@c9up/ream 0.2.1 → 0.2.3

package/src/http/Request.ts

@@ -7,6 +7,7 @@
  * @implements FR21
  */
 
+import { parseQueryString } from '../bodyparser/qsParse.js'
 import type { CookieSigner } from '../security/CookieSigner.js'
 import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Dict } from '../types/helpers.js'
@@ -701,6 +702,10 @@ export class Request extends Macroable {
   /** Get parsed query string as an object. */
   qs(): Dict<unknown> {
     if (!this.#parsedQs) {
+      // The same parser the body parser uses. A local one lived here and split
+      // on "&" only: `?filter[status]=open` stayed the literal key
+      // "filter[status]", and `?tags[]=a&tags[]=b` silently kept only "b" —
+      // both are ordinary shapes for a filter or an HTML multi-select.
       this.#parsedQs = parseQueryString(this.#raw.query)
     }
     return { ...this.#parsedQs }
@@ -1012,22 +1017,6 @@ function safeDecode(value: string): string {
   }
 }
 
-function parseQueryString(qs: string): Dict<unknown> {
-  if (!qs) return {}
-  const result: Dict<unknown> = {}
-  for (const pair of qs.split('&')) {
-    const eqIdx = pair.indexOf('=')
-    if (eqIdx === -1) {
-      result[safeDecode(pair)] = ''
-    } else {
-      const key = safeDecode(pair.slice(0, eqIdx))
-      const value = safeDecode(pair.slice(eqIdx + 1))
-      result[key] = value
-    }
-  }
-  return result
-}
-
 interface AcceptEntry {
   value: string
   q: number

package/src/index.ts

@@ -40,6 +40,7 @@ export {
   createError,
   E_FORBIDDEN,
   E_HTTP_EXCEPTION,
+  E_HTTP_REQUEST_ABORTED,
   E_ROUTE_NOT_FOUND,
   E_ROW_NOT_FOUND,
   E_UNAUTHORIZED,
@@ -48,6 +49,7 @@ export {
   type ExceptionClass,
   type ExceptionConstructor,
   ExceptionHandler,
+  type HttpError,
   InvalidArgumentsException,
   RuntimeException,
   type StatusPageRenderer,
@@ -58,6 +60,8 @@ export { RedirectBuilder } from './http/RedirectBuilder.js'
 export type { RawRequest } from './http/Request.js'
 export { Request } from './http/Request.js'
 export { Response } from './http/Response.js'
+export type { SseStreamOptions } from './http/SseStream.js'
+export { SseStream } from './http/SseStream.js'
 export { type GetterFn, Macroable, type MacroFn } from './utils/Macroable.js'
 
 // ─── Session ────────────────────────────────────────────────
@@ -77,6 +81,12 @@ export type {
   SessionRedisClientSource,
 } from './session/drivers/RedisDriver.js'
 export { RedisDriver as SessionRedisDriver } from './session/drivers/RedisDriver.js'
+export {
+  E_SESSION_NOT_READY,
+  E_SESSION_TAGGING_NOT_SUPPORTED,
+} from './session/errors.js'
+export type { ValuePath } from './session/ReadOnlyValuesStore.js'
+export { ReadOnlyValuesStore } from './session/ReadOnlyValuesStore.js'
 export type {
   SessionConfig,
   SessionDriver,
@@ -139,7 +149,11 @@ export { StaticProvider } from './storage/StaticProvider.js'
 
 // Request-filter security (CSRF, XSS, rate-limit, CORS, headers, path/param)
 // lives in @c9up/blackhole. ream core keeps only the crypto primitives.
-export { CookieSigner } from './security/CookieSigner.js'
+export {
+  CookieSigner,
+  E_INSECURE_APP_KEY,
+  E_MISSING_APP_KEY,
+} from './security/CookieSigner.js'
 export {
   constantTimeEq,
   hasNativeCrypto,
@@ -179,6 +193,7 @@ export {
   matchers,
   OnRouteBuilder,
   RouteBuilder,
+  RouteResource,
   Router,
   UrlBuilder,
 } from './router/Router.js'
@@ -238,8 +253,15 @@ export { ConsoleKernel, defineConfig, Ignitor, prettyPrintError } from './Ignito
 
 // ─── Providers ──────────────────────────────────────────────
 
+export { errors } from './errors/aggregate.js'
 export type { AppContext, ProviderContract } from './Provider.js'
 export { Provider } from './Provider.js'
+export type {
+  AuthenticatorName,
+  Authenticators,
+  ContainerBinding,
+  ContainerBindings,
+} from './types/index.js'
 
 // ─── Codemods ───────────────────────────────────────────────
 
@@ -349,4 +371,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.1.7'
+export const VERSION = '0.2.3'

package/src/router/Router.ts

@@ -402,6 +402,54 @@ export class RouteBuilder extends Macroable {
   getDefinition(): RouteDefinition {
     return this.#primary()
   }
+
+  /**
+   * The handler this route dispatches to (AdonisJS `route.getHandler`).
+   *
+   * Either the inline function or the controller/method pair — a route always
+   * has exactly one of the two.
+   */
+  getHandler(): RouteHandlerFunction | { target: AnyConstructor; method: string } | null {
+    const route = this.#primary()
+    return route.controller ?? route.handler
+  }
+
+  /**
+   * Every middleware attached to this route (AdonisJS `route.getMiddleware`).
+   *
+   * Named entries and inline functions in one list, in the order they run.
+   */
+  getMiddleware(): Array<string | MiddlewareFunction> {
+    const route = this.#primary()
+    return [...route.middleware, ...route.inlineMiddleware]
+  }
+
+  /**
+   * A serialisable description of this route (AdonisJS `route.toJSON`).
+   *
+   * What a routes-list command or a route-manifest generator reads, and why it
+   * carries names rather than the functions themselves.
+   */
+  toJSON(): {
+    name?: string
+    pattern: string
+    methods: string[]
+    handler: RouteHandlerFunction | { target: AnyConstructor; method: string } | null
+    middleware: string[]
+    domain?: string
+    matchers: Record<string, ParamMatcher>
+  } {
+    const route = this.#primary()
+    return {
+      ...(route.name === undefined ? {} : { name: route.name }),
+      pattern: route.path,
+      methods: this.#routes.map((entry) => entry.method),
+      handler: this.getHandler(),
+      middleware: [...route.middleware],
+      ...(route.domain === undefined ? {} : { domain: route.domain }),
+      matchers: { ...route.matchers },
+    }
+  }
 }
 
 // ─── GroupBuilder ───────────────────────────────────────────
@@ -415,6 +463,16 @@ export class GroupBuilder extends Macroable {
     this.#routes = routes
   }
 
+  /**
+   * The routes this group wraps (AdonisJS `group.routes`).
+   *
+   * Read-only view: a group applies to its members, it does not hand out the
+   * backing array for someone else to splice.
+   */
+  get routes(): readonly RouteDefinition[] {
+    return [...this.#routes]
+  }
+
   /** Set URL prefix for all routes in the group. */
   prefix(p: string): this {
     for (const route of this.#routes) {
@@ -705,6 +763,8 @@ function isViewEngine(value: unknown): value is ViewEngine {
 export class OnRouteBuilder {
   #router: Router
   #path: string
+  /** The route built by `render`/`redirect`/`redirectToPath`/`setHandler`. */
+  #route: RouteBuilder | undefined
 
   constructor(router: Router, path: string) {
     this.#router = router
@@ -721,7 +781,7 @@ export class OnRouteBuilder {
    * seeds its own engine there.
    */
   render(view: string, data?: Record<string, unknown>): RouteBuilder {
-    return this.#router.get(this.#path, async (ctx) => {
+    this.#route = this.#router.get(this.#path, async (ctx) => {
       const candidate = Reflect.get(Object(ctx), 'view') ?? ctx.store.get('view')
       if (!isViewEngine(candidate)) {
         throw new Error(
@@ -732,6 +792,7 @@ export class OnRouteBuilder {
       const html = await candidate.render(view, data)
       ctx.response.type('text/html; charset=utf-8').send(html)
     })
+    return this.#route
   }
 
   /**
@@ -740,16 +801,38 @@ export class OnRouteBuilder {
    * for a fixed URL.
    */
   redirect(name: string, params?: Record<string, string>, status = 302): RouteBuilder {
-    return this.#router.get(this.#path, async (ctx) => {
+    this.#route = this.#router.get(this.#path, async (ctx) => {
       ctx.response.redirect().status(status).toRoute(name, params)
     })
+    return this.#route
   }
 
   /** Redirect to a fixed path/URL (AdonisJS brisk `redirectToPath`). */
   redirectToPath(target: string, status = 302): RouteBuilder {
-    return this.#router.get(this.#path, async (ctx) => {
+    this.#route = this.#router.get(this.#path, async (ctx) => {
       ctx.response.redirect().status(status).toPath(target)
     })
+    return this.#route
+  }
+
+  /**
+   * Register a handler for this path (AdonisJS brisk `setHandler`).
+   *
+   * The escape hatch from the canned briskness: `render` and `redirect` cover
+   * the two common cases, this covers the third without going back through
+   * `router.get()`.
+   */
+  setHandler(handler: RouteHandlerFunction): RouteBuilder {
+    this.#route = this.#router.get(this.#path, handler)
+    return this.#route
+  }
+
+  /**
+   * The route the last `render`/`redirect`/`setHandler` created, or
+   * `undefined` while none has been called (AdonisJS brisk `route`).
+   */
+  get route(): RouteBuilder | undefined {
+    return this.#route
   }
 }
 
@@ -1236,7 +1319,7 @@ export class Router extends Macroable {
   makeSignedUrl(name: string, params?: Record<string, string>, options?: SignedUrlOptions): string {
     if (!this.#signedUrl) {
       throw new Error(
-        '[E_NO_APP_KEY] makeSignedUrl() requires an APP_KEY-backed signer. Set APP_KEY (>= 16 chars) so the encryption service is registered.',
+        '[E_MISSING_APP_KEY] makeSignedUrl() requires an APP_KEY-backed signer. Set APP_KEY (>= 16 chars) so the encryption service is registered.',
       )
     }
     const path = this.urlFor(name, params)

package/src/services/app.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Application } from '../Application.js'
+import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: Application | undefined
 
@@ -25,28 +26,10 @@ export function clearApp(app: Application): void {
   if (instance === app) instance = undefined
 }
 
-const app: Application = new Proxy({} as Application, {
-  get(_target, prop) {
-    // A module loader inspects what it imports before anyone uses it: it reads
-    // `then` to decide whether the namespace is thenable, and various symbols
-    // for interop and formatting. Throwing on those turns a plain
-    // `import { setX } from '.../services/x'` into a crash at import time, far
-    // from any real use. They are not members of what this stands in for, so
-    // answer undefined and let a genuine access be the one that reports.
-    if (typeof prop === 'symbol' || prop === 'then') {
-      return undefined
-    }
-    if (!instance) {
-      throw new Error(
-        'Application accessed before initialization. ' +
-          'Ensure this code runs during or after the boot phase.',
-      )
-    }
-    // Bind methods so private-field writes inside the class resolve
-    // against the real instance brand instead of the Proxy.
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const app: Application = createServiceProxy<Application>(
+  () => instance,
+  'Application accessed before initialization. ' +
+    'Ensure this code runs during or after the boot phase.',
+)
 
 export default app

package/src/services/console.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Console } from '../console/Console.js'
+import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: Console | undefined
 
@@ -26,26 +27,10 @@ export function clearConsole(consoleApp: Console): void {
   if (instance === consoleApp) instance = undefined
 }
 
-const consoleApp: Console = new Proxy({} as Console, {
-  get(_target, prop) {
-    // A module loader inspects what it imports before anyone uses it: it reads
-    // `then` to decide whether the namespace is thenable, and various symbols
-    // for interop and formatting. Throwing on those turns a plain
-    // `import { setX } from '.../services/x'` into a crash at import time, far
-    // from any real use. They are not members of what this stands in for, so
-    // answer undefined and let a genuine access be the one that reports.
-    if (typeof prop === 'symbol' || prop === 'then') {
-      return undefined
-    }
-    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
-  },
-})
+const consoleApp: Console = createServiceProxy<Console>(
+  () => instance,
+  'Console accessed before initialization. ' +
+    'Ensure this code runs during or after the boot phase.',
+)
 
 export default consoleApp

package/src/services/createServiceProxy.ts

@@ -0,0 +1,47 @@
+/**
+ * The one implementation behind every `@c9up/ream/services/*` accessor.
+ *
+ * Each accessor stands in for a singleton that only exists once the Ignitor has
+ * built it, so the module-level export is a proxy that forwards to whatever the
+ * boot phase installed. Written out per service, the proxy was copied five
+ * times and the `symbol`/`then` guard below reached only three of them — a fix
+ * that has to be applied by hand five times is a fix that will be missed.
+ *
+ * @see services/app.ts for the accessor shape this backs.
+ */
+
+/**
+ * Build the proxy an accessor module default-exports.
+ *
+ * @param read     Returns the live singleton, or `undefined` before boot.
+ * @param notReady Message thrown when something reads the accessor too early.
+ */
+export function createServiceProxy<T extends object>(
+  read: () => T | undefined,
+  notReady: string,
+): T {
+  // The target is never read through — every trap forwards to `read()`.
+  const target: T = Object.create(null)
+  return new Proxy(target, {
+    get(_target, prop) {
+      // A module loader inspects what it imports before anyone uses it: it
+      // reads `then` to decide whether the namespace is thenable, and various
+      // symbols for interop and formatting. Throwing on those turns a plain
+      // `import { setX } from '.../services/x'` into a crash at import time,
+      // far from any real use. They are not members of what this stands in
+      // for, so answer undefined and let a genuine access be the one that
+      // reports.
+      if (typeof prop === 'symbol' || prop === 'then') {
+        return undefined
+      }
+      const instance = read()
+      if (!instance) {
+        throw new Error(notReady)
+      }
+      // Bind methods so private-field writes inside the class resolve against
+      // the real instance brand instead of the Proxy.
+      const value = Reflect.get(instance, prop, instance)
+      return typeof value === 'function' ? value.bind(instance) : value
+    },
+  })
+}

package/src/services/router.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Router } from '../router/Router.js'
+import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: Router | undefined
 
@@ -34,19 +35,10 @@ export function getRouter(): Router | undefined {
  * Router proxy — defers all property access to the underlying instance.
  * Throws if accessed before Ignitor initializes it.
  */
-const router: Router = new Proxy({} as Router, {
-  get(_target, prop) {
-    if (!instance) {
-      throw new Error(
-        'Router accessed before initialization. ' +
-          'Ensure your route files are loaded as preloads in reamrc.ts, not at import time.',
-      )
-    }
-    // Bind methods so private-field writes inside the class resolve
-    // against the real instance brand instead of the Proxy.
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const router: Router = createServiceProxy<Router>(
+  () => instance,
+  'Router accessed before initialization. ' +
+    'Ensure your route files are loaded as preloads in reamrc.ts, not at import time.',
+)
 
 export default router

package/src/services/server.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Server } from '../server/Server.js'
+import { createServiceProxy } from './createServiceProxy.js'
 
 let instance: Server | undefined
 
@@ -29,29 +30,10 @@ export function getServer(): Server | undefined {
   return instance
 }
 
-const server: Server = new Proxy({} as Server, {
-  get(_target, prop) {
-    // A module loader inspects what it imports before anyone uses it: it reads
-    // `then` to decide whether the namespace is thenable, and various symbols
-    // for interop and formatting. Throwing on those turns a plain
-    // `import { setX } from '.../services/x'` into a crash at import time, far
-    // from any real use. They are not members of what this stands in for, so
-    // answer undefined and let a genuine access be the one that reports.
-    if (typeof prop === 'symbol' || prop === 'then') {
-      return undefined
-    }
-    if (!instance) {
-      throw new Error(
-        'Server accessed before initialization. ' +
-          'Ensure your kernel files are loaded as preloads in reamrc.ts.',
-      )
-    }
-    // Bind methods to the real instance so private-field access inside
-    // them resolves against the underlying class brand — passing the
-    // Proxy as `this` breaks `#field` writes (Proxy isn't branded).
-    const value = Reflect.get(instance, prop, instance)
-    return typeof value === 'function' ? value.bind(instance) : value
-  },
-})
+const server: Server = createServiceProxy<Server>(
+  () => instance,
+  'Server accessed before initialization. ' +
+    'Ensure your kernel files are loaded as preloads in reamrc.ts.',
+)
 
 export default server

package/src/session/ReadOnlyValuesStore.ts

@@ -49,4 +49,24 @@ export class ReadOnlyValuesStore {
   has(path: ValuePath): boolean {
     return this.get(path) !== undefined
   }
+
+  /**
+   * Every value, as a plain object (AdonisJS `toObject`).
+   *
+   * Same content as {@link all}; the two names exist because AdonisJS ships
+   * both and a migrated template may reach for either.
+   */
+  toObject(): Record<string, unknown> {
+    return this.all()
+  }
+
+  /** Every value — what `JSON.stringify(flashMessages)` emits. */
+  toJSON(): Record<string, unknown> {
+    return this.all()
+  }
+
+  /** JSON text, so `{{ flashMessages }}` in a template renders the contents. */
+  toString(): string {
+    return JSON.stringify(this.#values)
+  }
 }

package/src/session/Session.ts

@@ -11,6 +11,8 @@
  */
 
 import type { SessionRedisClientSource } from './drivers/RedisDriver.js'
+import { E_SESSION_NOT_READY, E_SESSION_TAGGING_NOT_SUPPORTED } from './errors.js'
+import { ReadOnlyValuesStore } from './ReadOnlyValuesStore.js'
 
 export interface SessionDriver {
   /**
@@ -435,9 +437,16 @@ export class Session {
     this.forget(INTENDED_URL_KEY)
   }
 
-  /** Get a flashed value from the previous request. */
-  flashMessages(): Record<string, unknown> {
-    return { ...this.#previousFlash }
+  /**
+   * What the PREVIOUS request flashed for this one (AdonisJS `flashMessages`).
+   *
+   * A property holding a store, not a method returning a record: that is the
+   * AdonisJS shape, and it is what lets a controller or template read a nested
+   * failure with `session.flashMessages.get('errors.email')`. `all()` gives
+   * back the plain object.
+   */
+  get flashMessages(): ReadOnlyValuesStore {
+    return new ReadOnlyValuesStore(this.#previousFlash)
   }
 
   /** Get a specific flash message from the previous request. */
@@ -519,8 +528,8 @@ export class Session {
    * live. `flashMessages` is the other half — what the PREVIOUS request left
    * for this one.
    */
-  get responseFlashMessages(): Record<string, unknown> {
-    return { ...this.#flashData }
+  get responseFlashMessages(): ReadOnlyValuesStore {
+    return new ReadOnlyValuesStore(this.#flashData)
   }
 
   /**
@@ -625,14 +634,10 @@ export class Session {
    */
   #taggingDriver(method: string): SessionDriverWithTagging {
     if (this.#driver === undefined) {
-      throw new Error(
-        `session.${method}() needs a session store — this session was built without one.`,
-      )
+      throw new E_SESSION_NOT_READY(method)
     }
     if (!supportsTagging(this.#driver)) {
-      throw new Error(
-        `session.${method}() is not supported by the configured session store. Use the memory, redis, or database store.`,
-      )
+      throw new E_SESSION_TAGGING_NOT_SUPPORTED(method)
     }
     return this.#driver
   }

package/src/session/SessionMiddleware.ts

@@ -232,7 +232,8 @@ function shareSessionWithView(ctx: HttpContext, session: Session): void {
   const view = Reflect.get(Object(ctx), 'view')
   const share = Reflect.get(Object(view), 'share')
   if (typeof share !== 'function') return
-  const flashMessages = new ReadOnlyValuesStore(session.flashMessages())
+  // The session hands back a store already — no need to rebuild one here.
+  const flashMessages = session.flashMessages
   share.call(view, {
     session: new ReadOnlyValuesStore(session.all()),
     flashMessages,

package/src/session/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * Session exceptions, under the codes AdonisJS raises.
+ *
+ * The conditions were already guarded — they just threw bare `Error`s, so an
+ * app could only match on the message text.
+ *
+ * `E_SESSION_NOT_MUTABLE` has no counterpart here on purpose: it is what
+ * AdonisJS raises for a session initiated in read-only mode, and ream has no
+ * read-only mode. Declaring the class with nothing able to throw it would be
+ * worse than its absence — an app would guard a branch that never runs.
+ */
+
+import { Exception } from '../http/Exception.js'
+
+/** The session was used before a store was attached to it. */
+export class E_SESSION_NOT_READY extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_NOT_READY'
+
+  constructor(method: string) {
+    super(`session.${method}() needs a session store — this session was built without one.`, {
+      status: 500,
+      code: 'E_SESSION_NOT_READY',
+    })
+  }
+}
+
+/** The configured store cannot tag sessions (cookie and file stores cannot). */
+export class E_SESSION_TAGGING_NOT_SUPPORTED extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_TAGGING_NOT_SUPPORTED'
+
+  constructor(method: string) {
+    super(
+      `session.${method}() is not supported by the configured session store. Use the memory, redis, or database store.`,
+      { status: 500, code: 'E_SESSION_TAGGING_NOT_SUPPORTED' },
+    )
+  }
+}

package/src/types/authenticators.ts

@@ -0,0 +1,24 @@
+/**
+ * Guard name → what `auth.use(name)` hands back.
+ *
+ * Empty here, and deliberately: ream owns no auth package, so it cannot know
+ * the guards an app configured. The auth package fills it in, exactly as
+ * AdonisJS does with `Authenticators`:
+ *
+ * ```ts
+ * declare module '@c9up/ream/types' {
+ *   interface Authenticators {
+ *     session: SessionGuard
+ *     jwt: JwtGuard
+ *   }
+ * }
+ * ```
+ *
+ * Until something augments it, `keyof Authenticators` is `never` and `use()`
+ * falls through to its `unknown` signature — the behaviour ream had before,
+ * kept as the floor rather than as the ceiling.
+ */
+export type Authenticators = {}
+
+/** A guard name this application knows about. */
+export type AuthenticatorName = keyof Authenticators