@c9up/ream 0.2.2 → 0.2.4

package/src/helpers/string.ts

@@ -1,5 +1,6 @@
-import { randomBytes } from 'node:crypto'
+import { randomBytes, randomUUID } from 'node:crypto'
 import bytes from './bytes.js'
+import { milliseconds, seconds } from './duration.js'
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -79,6 +80,135 @@ export function titleCase(s: string): string {
     .join(' ')
 }
 
+/**
+ * Space-separated lowercase words.
+ * @example noCase('userName') // 'user name'
+ */
+export function noCase(s: string): string {
+  return splitWords(s).join(' ')
+}
+
+/**
+ * Dot-separated lowercase words.
+ * @example dotCase('userName') // 'user.name'
+ */
+export function dotCase(s: string): string {
+  return splitWords(s).join('.')
+}
+
+/**
+ * Every word capitalised, space separated.
+ * @example capitalCase('user_name') // 'User Name'
+ */
+export function capitalCase(s: string): string {
+  return titleCase(s)
+}
+
+/**
+ * First word capitalised, the rest lowercase.
+ * @example sentenceCase('userName') // 'User name'
+ */
+export function sentenceCase(s: string): string {
+  const words = splitWords(s)
+  if (words.length === 0) return ''
+  const [first, ...rest] = words
+  return [(first ?? '').charAt(0).toUpperCase() + (first ?? '').slice(1), ...rest].join(' ')
+}
+
+/**
+ * Join values the way a sentence does.
+ * @example sentence(['a', 'b', 'c']) // 'a, b, and c'
+ */
+export function sentence(
+  values: readonly unknown[],
+  options: { separator?: string; pairSeparator?: string; lastSeparator?: string } = {},
+): string {
+  const parts = values.map((value) => String(value))
+  if (parts.length === 0) return ''
+  if (parts.length === 1) return parts[0] ?? ''
+  const separator = options.separator ?? ', '
+  const pairSeparator = options.pairSeparator ?? ' and '
+  const lastSeparator = options.lastSeparator ?? ', and '
+  if (parts.length === 2) return parts.join(pairSeparator)
+  return parts.slice(0, -1).join(separator) + lastSeparator + parts[parts.length - 1]
+}
+
+/**
+ * Wrap text at `width`, breaking on spaces.
+ *
+ * A word longer than the width is left whole rather than cut: breaking an
+ * identifier or a URL mid-token is worse than an over-long line.
+ */
+export function wordWrap(
+  value: string,
+  options: { width: number; indent?: string; newLine?: string },
+): string {
+  const width = Math.max(1, Math.floor(options.width))
+  const indent = options.indent ?? ''
+  const newLine = options.newLine ?? '\n'
+  const lines: string[] = []
+  let line = ''
+  for (const word of value.split(/\s+/).filter(Boolean)) {
+    if (line.length === 0) {
+      line = word
+    } else if (line.length + 1 + word.length <= width) {
+      line += ` ${word}`
+    } else {
+      lines.push(line)
+      line = word
+    }
+  }
+  if (line.length > 0) lines.push(line)
+  return lines.map((entry, index) => (index === 0 ? entry : indent + entry)).join(newLine)
+}
+
+/**
+ * Pad every column to the same width.
+ * @example justify(['a', 'bb'], { width: 4 }) // ['a   ', 'bb  ']
+ */
+export function justify(
+  columns: readonly string[],
+  options: { width: number; align?: 'left' | 'right'; indent?: string },
+): string[] {
+  const width = Math.max(0, Math.floor(options.width))
+  const indent = options.indent ?? ''
+  return columns.map((column) => {
+    const padded =
+      options.align === 'right' ? column.padStart(width, ' ') : column.padEnd(width, ' ')
+    return indent + padded
+  })
+}
+
+/** A RFC 4122 v4 UUID. */
+export function uuid(): string {
+  return randomUUID()
+}
+
+/** `ordinal` under the name AdonisJS also ships it as. */
+export function ordinalize(value: number): string {
+  return ordinal(value)
+}
+
+/** `sentence` under the name AdonisJS also ships it as. */
+export function toSentence(
+  values: readonly unknown[],
+  options?: { separator?: string; pairSeparator?: string; lastSeparator?: string },
+): string {
+  return sentence(values, options)
+}
+
+/** `escapeHTML` under the name @poppinss/string ships it as. */
+export function htmlEscape(value: string): string {
+  return escapeHTML(value)
+}
+
+/**
+ * Pluralise `word`, honouring a count: `pluralize('item', 1)` stays singular.
+ */
+export function pluralize(word: string, count?: number): string {
+  return count === 1 ? singular(word) : plural(word)
+}
+
 /**
  * Converts a snake_case/camelCase string to a human-readable form.
  * @example humanize('user_name') // 'User name'
@@ -466,6 +596,20 @@ const string = {
   prettyHrTime,
   toUnixSlash,
   interpolate,
+  noCase,
+  dotCase,
+  capitalCase,
+  sentenceCase,
+  sentence,
+  toSentence,
+  wordWrap,
+  justify,
+  uuid,
+  ordinalize,
+  htmlEscape,
+  pluralize,
+  seconds,
+  milliseconds,
 }
 
 export default string

package/src/http/HttpContext.ts

@@ -14,6 +14,7 @@ import type { MatchedParams } from '../router/Router.js'
 import type { CookieSigner } from '../security/CookieSigner.js'
 import type { SignedUrl } from '../security/SignedUrl.js'
 import type { Session } from '../session/Session.js'
+import type { Authenticators } from '../types/index.js'
 import { Macroable } from '../utils/Macroable.js'
 import type { RouteUrlResolver } from './RedirectBuilder.js'
 import { RedirectBuilder } from './RedirectBuilder.js'
@@ -47,7 +48,19 @@ export interface AuthState {
   check?(): Promise<boolean>
   authenticateUsing?(guards?: string[], options?: { loginRoute?: string }): Promise<void>
   getUserOrFail?(): AuthState['user']
-  use?(name: string): unknown
+  /**
+   * The guard behind `name` (AdonisJS `auth.use('web')`).
+   *
+   * Typed through the augmentable `Authenticators` interface in
+   * `@c9up/ream/types`: an app whose auth package augments it gets the guard's
+   * real type back, while a host that augments nothing still resolves to
+   * `unknown` rather than failing to compile. Without this, reaching a guard
+   * needed a cast that lies about a contract ream does not own.
+   */
+  use?: {
+    <Name extends keyof Authenticators>(name: Name): Authenticators[Name]
+    (name: string): unknown
+  }
   readonly authenticationAttempted?: boolean
   readonly authenticatedViaGuard?: string
 }

