@c9up/ream 0.2.6 → 0.2.8

package/src/dumper/Dumper.ts

@@ -0,0 +1,164 @@
+/**
+ * Value dumping — AdonisJS's `Dumper`, in shape and in method names.
+ *
+ *   import { dd } from '@c9up/ream/services/dumper'
+ *   dd(user)                     // prints and stops the process
+ *
+ *   import dumper from '@c9up/ream/services/dumper'
+ *   response.send(dumper.dumpToHtml(user, { cspNonce: response.nonce }))
+ *
+ * The rendering is `node:util`'s `inspect`, not a dependency. It already knows
+ * about depth limits, circular references, getters, Maps, Sets and typed
+ * arrays, and it colours for a terminal — which is the whole of the ANSI side.
+ * The HTML side escapes that same output rather than building a second
+ * formatter, so the two can never describe a value differently.
+ */
+
+import { inspect } from 'node:util'
+import { escapeHTML } from '../helpers/string.js'
+
+/** Where a dump was written, so the output can say so. */
+export interface DumpSource {
+  location: string
+  line: number
+}
+
+/** Knobs for the terminal rendering — AdonisJS `ConsoleDumpConfig`. */
+export interface ConsoleDumpConfig {
+  /** How deep to walk before printing `[Object]`. Default 4. */
+  depth?: number
+  /** Colour the output. Default: whether stdout is a TTY. */
+  colors?: boolean
+  /** Show non-enumerable properties. Default false. */
+  showHidden?: boolean
+}
+
+/** Knobs for the HTML rendering — AdonisJS `HTMLDumpConfig`. */
+export interface HTMLDumpConfig {
+  /** How deep to walk. Default 4. */
+  depth?: number
+  /** Show non-enumerable properties. Default false. */
+  showHidden?: boolean
+  /** Style overrides for the emitted `<pre>`, as CSS declarations. */
+  styles?: Record<string, string>
+}
+
+const DEFAULT_STYLES: Record<string, string> = {
+  'background-color': '#0b0b0d',
+  color: '#e6e6e6',
+  padding: '1rem',
+  'border-radius': '6px',
+  'font-family': 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  'font-size': '13px',
+  'line-height': '1.5',
+  'overflow-x': 'auto',
+}
+
+export class Dumper {
+  #html: HTMLDumpConfig = {}
+  #ansi: ConsoleDumpConfig = {}
+
+  /** Configure the HTML rendering. Chainable, as in AdonisJS. */
+  configureHtmlOutput(config: HTMLDumpConfig): this {
+    this.#html = { ...this.#html, ...config }
+    return this
+  }
+
+  /** Configure the terminal rendering. Chainable, as in AdonisJS. */
+  configureAnsiOutput(config: ConsoleDumpConfig): this {
+    this.#ansi = { ...this.#ansi, ...config }
+    return this
+  }
+
+  /**
+   * The `<style>` a page needs before its first HTML dump.
+   *
+   * Takes a CSP nonce because a page that sets a nonce-based policy rejects an
+   * unattributed inline `<style>` — and a dump landing in a page that silently
+   * drops its styling is worse than no dump. `response.nonce` is what to pass.
+   */
+  getHeadElements(cspNonce?: string): string {
+    const nonce = cspNonce ? ` nonce="${escapeHTML(cspNonce)}"` : ''
+    const styles = { ...DEFAULT_STYLES, ...this.#html.styles }
+    const declarations = Object.entries(styles)
+      .map(([property, value]) => `  ${property}: ${value};`)
+      .join('\n')
+    return `<style${nonce}>\n.ream-dump {\n${declarations}\n}\n</style>`
+  }
+
+  /** Render `value` for a terminal. */
+  dumpToAnsi(value: unknown, options?: { title?: string; source?: DumpSource }): string {
+    const body = inspect(value, {
+      depth: this.#ansi.depth ?? 4,
+      colors: this.#ansi.colors ?? process.stdout.isTTY === true,
+      showHidden: this.#ansi.showHidden ?? false,
+      // Long strings and arrays are the reason someone is dumping; truncating
+      // them defeats the call.
+      maxStringLength: null,
+      maxArrayLength: null,
+    })
+    return [header(options), body].filter(Boolean).join('\n')
+  }
+
+  /**
+   * Render `value` as HTML.
+   *
+   * The inspected output is escaped before it reaches the page: a dumped value
+   * is by definition data someone else may control, and a dump is something
+   * you reach for while debugging — exactly when a script tag in a field name
+   * would be least expected.
+   */
+  dumpToHtml(
+    value: unknown,
+    options?: { cspNonce?: string; title?: string; source?: DumpSource },
+  ): string {
+    const body = inspect(value, {
+      depth: this.#html.depth ?? 4,
+      colors: false,
+      showHidden: this.#html.showHidden ?? false,
+      maxStringLength: null,
+      maxArrayLength: null,
+    })
+    const heading = header(options)
+    const label = heading ? `<div class="ream-dump-header">${escapeHTML(heading)}</div>` : ''
+    return `${this.getHeadElements(options?.cspNonce)}\n${label}<pre class="ream-dump">${escapeHTML(body)}</pre>`
+  }
+
+  /**
+   * Dump and die — print to stderr and stop the process.
+   *
+   * `traceSourceIndex` selects which stack frame to report as the dump site:
+   * 1 is the caller of `dd`, which is right when `dd` is called directly, and
+   * a wrapper passes 2.
+   */
+  dd(value: unknown, traceSourceIndex = 1): void {
+    process.stderr.write(`${this.dumpToAnsi(value, { source: callSite(traceSourceIndex) })}\n`)
+    process.exit(1)
+  }
+}
+
+/** `title` and `source` as one line, or nothing when neither is given. */
+function header(options?: { title?: string; source?: DumpSource }): string {
+  const parts: string[] = []
+  if (options?.title) parts.push(options.title)
+  if (options?.source) parts.push(`${options.source.location}:${options.source.line}`)
+  return parts.join(' — ')
+}
+
+/**
+ * Where `dd` was called, read from a thrown stack.
+ *
+ * Best-effort: a bundled or minified frame may not parse, and a dump that
+ * cannot name its own line is still a useful dump — so a miss returns nothing
+ * rather than throwing on the debugging path.
+ */
+function callSite(index: number): DumpSource | undefined {
+  const frames = new Error().stack?.split('\n').slice(1)
+  const frame = frames?.[index]
+  if (!frame) return undefined
+  const match = /\(?(.+):(\d+):\d+\)?$/.exec(frame.trim())
+  const location = match?.[1]
+  const line = match?.[2]
+  if (!location || !line) return undefined
+  return { location, line: Number(line) }
+}

package/src/helpers/is.ts

@@ -62,12 +62,7 @@ export function isArray<T = unknown>(v: unknown): v is T[] {
  * @example isPromise(Promise.resolve()) // true
  */
 export function isPromise<T = unknown>(v: unknown): v is Promise<T> {
-  return (
-    v !== null &&
-    typeof v === 'object' &&
-    'then' in v &&
-    typeof (v as Record<string, unknown>).then === 'function'
-  )
+  return v !== null && typeof v === 'object' && 'then' in v && typeof v.then === 'function'
 }
 
 /**

package/src/index.ts

@@ -371,4 +371,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.6'
+export const VERSION = '0.2.8'

package/src/middleware/Pipeline.ts

@@ -11,6 +11,7 @@
  * 5. Handler
  */
 
+import { debugHttp } from '../debug.js'
 import { ReamError } from '../errors/ReamError.js'
 import { E_FORBIDDEN, E_UNAUTHORIZED, E_VALIDATION_ERROR } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
@@ -196,6 +197,12 @@ function composeMiddleware(middleware: MiddlewareFunction[]): MiddlewareFunction
       const fn = i < middleware.length ? middleware[i] : finalNext
       if (!fn) return
 
+      if (debugHttp.enabled && i < middleware.length) {
+        // `fn.name` is what a named middleware function or a bound class
+        // method carries; an inline arrow has none, and its position is the
+        // only thing that identifies it.
+        debugHttp('middleware %d/%d %s', i + 1, middleware.length, fn.name || '(anonymous)')
+      }
       await fn(ctx, () => dispatch(i + 1))
     }
 

package/src/repl/Repl.ts

@@ -0,0 +1,162 @@
+/**
+ * The application REPL — AdonisJS's `Repl`, in shape and in method names.
+ *
+ *   import repl from '@c9up/ream/services/repl'
+ *   repl.addMethod('loadModels', async () => { … }, {
+ *     description: 'Load every entity onto the prompt',
+ *   })
+ *   repl.start({ app, router })
+ *
+ * Built on `node:repl`, which is the REPL — this adds what makes it an
+ * APPLICATION repl: a context seeded with the booted services, helpers a
+ * project registers itself, and `.ls` to list them, because a prompt full of
+ * undiscoverable helpers is a prompt nobody uses.
+ */
+
+import type { REPLServer } from 'node:repl'
+import { start as startNodeRepl } from 'node:repl'
+
+/** What a registered helper receives — the repl itself, then its arguments. */
+export type MethodCallback = (repl: Repl, ...args: unknown[]) => unknown
+
+/** How a helper describes itself in `.ls`. */
+export interface MethodOptions {
+  description?: string
+  usage?: string
+}
+
+/**
+ * A TypeScript compiler for the prompt, when the host has one.
+ *
+ * `node:repl` evaluates JavaScript. A project whose code is TypeScript wants
+ * to paste TypeScript, so the host supplies the compiler it already runs
+ * rather than ream carrying one.
+ */
+export interface Compiler {
+  compile(code: string, fileName: string): string
+  supportsTypescript: boolean
+}
+
+interface RegisteredMethod {
+  handler: MethodCallback
+  options: MethodOptions & { width: number }
+}
+
+export class Repl {
+  readonly #methods = new Map<string, RegisteredMethod>()
+  readonly #readyCallbacks: Array<(repl: Repl) => void> = []
+  #compiler: Compiler | undefined
+  #server: REPLServer | undefined
+  readonly #prompt: string
+  readonly #write: (message: string) => void
+
+  constructor(options: { prompt?: string; write?: (message: string) => void } = {}) {
+    this.#prompt = options.prompt ?? '> '
+    this.#write =
+      options.write ??
+      ((message) => {
+        process.stdout.write(message)
+      })
+  }
+
+  /**
+   * Print a message around the prompt.
+   *
+   * Newline-wrapped: written mid-session the text would otherwise land on the
+   * line the user is typing.
+   */
+  notify(message: string): void {
+    this.#write(`\n${message}\n`)
+  }
+
+  /** Run `callback` once the prompt is up. Chainable. */
+  ready(callback: (repl: Repl) => void): this {
+    this.#readyCallbacks.push(callback)
+    return this
+  }
+
+  /**
+   * Register a helper, available at the prompt by name. Chainable.
+   *
+   * `width` is the name's display width, recorded here so `.ls` can align a
+   * column without measuring the set twice.
+   */
+  addMethod(name: string, handler: MethodCallback, options: MethodOptions = {}): this {
+    this.#methods.set(name, { handler, options: { ...options, width: name.length } })
+    return this
+  }
+
+  /** Every registered helper, keyed by name — AdonisJS `getMethods`. */
+  getMethods(): Record<string, RegisteredMethod> {
+    return Object.fromEntries(this.#methods)
+  }
+
+  /** Use `compiler` for the code typed at the prompt. Chainable. */
+  useCompiler(compiler: Compiler): this {
+    this.#compiler = compiler
+    return this
+  }
+
+  /** The compiler in use, if any. */
+  get compiler(): Compiler | undefined {
+    return this.#compiler
+  }
+
+  /** The underlying `node:repl` server, once started. */
+  get server(): REPLServer | undefined {
+    return this.#server
+  }
+
+  /**
+   * List the registered helpers, one per line, names aligned.
+   *
+   * Exposed rather than private because it IS the `.ls` command, and a caller
+   * driving the repl programmatically (a test, a custom command) needs the
+   * same listing without a live prompt.
+   */
+  describeMethods(): string {
+    if (this.#methods.size === 0) return 'No methods registered'
+    const widest = Math.max(...[...this.#methods.values()].map((m) => m.options.width))
+    return [...this.#methods]
+      .map(([name, method]) => {
+        const description = method.options.description ?? ''
+        const usage = method.options.usage ? ` (${method.options.usage})` : ''
+        return `${name.padEnd(widest)}  ${description}${usage}`.trimEnd()
+      })
+      .join('\n')
+  }
+
+  /**
+   * Start the prompt, seeding it with `context`.
+   *
+   * Registered helpers are bound to this repl before the prompt appears — a
+   * helper that only exists after the first keystroke is a helper the user
+   * finds missing.
+   */
+  start(context: Record<string, unknown> = {}): this {
+    const server = startNodeRepl({ prompt: this.#prompt, useGlobal: false })
+    this.#server = server
+
+    for (const [key, value] of Object.entries(context)) {
+      Object.defineProperty(server.context, key, { value, configurable: true, enumerable: true })
+    }
+    for (const [name, method] of this.#methods) {
+      Object.defineProperty(server.context, name, {
+        value: (...args: unknown[]) => method.handler(this, ...args),
+        configurable: true,
+        enumerable: true,
+      })
+    }
+
+    server.defineCommand('ls', {
+      help: 'List the helpers available at this prompt',
+      action: () => {
+        this.notify(this.describeMethods())
+        server.displayPrompt()
+      },
+    })
+
+    for (const callback of this.#readyCallbacks) callback(this)
+    return this
+  }
+}

package/src/scheduler/Scheduler.ts

@@ -252,9 +252,12 @@ export class Scheduler {
       // `.then`-based detection + `Promise.resolve` wrap so non-native
       // thenables (e.g. RxJS-style) are handled uniformly.
       if (
+        // Object OR function: a thenable function is exotic but legal, and the
+        // guard this replaced accepted one. `in` narrows either.
+        (typeof result === 'object' || typeof result === 'function') &&
         result !== null &&
-        result !== undefined &&
-        typeof (result as { then?: unknown }).then === 'function'
+        'then' in result &&
+        typeof result.then === 'function'
       ) {
         Promise.resolve(result).catch(() => {})
       }
@@ -334,9 +337,12 @@ export class Scheduler {
       // reporter never crashes the ticker.
       const result = this.#errorReporter(err, { taskName }) as unknown
       if (
+        // Object OR function: a thenable function is exotic but legal, and the
+        // guard this replaced accepted one. `in` narrows either.
+        (typeof result === 'object' || typeof result === 'function') &&
         result !== null &&
-        result !== undefined &&
-        typeof (result as { then?: unknown }).then === 'function'
+        'then' in result &&
+        typeof result.then === 'function'
       ) {
         Promise.resolve(result).catch(() => {})
       }

package/src/services/dumper.ts

@@ -0,0 +1,30 @@
+/**
+ * Dumper singleton service.
+ *
+ *   import { dd } from '@c9up/ream/services/dumper'
+ *   dd(user)
+ *
+ *   import dumper from '@c9up/ream/services/dumper'
+ *   dumper.configureAnsiOutput({ depth: 8 })
+ *
+ * Unlike the other accessors this one holds a real instance rather than a
+ * proxy: the dumper depends on nothing the boot phase builds, and something
+ * you reach for mid-debug should not require a booted application.
+ */
+
+import { Dumper } from '../dumper/Dumper.js'
+
+const dumper = new Dumper()
+
+/**
+ * Dump and die — AdonisJS's `dd`.
+ *
+ * The trace index is 2, not the default 1: the frame above is this function,
+ * so the caller of `dd` is one further out. Without it, every dump would
+ * report this file as its source.
+ */
+export const dd = (value: unknown): void => {
+  dumper.dd(value, 2)
+}
+
+export default dumper

package/src/services/logger.ts

@@ -0,0 +1,49 @@
+/**
+ * Application logger singleton service.
+ *
+ * Usage:
+ *   import logger from '@c9up/ream/services/logger'
+ *   logger.info('user signed in', { userId })
+ *
+ * ream does not implement the logger — it declares the contract
+ * ({@link ContextLogger}) and reads whatever a provider bound as `'logger'`.
+ * `@c9up/spectrum` is the implementation in this universe, the way `hash` is
+ * sigil's and validation is rune's.
+ *
+ * `ctx.logger` stays the right thing to use inside a request: it is
+ * correlation-scoped. This is for everywhere else — a provider, a scheduled
+ * task, a console command — where there is no request to scope to.
+ */
+
+import type { ChildLoggerSource } from '../http/HttpContext.js'
+import { createServiceProxy } from './createServiceProxy.js'
+
+let instance: ChildLoggerSource | undefined
+
+/** @internal Set the logger (called by Ignitor once providers have booted). */
+export function setLogger(logger: ChildLoggerSource): void {
+  instance = logger
+}
+
+/**
+ * @internal Unset the locator IF it still points at `logger` (called by
+ * Ignitor.stop()). Ownership-guarded — see services/app.ts.
+ */
+export function clearLogger(logger: ChildLoggerSource): void {
+  if (instance === logger) instance = undefined
+}
+
+/** @internal Get the logger directly. */
+export function getLogger(): ChildLoggerSource | undefined {
+  return instance
+}
+
+const logger: ChildLoggerSource = createServiceProxy<ChildLoggerSource>(
+  () => instance,
+  'Logger accessed before initialization. ' +
+    'ream declares the contract but implements no logger — install one (`@c9up/spectrum`) ' +
+    "and register its provider, which binds it as 'logger'. Inside a request, prefer " +
+    '`ctx.logger`, which is scoped to the correlation id.',
+)
+
+export default logger

package/src/services/repl.ts

@@ -0,0 +1,21 @@
+/**
+ * REPL singleton service.
+ *
+ *   // start/repl.ts, imported as a preload for the `repl` environment
+ *   import repl from '@c9up/ream/services/repl'
+ *   import { UserEntity } from '#app/entities/user'
+ *
+ *   repl.addMethod('users', () => UserEntity, {
+ *     description: 'The user entity, for querying at the prompt',
+ *   })
+ *
+ * Holds a real instance rather than a proxy: helpers are registered BEFORE the
+ * prompt starts — that is the point of registering them — so the object has to
+ * exist before anything boots it.
+ */
+
+import { Repl } from '../repl/Repl.js'
+
+const repl = new Repl()
+
+export default repl

package/src/session/Session.ts

@@ -56,9 +56,9 @@ export interface SessionDriverWithTagging extends SessionDriver {
 export function supportsTagging(driver: SessionDriver): driver is SessionDriverWithTagging {
   return (
     'tag' in driver &&
-    typeof (driver as SessionDriverWithTagging).tag === 'function' &&
+    typeof driver.tag === 'function' &&
     'tagged' in driver &&
-    typeof (driver as SessionDriverWithTagging).tagged === 'function'
+    typeof driver.tagged === 'function'
   )
 }
 

package/src/testing/TestClient.ts

@@ -68,17 +68,51 @@ export class TestClient {
 
   #server: { port: number; close: () => Promise<void> | void } | null = null
 
-  /** Boot the application on a random port. */
+  /**
+   * In flight or settled, so concurrent callers share one boot.
+   *
+   * Also what makes `boot()` optional: the first request awaits this, starting
+   * it if nobody has. A test file that never issues a request never starts a
+   * server — which is the difference between a unit file paying for one and
+   * not, and at ~400ms a file that is most of a campaign's time.
+   */
+  #booting: Promise<void> | null = null
+
+  /**
+   * Boot the application on a random port. Idempotent: a second call awaits the
+   * first rather than starting a second server.
+   *
+   * Optional — a request boots on its own. Call it when you need `port` before
+   * issuing one (an SSE or WebSocket connection opened with `fetch`).
+   */
   async boot(): Promise<void> {
+    this.#booting ??= this.#startServer()
+    return this.#booting
+  }
+
+  async #startServer(): Promise<void> {
     this.#server = await this.#bootFn(0)
     this.#port = this.#server.port
   }
 
-  /** Close the server. */
+  /** Whether a server is currently running for this client. */
+  get booted(): boolean {
+    return this.#server !== null
+  }
+
+  /**
+   * Close the server. A no-op when nothing was ever started, so a teardown can
+   * call it unconditionally against a client whose file issued no request.
+   */
   async close(): Promise<void> {
+    // Awaited first: closing while a boot is in flight would otherwise leave
+    // the server that boot is about to assign running with nobody holding it.
+    if (this.#booting) await this.#booting.catch(() => {})
+    this.#booting = null
     if (this.#server) {
       await this.#server.close()
       this.#server = null
+      this.#port = 0
     }
   }
 
@@ -86,7 +120,11 @@ export class TestClient {
    * Ephemeral port the booted server bound to. Useful for long-lived
    * connections (SSE / WebSocket) that the fluent buffered request
    * surface can't model — open them with `fetch` against
-   * `http://127.0.0.1:${client.port}/...`. Returns 0 before `boot()`.
+   * `http://127.0.0.1:${client.port}/...`.
+   *
+   * Returns 0 while no server is running. Requests boot on their own, so a
+   * client that has only been constructed has not bound a port yet — `await
+   * client.boot()` first when you need this before issuing one.
    */
   get port(): number {
     return this.#port
@@ -148,8 +186,11 @@ export class TestClient {
    * `form()`. The lower-level `request()` (below) stays for raw control.
    */
   fluent(method: HttpMethod, path: string): RequestBuilder {
-    const sender: HttpSender = (m, p, init) =>
-      sendRequest(
+    const sender: HttpSender = async (m, p, init) => {
+      // Boots on the first request and no earlier. `#port` is read here rather
+      // than captured, so it is the port this boot bound to.
+      await this.boot()
+      return sendRequest(
         this.#port,
         m,
         p,
@@ -157,6 +198,7 @@ export class TestClient {
         init.body.toString('utf8'),
         init.timeoutMs,
       )
+    }
     return new RequestBuilder(sender, method, path, this.#auth, this.#sessionSeeder)
   }