@c9up/ream 0.2.13 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -212,9 +212,7 @@
     "tsconfig.client.json"
   ],
   "dependencies": {
-    "etag": "^1.8.1",
     "file-type": "^22.0.1",
-    "mime-types": "^3.0.1",
     "reflect-metadata": "^0.2"
   },
   "peerDependencies": {
@@ -230,11 +228,11 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "2.5.12",
     "@c9up/comet": "^0.1.0",
-    "@types/etag": "^1.8.4",
-    "@types/mime-types": "^3.0.1",
     "@types/node": "^22.19.15",
+    "mime-db": "^1.54.0",
+    "mime-types": "^3.0.2",
     "typescript": "^6.0.2",
     "vitest": "^4.1.6"
   },
@@ -259,6 +257,6 @@
     "lint": "biome check src/",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "typecheck:console-tests": "tsc --noEmit -p tsconfig.tests.json"
+    "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json"
   }
 }

package/scripts/build-napi-types.mjs

@@ -7,7 +7,8 @@
  * cargo a `/tmp/...` path the native proc-macro cannot write to, so the
  * type-def file comes back empty and the build fails for no visible reason.
  *
- * One crate at a time on purpose: napi-derive APPENDS to `TYPE_DEF_TMP_PATH`
+ * One crate at a time on purpose: with napi-derive 2 the writes all went to a
+ * single `TYPE_DEF_TMP_PATH` and a parallel build interleaved them
  * while cargo compiles, and a parallel build interleaves the writes —
  * definitions go missing, silently, and the generated file comes out short.
  */