package/src/http/RedirectBuilder.ts

@@ -13,16 +13,27 @@ import type { Response } from './Response.js'
 
 export type RouteUrlResolver = (name: string, params?: Record<string, string>) => string
 
-function isSameOriginOrRelative(referer: string, requestUrl?: string): boolean {
+function isSameOriginOrRelative(
+  referer: string,
+  requestUrl?: string,
+  allowedHosts: readonly string[] = [],
+): boolean {
   // A relative path is trusted only when it starts with a single "/" and has no
   // backslash: browsers normalise "\" to "/", so "/\evil.com" would become the
   // protocol-relative "//evil.com" that a lone `!startsWith("//")` check misses.
   if (referer.startsWith('/') && !referer.startsWith('//') && !referer.includes('\\')) return true
+  let ref: URL
+  try {
+    ref = new URL(referer)
+  } catch {
+    return false
+  }
+  // An explicitly allowed host is trusted whatever the request's own origin is
+  // — that is what the list is for (AdonisJS `allowedHosts`).
+  if (allowedHosts.includes(ref.host)) return true
   if (!requestUrl) return false
   try {
-    const ref = new URL(referer)
-    const req = new URL(requestUrl)
-    return ref.origin === req.origin
+    return ref.origin === new URL(requestUrl).origin
   } catch {
     return false
   }
@@ -35,6 +46,14 @@ export interface IntendedUrlStore {
 }
 
 export class RedirectBuilder {
+  /**
+   * Hosts a redirect-back may leave the origin for (AdonisJS `allowedHosts`).
+   *
+   * Empty by default, which keeps `back()` same-origin only — an open-redirect
+   * is exactly what an unvalidated Referer buys.
+   */
+  allowedHosts: string[] = []
+
   #response: Response
   #status = 302
   #qs: Record<string, unknown> = {}
@@ -193,12 +212,23 @@ export class RedirectBuilder {
    * to `fallback` to prevent open redirect attacks.
    */
   back(fallback = '/'): void {
+    this.toPath(this.getPreviousUrl(fallback))
+  }
+
+  /**
+   * Where "back" goes (AdonisJS `getPreviousUrl`).
+   *
+   * Reads the Referer and validates its host, returning `fallback` when there
+   * is nothing trustworthy. Public and overridable on purpose: resolving the
+   * previous URL from the session instead of the header is the documented
+   * reason to replace it.
+   */
+  getPreviousUrl(fallback = '/'): string {
     const referer = this.#requestReferer
-    if (referer && isSameOriginOrRelative(referer, this.#requestUrl)) {
-      this.toPath(referer)
-    } else {
-      this.toPath(fallback)
+    if (referer && isSameOriginOrRelative(referer, this.#requestUrl, this.allowedHosts)) {
+      return referer
     }
+    return fallback
   }
 
   /**

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 }
@@ -999,35 +1004,6 @@ function isIpLiteral(host: string): boolean {
   return /^(\d{1,3}\.){3}\d{1,3}$/.test(host)
 }
 
-/**
- * Decode a percent-encoded segment without throwing on malformed input.
- * Browsers happily send `q=%E0%A4%A` (truncated UTF-8 sequences) — refusing
- * the whole request would let any client knock the route handler offline.
- */
-function safeDecode(value: string): string {
-  try {
-    return decodeURIComponent(value)
-  } catch {
-    return value
-  }
-}
-
-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

@@ -81,6 +81,10 @@ 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 {
@@ -252,7 +256,12 @@ export { ConsoleKernel, defineConfig, Ignitor, prettyPrintError } from './Ignito
 export { errors } from './errors/aggregate.js'
 export type { AppContext, ProviderContract } from './Provider.js'
 export { Provider } from './Provider.js'
-export type { ContainerBinding, ContainerBindings } from './types/container.js'
+export type {
+  AuthenticatorName,
+  Authenticators,
+  ContainerBinding,
+  ContainerBindings,
+} from './types/index.js'
 
 // ─── Codemods ───────────────────────────────────────────────
 
@@ -362,4 +371,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.2'
+export const VERSION = '0.2.4'

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
   }
 }
 

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' },
+    )
+  }
+}