@c9up/ream 0.2.22 → 0.2.24

package/dist/hot.js.map

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

package/dist/index.d.ts

@@ -121,5 +121,5 @@ export { BaseEvent, Emitter, type EmitterResolver, type ListenerClass, } from '.
 export { type BufferedEvent, type BufferedEventName, type EventFinder, EventsBuffer, } from './events/EventsBuffer.js';
 export type { ErrorReporter, LockBackend, LockBackendFactory, LockRedisClient, LockRedisResolver, RunTaskOutcome, ScheduleEvent, ScheduleEventSink, ScheduleInvocation, ScheduleMetadata, ScheduleProviderOptions, SchedulerConfig, SchedulerOptions, ScheduleTaskCompletedEvent, ScheduleTaskFailedEvent, ScheduleTaskSkippedEvent, ScheduleTaskStartedEvent, TaskInfo, TaskStats, } from './scheduler/index.js';
 export { defineSchedulerConfig, getScheduleMetadata, locks, MemoryLockBackend, RedisLockBackend, SCHEDULE_METADATA_KEY, Schedule, ScheduleProvider, Scheduler, StatsTracker, } from './scheduler/index.js';
-export declare const VERSION = "0.2.22";
+export declare const VERSION = "0.2.24";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -92,5 +92,5 @@ export { defineConfig as defineEventsConfig } from './events/config.js';
 export { BaseEvent, Emitter, } from './events/Emitter.js';
 export { EventsBuffer, } from './events/EventsBuffer.js';
 export { defineSchedulerConfig, getScheduleMetadata, locks, MemoryLockBackend, RedisLockBackend, SCHEDULE_METADATA_KEY, Schedule, ScheduleProvider, Scheduler, StatsTracker, } from './scheduler/index.js';
-export const VERSION = '0.2.22';
+export const VERSION = '0.2.24';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -233,8 +233,7 @@
   },
   "peerDependencies": {
     "@c9up/comet": "^0.1.0",
-    "@c9up/quasar": "^0.1.0 || ^0.2.0",
-    "hot-hook": "^1.0.0"
+    "@c9up/quasar": "^0.1.0 || ^0.2.0"
   },
   "peerDependenciesMeta": {
     "@c9up/comet": {
@@ -242,9 +241,6 @@
     },
     "@c9up/quasar": {
       "optional": true
-    },
-    "hot-hook": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -257,8 +253,9 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.11"
   },
+  "//engines": "Node 24, not 22, because AsyncLocalStorage sits on the request hot path — the container resolves through it, HttpContext is it, and the emitter reads it on every event. Node 24 backs it with AsyncContextFrame by default, and measured on that exact pattern (one context per request, six async boundaries, several reads) it costs 0.61 us per request instead of 1.55 us: 2.5x, on every request, for free. Before 24 the same mechanism existed only behind an experimental flag, and a framework cannot base its performance on a flag the application has to remember to pass. This is NOT 'track the current LTS' — security fixes still land in 22 until 2027, npm 11 is irrelevant under pnpm, and node:sqlite is not what atlas uses.",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/HttpKernel.ts

@@ -12,6 +12,7 @@
 
 import type { Container } from './container/Container.js'
 import { debugHttp } from './debug.js'