@@ -28,11 +29,11 @@ const scratch = mkdtempSync(join(tmpdir(), 'napi-types-'))
 try {
   const lines = []
   for (const crate of CRATES) {
-    const perCrate = join(scratch, `${crate}.jsonl`)
+    const perCrate = join(scratch, crate)
     writeFileSync(perCrate, '')
     execFileSync('cargo', ['build', '-p', crate], {
       cwd: packageRoot,
-      env: { ...process.env, TYPE_DEF_TMP_PATH: perCrate },
+      env: { ...process.env, NAPI_TYPE_DEF_TMP_FOLDER: scratch },
       stdio: ['ignore', 'ignore', 'inherit'],
     })
     const emitted = readFileSync(perCrate, 'utf8').split('\n').filter(Boolean)

package/scripts/generate-mime.mjs

@@ -0,0 +1,119 @@
+/**
+ * Regenerate `src/http/mime.ts` from mime-db.
+ *
+ * The table is data, not logic, and hand-maintaining it is how `.yaml` and
+ * `.sql` went missing. `mime-types` reads the same two fields out of mime-db —
+ * the resolved extension map and the per-type `charset` — so generating from
+ * there keeps `contentType()` answering exactly what the package answered.
+ *
+ * mime-db and mime-types are dev-only: they are read HERE, at generation time,
+ * and never imported by the framework.
+ *
+ *     node scripts/generate-mime.mjs
+ */
+
+import { createRequire } from 'node:module'
+import { writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+const mimeTypes = require('mime-types')
+const db = require('mime-db')
+const dbVersion = require('mime-db/package.json').version
+
+const here = dirname(fileURLToPath(import.meta.url))
+const target = join(here, '..', 'src', 'http', 'mime.ts')
+
+/**
+ * Emitted in the package's own style — single quotes, no semicolons — so a
+ * regenerated file is already what `biome check` wants and the diff after a
+ * regeneration is the data that changed, nothing else.
+ */
+const quote = (value) => `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+/** An identifier when it is one, a quoted key otherwise (`7z`, `3gp`…). */
+const key = (ext) => (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(ext) ? ext : quote(ext))
+
+const extensions = Object.keys(mimeTypes.types).sort()
+const rows = extensions.map((e) => `  ${key(e)}: ${quote(mimeTypes.types[e])},`).join('\n')
+
+const charsets = Object.entries(db)
+  .filter(([, entry]) => entry.charset)
+  .sort(([a], [b]) => a.localeCompare(b))
+  .map(([type, entry]) => `  ${quote(type)}: ${quote(entry.charset.toLowerCase())},`)
+  .join('\n')
+
+await writeFile(target, render({ rows, charsets, dbVersion, count: extensions.length }))
+process.stdout.write(`mime.ts: ${extensions.length} extensions from mime-db ${dbVersion}\n`)
+
+function render({ rows, charsets, dbVersion, count }) {
+  return `/**
+ * Content types for a response, resolved here rather than pulled in.
+ *
+ * \`response.type("txt")\` has to become \`text/plain; charset=utf-8\`, which is a
+ * lookup table and one charset rule — the same job \`@c9up/archive\` already
+ * does in its own table, so the framework was carrying a dependency for work
+ * the ecosystem already owned.
+ *
+ * A hand-written table is what made that a regression rather than a saving:
+ * it knew the extensions someone thought of, so \`.yaml\`, \`.sql\`, \`.opus\` and
+ * \`.xhtml\` fell through and the caller's own string went out as the content
+ * type. The tables below are GENERATED from mime-db instead, which is where
+ * \`mime-types\` reads them too, so the resolution is the same one and stays
+ * the same one.
+ *
+ * Regenerate with:
+ *
+ *     node scripts/generate-mime.mjs
+ *
+ * Do not edit {@link TYPES} or {@link CHARSETS} by hand.
+ *
+ * @generated from mime-db ${dbVersion} (${count} extensions)
+ */
+
+/** Extension → type. No leading dot; lowercase. */
+const TYPES: Record<string, string> = {
+${rows}
+}
+
+/**
+ * Types that declare a charset of their own, lowercased.
+ *
+ * Everything else under \`text/\` defaults to utf-8; everything else has none.
+ * That is mime-db's \`charset\` field plus \`mime-types\`' \`text/*\` fallback.
+ */
+const CHARSETS: Record<string, string> = {
+${charsets}
+}
+
+/** The charset for a type, or \`undefined\` when it carries none. */
+function charsetFor(type: string): string | undefined {
+  const base = type.split(';')[0].trim().toLowerCase()
+  const declared = CHARSETS[base]
+  if (declared !== undefined) return declared
+  return base.startsWith('text/') ? 'utf-8' : undefined
+}
+
+/** The type for a bare extension, or \`undefined\` when it is not one we know. */
+export function lookupType(extension: string): string | undefined {
+  const ext = extension.replace(/^.*\\./, '').toLowerCase()
+  return TYPES[ext]
+}
+
+/**
+ * A full \`Content-Type\` for an extension or a type (\`mime-types.contentType\`).
+ *
+ * Returns \`false\` for something it cannot resolve, as the package did, so the
+ * caller keeps its existing fallback rather than writing \`content-type: false\`.
+ */
+export function contentType(input: string): string | false {
+  if (input.length === 0) return false
+  // Already a type — possibly with parameters the caller set itself.
+  const type = input.includes('/') ? input : lookupType(input)
+  if (type === undefined) return false
+  if (type.includes('charset=')) return type
+  const charset = charsetFor(type)
+  return charset === undefined ? type : \`\${type}; charset=\${charset}\`
+}
+`
+}

package/scripts/generate-napi-types.mjs

@@ -29,27 +29,40 @@ import { readFileSync, writeFileSync } from 'node:fs'
  * entry must match, or the script fails: a stale refinement is how a hand
  * annotation quietly stops describing the Rust.
  */
+/**
+ * napi-derive 3 emits `callback: (arg: unknown) => unknown` where 2 emitted
+ * `(...args: any[]) => any` — better, since it no longer reaches for `any`,
+ * but a different string to match on. These refinements exist because the
+ * generated shape says nothing about what the callback actually receives.
+ */
 const CALLBACK_REFINEMENTS = {
   'EventBus.subscribe': {
-    from: 'callback: (...args: any[]) => any',
+    from: 'callback: (arg: unknown) => unknown',
     to: 'callback: (eventJson: string) => void',
   },
   'EventBus.onRequest': {
-    from: 'callback: (...args: any[]) => any',
+    from: 'callback: (arg: unknown) => unknown',
     to: 'callback: (eventJson: string, reply: (response: string) => void) => void',
   },
   'HyperServer.onRequest': {
-    from: 'callback: (...args: any[]) => any',
-    to: 'callback: (request: string) => Promise<string> | string',
+    // Only the argument is named. The `to` used to say
+    // `(request: string) => Promise<string> | string`, which described the
+    // boundary as it was BEFORE it stopped serialising: the Rust hands the
+    // handler a JsObject and awaits a `NapiResponse`, and napi's own output
+    // already said so. The refinement was overwriting a correct shape with a
+    // stale one, and nothing noticed because every caller of `onRequest` was
+    // outside the typecheck.
+    from: 'callback: (arg: unknown) => Promise<NapiResponse>',
+    to: 'callback: (request: Record<string, unknown>) => Promise<NapiResponse>',
   },
   'HyperServer.onStreamDisconnect': {
-    from: 'callback: (...args: any[]) => any',
+    from: 'callback: (arg: unknown) => unknown',
     to: 'callback: (streamId: string) => void',
   },
   // The Rust hands over a serialised JsTaskPayload — `{ task_name,
   // scheduled_for_ms }` renamed to camelCase by serde.
   'RustScheduler.register': {
-    from: 'callback: (...args: any[]) => any',
+    from: 'callback: (arg: unknown) => unknown',
     to: 'callback: (invocation: { taskName: string; scheduledForMs: number }) => void',
   },
 }
@@ -150,12 +163,15 @@ for (const fn of fns) {
   // napi-derive emits the whole declaration for a function, unlike a struct
   // where `def` holds only the members.
   const declaration = fn.def.trim()
-  out.push(
-    declaration.startsWith('export declare function')
-      ? `${declaration};`
-      : `export declare function ${fn.name}${declaration};`,
-    '',
-  )
+  // napi-derive 3 emits a bare `function name(...)` where 2 emitted the
+  // signature after the name; concatenating onto the former produced
+  // `function xfunction x(...)`.
+  const rendered = declaration.startsWith('export declare function')
+    ? declaration
+    : declaration.startsWith('function ')
+      ? `export declare ${declaration}`
+      : `export declare function ${fn.name}${declaration}`
+  out.push(`${rendered};`, '')
 }
 
 const stale = Object.keys(CALLBACK_REFINEMENTS).filter((k) => !used.has(k))

package/src/Application.ts

@@ -181,7 +181,12 @@ export class Application implements AppContext {
 
   /** Resolve inside one of the conventional directories. */
   #inDirectory(key: keyof DirectoriesNode, paths: string[]): string {
-    return this.makePath(this.#directories[key], ...paths)
+    // `DirectoriesNode` is an index signature, so a key nobody registered
+    // reads as undefined rather than failing to compile. Falling back to the
+    // key itself keeps the convention: `configPath()` under a node with no
+    // `config` entry resolves to `<root>/config`, which is where it would
+    // have been anyway.
+    return this.makePath(this.#directories[key] ?? String(key), ...paths)
   }
 
   /** Absolute path inside the `config/` directory. */

package/src/GracefulShutdown.ts

@@ -65,12 +65,12 @@ export function installGracefulShutdown(options: ShutdownOptions): ShutdownHandl
       // Second signal while draining — escalate immediately.
       logger.error('Forced exit: second signal received during shutdown')
       process.exit(1)
-      return
+    } else {
+      shutdown().catch((err) => {
+        logger.error(`Fatal: ${err}`)
+        process.exit(1)
+      })
     }
-    shutdown().catch((err) => {
-      logger.error(`Fatal: ${err}`)
-      process.exit(1)
-    })
   }
 
   const onSigterm = handleSignal

package/src/Provider.ts

@@ -7,12 +7,31 @@
  *   register() → boot() → start() → ready() → ... → shutdown()
  */
 
-import type { ConfigStore } from './ConfigLoader.js'
 import type { Container } from './container/Container.js'
 
+/**
+ * The config a provider reads, as a CONTRACT rather than as the class.
+ *
+ * `ConfigStore` satisfies it, so nothing that holds a real one changes. But
+ * typed as the class, `AppContext` demanded a private `#tree` no one outside
+ * `ConfigLoader` can produce — so a test could not substitute a config, and an
+ * independently-published package could not describe an `AppContext` at all
+ * without importing `@c9up/ream`, which is the coupling the comment below this
+ * one exists to avoid. bay, station and blackhole each re-declared their own
+ * for exactly that reason.
+ *
+ * `get` and `set` are what providers actually use; a `ConfigStore`'s other
+ * methods stay reachable on the concrete type.
+ */
+export interface ConfigReader {
+  get<T = unknown>(key: string): T | undefined
+  get<T = unknown>(key: string, defaultValue: T): T
+  set(key: string, value: unknown): void
+}
+
 export interface AppContext {
   container: Container
-  config: ConfigStore
+  config: ConfigReader
 }
 
 /**

package/src/bodyparser/MultipartFile.ts

@@ -1,3 +1,51 @@
+/**
+ * The top-level mime types IANA registers.
+ *
+ * Closed on purpose. Typing {@link MultipartFile.type} as a bare `string` let
+ * `file.type === 'image/png'` compile and quietly never match — a mime filter
+ * that passes everything, which is the shape a comment used to warn about and
+ * a compiler can simply refuse. Against this union that comparison is an
+ * error, and {@link MultipartFile.mime} is what a full-mime check wants.
+ *
+ * A top-level type outside this list is malformed: an unregistered format
+ * belongs under one of these trees, `application/x-…` rather than `x-foo/bar`.
+ *
+ * Additive, not a replacement: {@link MultipartFile.type} keeps upstream's
+ * `string` and its raw segment, and {@link MultipartFile.registeredType}
+ * narrows it here for callers who want `=== 'image/png'` refused at compile
+ * time. Nothing a valid AdonisJS call site does stops compiling, and no type
+ * outside this set is swallowed — closing `type` itself would have done both.
+ */
+export type MimeType =
+  | 'application'
+  | 'audio'
+  | 'example'
+  | 'font'
+  | 'image'
+  | 'message'
+  | 'model'
+  | 'multipart'
+  | 'text'
+  | 'video'
+
+const MIME_TYPES = new Set<string>([
+  'application',
+  'audio',
+  'example',
+  'font',
+  'image',
+  'message',
+  'model',
+  'multipart',
+  'text',
+  'video',
+])
+
+/** Whether a parsed top-level type is one IANA registers. */
+function isMimeType(value: string): value is MimeType {
+  return MIME_TYPES.has(value)
+}
+
 /**
  * MultipartFile — represents an uploaded file.
  *
@@ -28,14 +76,32 @@ export class MultipartFile {
    * `image/png` would otherwise sail through a mime allowlist. A renamed file
    * reports what it actually is.
    *
-   * BREAKING as of 0.2.0: it used to hold the whole `image/png`. TypeScript
-   * cannot catch a comparison against a full mime string — `file.type ===
-   * 'image/png'` still compiles and simply never matches. Use {@link mime}.
+   * BREAKING as of 0.2.0: it used to hold the whole `image/png`. A comparison
+   * against a full mime — `file.type === 'image/png'` — compiles and never
+   * matches, which is what {@link mime} exists for, and what
+   * {@link registeredType} refuses at compile time for callers who want that.
+   *
+   * `string` and the raw segment, as upstream: a type outside the registered
+   * set is still reported rather than swallowed.
    */
   get type(): string | undefined {
     return this.#mimeParts()[0]
   }
 
+  /**
+   * The same primary type, narrowed to what IANA registers.
+   *
+   * Additive, and the point of it: against a closed union
+   * `file.registeredType === 'image/png'` is a compile error instead of a
+   * comparison that always fails. `undefined` where {@link type} holds
+   * something outside the set — a malformed or unregistered tree — so the two
+   * disagree exactly there and nowhere else.
+   */
+  get registeredType(): MimeType | undefined {
+    const type = this.#mimeParts()[0]
+    return type !== undefined && isMimeType(type) ? type : undefined
+  }
+
   /** The mime SUBTYPE — `png` for `image/png`. Same source as {@link type}. */
   get subtype(): string | undefined {
     return this.#mimeParts()[1]
@@ -59,7 +125,10 @@ export class MultipartFile {
   #mimeParts(): [string | undefined, string | undefined] {
     const source = this.#detected?.mime ?? this.#headerMime
     if (!source) return [undefined, undefined]
-    const [type, subtype] = source.split(';')[0].trim().split('/')
+    // `split` always yields a first element; naming it is how that stops
+    // being something the compiler has to be told.
+    const [head = ''] = source.split(';')
+    const [type, subtype] = head.trim().split('/')
     return [type || undefined, subtype || undefined]
   }
 
@@ -297,7 +366,7 @@ export class MultipartFile {
    * passing `file.clientName` straight through.
    */
   async move(location: string, options?: { name?: string; overwrite?: boolean }): Promise<void> {
-    const { mkdir, writeFile, access } = await import('node:fs/promises')
+    const { mkdir, writeFile } = await import('node:fs/promises')
     const { join } = await import('node:path')
 
     const name = options?.name ?? `${randomBytes(16).toString('hex')}.${this.extname || 'unknown'}`
@@ -308,20 +377,28 @@ export class MultipartFile {
     }
 
     const filePath = join(location, name)
-    if (options?.overwrite === false) {
-      const exists = await access(filePath).then(
-        () => true,
-        () => false,
-      )
-      if (exists) {
+    await mkdir(location, { recursive: true })
+
+    // NAMED DEVIATION — the refusal is ATOMIC where upstream's is not.
+    //
+    // Upstream checks `pathExists` and then renames, so two uploads landing on
+    // the same name both see nothing and both succeed: the second silently
+    // replaces the first, which is the one thing `overwrite: false` exists to
+    // prevent. `wx` is O_EXCL — the kernel decides, and exactly one of the two
+    // writes wins.
+    //
+    // The message is upstream's, word for word: a caller matching on it keeps
+    // working, and only the race is gone.
+    try {
+      await writeFile(filePath, this.content, options?.overwrite === false ? { flag: 'wx' } : {})
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
         throw new Error(
           `"${name}" already exists at "${location}". Set "overwrite = true" to overwrite it`,
         )
       }
+      throw error
     }
-
-    await mkdir(location, { recursive: true })
-    await writeFile(filePath, this.content)
     this.markAsMoved(name, filePath)
   }
 
@@ -358,8 +435,9 @@ function isSafeFilename(name: string): boolean {
 function parseFileSize(size: string): number {
   const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
   if (!match) return 1024 * 1024
-  const num = parseInt(match[1], 10)
-  switch (match[2]?.toLowerCase()) {
+  const [, digits, unit] = match
+  const num = parseInt(digits ?? '0', 10)
+  switch (unit?.toLowerCase()) {
     case 'kb':
       return num * 1024
     case 'mb':

package/src/bodyparser/parseSize.ts

@@ -6,8 +6,9 @@
 export function parseSize(size: string): number {
   const match = size.match(/^(\d+)(kb|mb|gb)?$/i)
   if (!match) return 1024 * 1024 // default 1mb
-  const num = parseInt(match[1], 10)
-  switch (match[2]?.toLowerCase()) {
+  const [, digits, unit] = match
+  const num = parseInt(digits ?? '0', 10)
+  switch (unit?.toLowerCase()) {
     case 'kb':
       return num * 1024
     case 'mb':

package/src/commands/MigrateBase.ts

@@ -19,7 +19,10 @@ import type { MigrationRegistry } from '../migrations/MigrationRegistry.js'
 import type { RegisteredMigrationSource } from '../migrations/types.js'
 
 export abstract class MigrateBase extends BaseCommand {
-  static override options: CommandOptions = { startApp: true }
+  // `drivesMigrations` because these three ARE the migration run: without it the
+  // boot applies everything first, so `migrate` says "nothing to migrate" after
+  // the work is done, and `migrate:status` mutates the schema it reports on.
+  static override options: CommandOptions = { startApp: true, drivesMigrations: true }
 
   @flags.string({
     description: 'Only this migration source, by the name its package registered',

package/src/console/BaseCommand.ts

@@ -117,7 +117,7 @@ export abstract class BaseCommand {
   error?: unknown
 
   /** Assigned by the kernel — see {@link terminate}. */
-  protected declare onTerminate?: () => void | Promise<void>
+  declare protected onTerminate?: () => void | Promise<void>
 
   /**
    * Lifecycle hooks, run in this order around `run()`: `prepare`, `interact`,

package/src/console/Kernel.ts

@@ -999,6 +999,14 @@ export class Kernel {
       )
     }
 
+    // Before the boot, not after: a data package that migrates on boot for the
+    // convenience of `dev` would otherwise apply everything a moment before the
+    // command that exists to apply it runs — leaving `migrate` with nothing to
+    // report and `migrate:status` having changed what it was asked to look at.
+    if (Command.options?.drivesMigrations === true) {
+      process.env.REAM_SKIP_BOOT_MIGRATE = '1'
+    }
+
     return this.#startApp()
   }
 

package/src/console/types.ts

@@ -37,6 +37,21 @@ export interface CommandOptions {
    * default so a typo (`--warm` for `--warn`) is reported, not swallowed.
    */
   allowUnknownFlags?: boolean
+
+  /**
+   * This command drives migrations itself, so booting must not run them.
+   *
+   * A data package may migrate on boot for the convenience of `dev` — atlas
+   * does, outside production. For the commands that exist to migrate, that
+   * convenience is the bug: the boot applies everything, and then `migrate`
+   * reports "nothing to migrate" while `migrate:status`, asked only to look,
+   * has changed the schema it is reporting on.
+   *
+   * Declaring this sets `REAM_SKIP_BOOT_MIGRATE=1` before the application
+   * starts, which is the flag a data package watches for. Any package's own
+   * migration command opts in the same way; the framework names none of them.
+   */
+  drivesMigrations?: boolean
 }
 
 /** Metadata recorded by an `@args.*` decorator. */