@c9up/ream 0.2.7 → 0.2.8

package/dist/repl/Repl.js

@@ -0,0 +1,123 @@
+/**
+ * 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 { start as startNodeRepl } from 'node:repl';
+export class Repl {
+    #methods = new Map();
+    #readyCallbacks = [];
+    #compiler;
+    #server;
+    #prompt;
+    #write;
+    constructor(options = {}) {
+        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) {
+        this.#write(`\n${message}\n`);
+    }
+    /** Run `callback` once the prompt is up. Chainable. */
+    ready(callback) {
+        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, handler, options = {}) {
+        this.#methods.set(name, { handler, options: { ...options, width: name.length } });
+        return this;
+    }
+    /** Every registered helper, keyed by name — AdonisJS `getMethods`. */
+    getMethods() {
+        return Object.fromEntries(this.#methods);
+    }
+    /** Use `compiler` for the code typed at the prompt. Chainable. */
+    useCompiler(compiler) {
+        this.#compiler = compiler;
+        return this;
+    }
+    /** The compiler in use, if any. */
+    get compiler() {
+        return this.#compiler;
+    }
+    /** The underlying `node:repl` server, once started. */
+    get server() {
+        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() {
+        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 = {}) {
+        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) => 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;
+    }
+}
+//# sourceMappingURL=Repl.js.map

package/dist/repl/Repl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Repl.js","sourceRoot":"","sources":["../../src/repl/Repl.ts"],"names":[],"mappings":"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"}

package/dist/services/dumper.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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';
+declare const dumper: 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 declare const dd: (value: unknown) => void;
+export default dumper;
+//# sourceMappingURL=dumper.d.ts.map

package/dist/services/dumper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dumper.d.ts","sourceRoot":"","sources":["../../src/services/dumper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAE5C,QAAA,MAAM,MAAM,QAAe,CAAA;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,GAAI,OAAO,OAAO,KAAG,IAEnC,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/services/dumper.js

@@ -0,0 +1,27 @@
+/**
+ * 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) => {
+    dumper.dd(value, 2);
+};
+export default dumper;
+//# sourceMappingURL=dumper.js.map

package/dist/services/dumper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dumper.js","sourceRoot":"","sources":["../../src/services/dumper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAE5C,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAA;AAE3B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAc,EAAQ,EAAE;IACzC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;AACrB,CAAC,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/services/repl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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';
+declare const repl: Repl;
+export default repl;
+//# sourceMappingURL=repl.d.ts.map

package/dist/services/repl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../../src/services/repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC,QAAA,MAAM,IAAI,MAAa,CAAA;AAEvB,eAAe,IAAI,CAAA"}

package/dist/services/repl.js

@@ -0,0 +1,19 @@
+/**
+ * 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;
+//# sourceMappingURL=repl.js.map

package/dist/services/repl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl.js","sourceRoot":"","sources":["../../src/services/repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAA;AAEvB,eAAe,IAAI,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -39,6 +39,22 @@
       "types": "./dist/services/config.d.ts",
       "import": "./dist/services/config.js"
     },
+    "./services/dumper": {
+      "types": "./dist/services/dumper.d.ts",
+      "import": "./dist/services/dumper.js"
+    },
+    "./dumper": {
+      "types": "./dist/dumper/Dumper.d.ts",
+      "import": "./dist/dumper/Dumper.js"
+    },
+    "./services/repl": {
+      "types": "./dist/services/repl.d.ts",
+      "import": "./dist/services/repl.js"
+    },
+    "./repl": {
+      "types": "./dist/repl/Repl.d.ts",
+      "import": "./dist/repl/Repl.js"
+    },
     "./services/encryption": {
       "types": "./dist/services/encryption.d.ts",
       "import": "./dist/services/encryption.js"

package/src/HttpKernel.ts

@@ -11,6 +11,7 @@
  */
 
 import type { Container } from './container/Container.js'
+import { debugHttp } from './debug.js'
 import type { Emitter } from './events/Emitter.js'
 import { E_ROUTE_NOT_FOUND, ExceptionHandler } from './http/Exception.js'
 import { type ChildLoggerSource, HttpContext } from './http/HttpContext.js'
@@ -157,6 +158,14 @@ export function createHttpKernel(
     // only correct key; the previous PascalCase fallback was dead code.
     const host = reqData.headers.host
     const match = config.router.match(reqData.method, reqData.path, host)
+    if (debugHttp.enabled) {
+      debugHttp(
+        '%s %s -> %s',
+        reqData.method,
+        reqData.path,
+        match ? (match.route.name ?? match.route.path) : 'no match',
+      )
+    }
     const routeInfo = match
       ? {
           pattern: match.route.path,
@@ -327,6 +336,15 @@ export function createHttpKernel(
         path: reqData.path,
         status: ctx.response.getStatus(),
       })
+      if (debugHttp.enabled) {
+        debugHttp(
+          '%s %s <- %d (%s)',
+          reqData.method,
+          reqData.path,
+          ctx.response.getStatus(),
+          correlationId,
+        )
+      }
       const serialized = await serializeResponse(ctx)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
@@ -374,6 +392,15 @@ export function createHttpKernel(
         path: reqData.path,
         status: ctx.response.getStatus(),
       })
+      if (debugHttp.enabled) {
+        debugHttp(
+          '%s %s <- %d (%s)',
+          reqData.method,
+          reqData.path,
+          ctx.response.getStatus(),
+          correlationId,
+        )
+      }
       const serialized = await serializeResponse(ctx)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.

package/src/debug.ts

@@ -0,0 +1,25 @@
+/**
+ * Debug channels, off unless `NODE_DEBUG` names them — the shape AdonisJS
+ * uses (`NODE_DEBUG=adonisjs:http`).
+ *
+ *   NODE_DEBUG=ream:http ream serve
+ *   NODE_DEBUG=ream:* ream serve
+ *
+ * These are for the framework's own tracing: which route a request matched,
+ * which middleware ran, what status came back. They are NOT request logging —
+ * a production request log belongs to the app's logger (`ctx.logger`), which
+ * is correlation-scoped and structured. Neither framework prints one by
+ * default, and this is the switch for when you need to see the plumbing.
+ *
+ * `debuglog` returns a no-op when the channel is off, so an inactive probe
+ * costs a call. Guard with `.enabled` anywhere the ARGUMENTS would cost
+ * something to build — the per-request probes below all do.
+ */
+
+import { debuglog } from 'node:util'
+
+/** Routing, middleware and response tracing. AdonisJS `adonisjs:http`. */
+export const debugHttp = debuglog('ream:http')
+
+/** Boot: providers, preloads, container bindings. AdonisJS `adonisjs:core`. */
+export const debugCore = debuglog('ream:core')

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/index.ts

@@ -371,4 +371,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.7'
+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))
     }