+import { hotReloadCount } from './dev/hmr.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'
@@ -117,7 +118,16 @@ export function createHttpKernel(
   // router.clear() drops the route objects, their chains become unreachable
   // and are GC'd — no need to monkey-patch router.clear (which leaked a
   // wrapper chain when createHttpKernel ran more than once on one router).
-  const pipelineCache = new WeakMap<RouteDefinition, { chain: MiddlewareFunction }>()
+  // `hotAt` is what makes hot reloading reach the router at all. A lazy
+  // controller is promoted to a concrete one on first request and the whole
+  // pipeline is cached per route — so once hot-hook swapped a module, both
+  // still pointed at the class from before, the process kept serving it, and
+  // the swap looked like it had not happened. Remembering when an entry was
+  // built lets a later swap throw it away.
+  //
+  // In production this is a number compared against a constant zero: nothing
+  // bumps the counter when `@c9up/ream/hot` was never loaded.
+  const pipelineCache = new WeakMap<RouteDefinition, { chain: MiddlewareFunction; hotAt: number }>()
 
   // Resolve the events emitter once, only when the app registered
   // `EventsProvider`. Lazy + cached: the binding may not exist yet at kernel
@@ -245,7 +255,17 @@ export function createHttpKernel(
           throw new E_ROUTE_NOT_FOUND(reqData.method, reqData.path)
         }
 
+        const hotAt = hotReloadCount()
         let cached = pipelineCache.get(match.route)
+        if (cached !== undefined && cached.hotAt !== hotAt) {
+          // A module was swapped since this was built. Drop the pipeline AND
+          // the promoted controller, so the loader runs again and `import()`
+          // hands back what hot-hook just invalidated rather than the copy in
+          // the ESM cache.
+          pipelineCache.delete(match.route)
+          if (match.route.lazyController) match.route.controller = undefined
+          cached = undefined
+        }
 
         if (!cached) {
           // Promote a lazy/string controller to a concrete controller tuple on
@@ -314,7 +334,7 @@ export function createHttpKernel(
             { guards, roles, permissions, validators },
           )
 
-          cached = { chain }
+          cached = { chain, hotAt }
           pipelineCache.set(match.route, cached)
         }
 

package/src/Ignitor.ts

@@ -63,6 +63,18 @@ import type { AppEnvironment } from './Application.js'
 /**
  * Reamrc config — like AdonisJS adonisrc.ts with defineConfig().
  */
+/** A command the CLI runs on the application's behalf. */
+export interface AssetsCommand {
+  command: string
+  args?: string[]
+}
+
+/** What `assets` declares: a watcher for `dev`, a one-shot for `build`. */
+export interface AssetsConfig {
+  devServer?: AssetsCommand
+  build?: AssetsCommand
+}
+
 export interface ReamrcConfig {
   providers?: Array<
     | (() => Promise<{ default: new (app: AppContext) => ProviderContract }>)
@@ -113,6 +125,18 @@ export interface ReamrcConfig {
   }
   /** Test suites and runner settings — the `tests` block of adonisrc.ts. */
   tests?: TestsConfig
+  /**
+   * The asset pipeline `ream dev` and `ream build` drive alongside the app.
+   *
+   * `devServer` is started beside the development server and killed with it;
+   * `build` runs once, before the TypeScript build, and a non-zero exit stops
+   * the build rather than shipping a bundle nobody rebuilt.
+   *
+   * Declared here because the CLI already reads it: without the type an app
+   * that configures its asset build gets an excess-property error from
+   * `defineConfig`, which is a strange way to learn that the option exists.
+   */
+  assets?: AssetsConfig
 }
 
 /** One test suite, as declared in the rc file (AdonisJS `tests.suites[]`). */

package/src/dev/fullReload.ts

@@ -0,0 +1,34 @@
+/**
+ * Saying why the process is about to restart.
+ *
+ * A change the loader cannot swap in place becomes an exit code the dev server
+ * restarts on. From the terminal the only trace of it was the boot banner
+ * printing itself a second time — which reads as a server rebooting on its own
+ * rather than as a file that fell outside `hotHook.boundaries`. Upstream's dev
+ * server logs the file it reloaded for; this is that line.
+ *
+ * Kept apart from the loader entry so it can be tested: importing that entry
+ * registers module hooks, which a test cannot undo.
+ */
+
+/** Why a change could not be swapped in place. */
+export type ReloadReason = 'outside-boundaries' | 'restart-list'
+
+/**
+ * The line to print before restarting.
+ *
+ * @param file - absolute path of the file that changed.
+ * @param relativise - turns it into the path the editor shows, so the line can
+ *   be read at a glance.
+ */
+export function fullReloadNotice(
+  file: string,
+  reason: ReloadReason,
+  relativise: (file: string) => string,
+): string {
+  const why =
+    reason === 'restart-list'
+      ? ' (it is on `hotHook.restart`, which always restarts)'
+      : ' (nothing importing it is inside a `hotHook.boundaries` entry, so it could not be swapped)'
+  return `[ream] full reload — ${relativise(file)}${why}`
+}

package/src/dev/hotGlob.ts

@@ -0,0 +1,66 @@
+/**
+ * Matching the globs an application declares under `hotHook.boundaries`.
+ *
+ * A dependency for this would be `picomatch` plus `fast-glob`, which is two
+ * packages and their trees for the three wildcards these patterns actually use.
+ * The patterns are written by hand in a `package.json` and read once at boot;
+ * what they need is to be right, not fast.
+ *
+ * The dialect is the one those files already use:
+ *   *   any run of characters inside one path segment
+ *   **  any number of segments, including none
+ *   ?   exactly one character inside a segment
+ *
+ * A leading `./` is optional, and matching is done on POSIX-shaped paths
+ * relative to the project root, so a Windows checkout and a Linux one read the
+ * same pattern the same way.
+ */
+
+/** Turn one glob into an anchored regular expression. */
+export function globToRegExp(pattern: string): RegExp {
+  const cleaned = pattern.replace(/^\.\//, '')
+  let out = ''
+  for (let i = 0; i < cleaned.length; i += 1) {
+    const char = cleaned[i]
+    if (char === '*') {
+      if (cleaned[i + 1] === '*') {
+        // `**/` swallows the separator so that `a/**/b` also matches `a/b`;
+        // a trailing `**` simply matches the rest.
+        i += 1
+        if (cleaned[i + 1] === '/') {
+          i += 1
+          out += '(?:[^/]+/)*'
+        } else {
+          out += '.*'
+        }
+        continue
+      }
+      out += '[^/]*'
+      continue
+    }
+    if (char === '?') {
+      out += '[^/]'
+      continue
+    }
+    // Everything else is literal, including the characters a regular
+    // expression would otherwise read as syntax.
+    out += (char ?? '').replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${out}$`)
+}
+
+/**
+ * A matcher over several globs.
+ *
+ * Returns a predicate rather than a class: the graph takes a function, and a
+ * project with no boundaries gets one that is honestly always false instead of
+ * an empty object that has to be checked for.
+ */
+export function globMatcher(patterns: readonly string[]): (path: string) => boolean {
+  const expressions = patterns.map(globToRegExp)
+  if (expressions.length === 0) return () => false
+  return (path: string) => {
+    const normalised = path.replace(/\\/g, '/').replace(/^\.\//, '')
+    return expressions.some((expression) => expression.test(normalised))
+  }
+}

package/src/dev/hotGraph.ts

@@ -0,0 +1,109 @@
+/**
+ * The import graph a hot reload reasons over, and what it decides.
+ *
+ * Owned here rather than taken from `hot-hook`, which used to do this job. The
+ * package is 655 lines and four npm dependencies, and it had to be installed by
+ * every application because a dev-only loader has no business in a production
+ * install of the framework — so a project created before that convention simply
+ * lost hot reloading and was told nothing. The part that genuinely needs a
+ * library is the part Node now provides itself: `module.registerHooks` for the
+ * graph, `fs.watch` for the changes.
+ *
+ * NO node_modules dependency, deliberately: everything below is arithmetic on
+ * paths.
+ *
+ * The graph is built by the resolver as the program runs, never by reading
+ * files. A `resolve` hook is handed the importer and the imported, which is
+ * exactly an edge, and it sees dynamic imports as they happen — a static parse
+ * of the source could only guess at those.
+ */
+
+/** A module's place in the graph: who imports it, and which version is live. */
+interface Node {
+  /** Modules that imported this one. The graph is walked upward, so this is the direction stored. */
+  readonly importers: Set<string>
+  /** Bumped on invalidation; appended to the URL so the loader fetches the file again. */
+  version: number
+}
+
+/** What a change to one file means. */
+export type Decision =
+  | { kind: 'swap'; invalidated: string[] }
+  | { kind: 'reload'; file: string; reason: 'outside-boundaries' | 'restart-list' }
+  | { kind: 'ignore' }
+
+export class HotGraph {
+  readonly #nodes = new Map<string, Node>()
+  readonly #isBoundary: (file: string) => boolean
+  readonly #isRestart: (file: string) => boolean
+
+  constructor(options: {
+    isBoundary: (file: string) => boolean
+    isRestart: (file: string) => boolean
+  }) {
+    this.#isBoundary = options.isBoundary
+    this.#isRestart = options.isRestart
+  }
+
+  #node(file: string): Node {
+    let node = this.#nodes.get(file)
+    if (node === undefined) {
+      node = { importers: new Set(), version: 0 }
+      this.#nodes.set(file, node)
+    }
+    return node
+  }
+
+  /** Record that `importer` imported `file`. Called from the resolve hook. */
+  link(file: string, importer: string | undefined): void {
+    const node = this.#node(file)
+    if (importer !== undefined && importer !== file) node.importers.add(importer)
+  }
+
+  /** The version to hang off the URL, or 0 while the module has never been invalidated. */
+  version(file: string): number {
+    return this.#nodes.get(file)?.version ?? 0
+  }
+
+  /** Whether the resolver has ever seen this file. */
+  knows(file: string): boolean {
+    return this.#nodes.has(file)
+  }
+
+  /**
+   * What to do about `file` having changed.
+   *
+   * Walks up from the changed file collecting what has to be re-imported, and
+   * stops at each boundary: a boundary is imported dynamically, so the next
+   * import of it re-resolves, and with it everything below that was collected
+   * on the way. A path that reaches a module nobody imports without crossing a
+   * boundary cannot be re-imported by anyone, and that is a full reload.
+   *
+   * Deciding before invalidating matters: a decision that turns out to be a
+   * full reload must leave no version bumped behind, or a later swap would
+   * hand the caller a URL for a module the process never re-imported.
+   */
+  decide(file: string): Decision {
+    if (this.#isRestart(file)) return { kind: 'reload', file, reason: 'restart-list' }
+    if (!this.#nodes.has(file)) return { kind: 'ignore' }
+
+    const collected = new Set<string>()
+    const queue = [file]
+    while (queue.length > 0) {
+      const current = queue.pop()
+      if (current === undefined || collected.has(current)) continue
+      collected.add(current)
+      // A boundary is where the walk stops: whoever imports it does so
+      // dynamically and will ask for it again.
+      if (this.#isBoundary(current)) continue
+      const importers = this.#nodes.get(current)?.importers
+      if (importers === undefined || importers.size === 0) {
+        return { kind: 'reload', file, reason: 'outside-boundaries' }
+      }
+      for (const importer of importers) queue.push(importer)
+    }
+
+    for (const path of collected) this.#node(path).version += 1
+    return { kind: 'swap', invalidated: [...collected] }
+  }
+}

package/src/dev/hotWatcher.ts

@@ -0,0 +1,89 @@
+/**
+ * Watching the project for the changes a hot reload reacts to.
+ *
+ * `fs.watch` with `recursive: true`, which Node implements on Linux, macOS and
+ * Windows alike — the reason a watcher used to be a dependency here, and is not
+ * any more.
+ *
+ * Two behaviours are worth stating because they are not obvious from the API:
+ *
+ * A save is rarely one event. Editors write, rename and touch, and a single
+ * Ctrl-S can arrive as several notifications for the same file within a few
+ * milliseconds. Each one would walk the graph and bump a version, so they are
+ * coalesced.
+ *
+ * `ream dev` also watches from the outside, in Rust. That is not a duplicate:
+ * this watcher dies with the process it lives in, so a server that crashed on a
+ * syntax error has nothing left to notice the fix. The outer one covers exactly
+ * that window, and hands back over by restarting the process.
+ */
+
+import { type FSWatcher, watch } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/** How long to wait for a save to finish arriving before acting on it. */
+const SETTLE_MS = 40
+
+export interface WatcherOptions {
+  /** Project root; every reported path is absolute, resolved against it. */
+  root: string
+  /** Directories under the root to watch, when they exist. */
+  directories: readonly string[]
+  /** Individual files to watch — env files sit at the root, so no directory covers them. */
+  files: readonly string[]
+  /** Called once per settled change, with an absolute path. */
+  onChange: (file: string) => void
+}
+
+export interface Watcher {
+  close: () => void
+}
+
+export function watchProject(options: WatcherOptions): Watcher {
+  const watchers: FSWatcher[] = []
+  const pending = new Map<string, NodeJS.Timeout>()
+
+  const report = (file: string): void => {
+    const existing = pending.get(file)
+    if (existing !== undefined) clearTimeout(existing)
+    const timer = setTimeout(() => {
+      pending.delete(file)
+      options.onChange(file)
+    }, SETTLE_MS)
+    // The dev server must still be able to exit while a save is settling.
+    timer.unref?.()
+    pending.set(file, timer)
+  }
+
+  for (const directory of options.directories) {
+    const absolute = resolve(options.root, directory)
+    try {
+      watchers.push(
+        watch(absolute, { recursive: true }, (_event, name) => {
+          if (typeof name !== 'string' || name === '') return
+          report(join(absolute, name))
+        }),
+      )
+    } catch {
+      // A directory this project does not have is not an error: the list is
+      // the framework's conventional layout, not a requirement.
+    }
+  }
+
+  for (const file of options.files) {
+    const absolute = resolve(options.root, file)
+    try {
+      watchers.push(watch(absolute, () => report(absolute)))
+    } catch {
+      // Same: a `.env` that does not exist is simply not watched.
+    }
+  }
+
+  return {
+    close: () => {
+      for (const timer of pending.values()) clearTimeout(timer)
+      pending.clear()
+      for (const watcher of watchers) watcher.close()
+    },
+  }
+}

package/src/env/loadEnvFiles.ts

@@ -1,41 +1,82 @@
 import { readFileSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { parseEnv } from 'node:util'
 import { interpolate } from './interpolate.js'
 import { normalizeNodeEnv } from './nodeEnv.js'
 
 /**
- * Load `.env` files into `process.env` — the shared primitive behind both the
- * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
- * AdonisJS which loads env in every flow.
+ * The `.env*` files that will be read, most-specific first.
  *
- * Order is most-specific-first and "already-present wins", so the shell / CI
- * always overrides the files. Missing files are skipped silently. Uses Node's
- * built-in parser — no dependency.
+ * Exported because `@c9up/ream/hot` has to WATCH exactly this list: nothing
+ * imports an env file, so hot-hook's dependency tree never sees one and an
+ * edit to `.env` changed nothing at all. A second copy of the list in the
+ * loader entry would drift from this one the first time the naming changes.
  *
- * @param appRoot Directory URL the `.env*` files are resolved against.
- * @param options.skipEnvLocal Skip `.env.local` (the test flow does, so a
- *   developer's local overrides don't leak into tests).
+ * @param options.skipEnvLocal Skip `.env.local` — see {@link loadEnvFiles}.
  */
-export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
+export function envFileNames(options: { skipEnvLocal?: boolean } = {}): string[] {
   // Normalised, so `NODE_ENV=prod` loads `.env.production` — the file the
   // deployment actually wrote — instead of looking for `.env.prod`.
   const raw = normalizeNodeEnv(process.env.NODE_ENV)
   const nodeEnv = raw === 'unknown' ? undefined : raw
-  const files = [
+  return [
     nodeEnv ? `.env.${nodeEnv}.local` : null,
     options.skipEnvLocal ? null : '.env.local',
     nodeEnv ? `.env.${nodeEnv}` : null,
     '.env',
   ].filter((name): name is string => name !== null)
+}
+
+/**
+ * Where the `.env*` files are read from.
+ *
+ * Normally beside the application, which is what `appRoot` names. A BUILT
+ * application moves: `start/env.js` sits in `dist/`, so `new URL('../',
+ * import.meta.url)` resolves there and the files at the project root become
+ * invisible — `ream start` died on a `.env` it was standing next to.
+ *
+ * `ENV_PATH` is AdonisJS's own variable for this, named and shaped the same
+ * way: a DIRECTORY to read the files from, as in
+ * `ENV_PATH=/etc/secrets node server.js`. An application moving over keeps
+ * whatever it already sets.
+ *
+ * It is also why the ordering rule stays here rather than in the CLI: node's
+ * `--env-file` applies files last-wins while this loader applies them
+ * most-specific-first, and a second copy of that would be one to keep in step
+ * forever.
+ */
+function envDirectory(appRoot: URL): URL {
+  const override = process.env.ENV_PATH
+  if (override === undefined || override.trim() === '') return appRoot
+  // A directory URL, so `new URL('.env', directory)` lands inside it rather
+  // than beside it.
+  return pathToFileURL(override.endsWith('/') ? override : `${override}/`)
+}
 
-  for (const name of files) {
+/**
+ * Load `.env` files into `process.env` — the shared primitive behind both the
+ * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
+ * AdonisJS which loads env in every flow.
+ *
+ * Order is most-specific-first and "already-present wins", so the shell / CI
+ * always overrides the files. Missing files are skipped silently. Uses Node's
+ * built-in parser — no dependency.
+ *
+ * @param appRoot Directory URL the `.env*` files are resolved against.
+ * @param options.skipEnvLocal Skip `.env.local` (the test flow does, so a
+ *   developer's local overrides don't leak into tests).
+ */
+export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
+  const directory = envDirectory(appRoot)
+  let found = false
+  for (const name of envFileNames(options)) {
     let contents: string
     try {
-      contents = readFileSync(fileURLToPath(new URL(name, appRoot)), 'utf8')
+      contents = readFileSync(fileURLToPath(new URL(name, directory)), 'utf8')
     } catch {
       continue // file absent — nothing to load
     }
+    found = true
     const parsed = parseEnv(contents)
     for (const [key, value] of Object.entries(parsed)) {
       if (typeof value !== 'string' || process.env[key] !== undefined) continue
@@ -49,4 +90,18 @@ export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } =
       })
     }
   }
+
+  // Upstream raises when `ENV_PATH` names a place with no env file in it, and
+  // for the reason silence would be wrong: the variable is somebody saying
+  // where the file IS. A typo in the path would otherwise start a server on
+  // whatever defaults happened to be around, which is how a deployment reads
+  // its staging config in production and nobody finds out until later.
+  //
+  // Without `ENV_PATH` a missing file stays silent: an application may have
+  // none at all, and every value may come from the environment.
+  if (!found && process.env.ENV_PATH !== undefined && process.env.ENV_PATH.trim() !== '') {
+    throw new Error(
+      `ENV_PATH points at ${process.env.ENV_PATH}, which holds none of ${envFileNames(options).join(', ')}`,
+    )
+  }
 }