@c9up/ream 0.1.3

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@c9up/ream",
+  "version": "0.1.3",
+  "description": "Ream — Rust-powered Node.js application framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./services/app": {
+      "types": "./dist/services/app.d.ts",
+      "import": "./dist/services/app.js"
+    },
+    "./services/router": {
+      "types": "./dist/services/router.d.ts",
+      "import": "./dist/services/router.js"
+    },
+    "./services/server": {
+      "types": "./dist/services/server.d.ts",
+      "import": "./dist/services/server.js"
+    },
+    "./bodyparser": {
+      "types": "./dist/bodyparser/BodyParserMiddleware.d.ts",
+      "import": "./dist/bodyparser/BodyParserMiddleware.js"
+    },
+    "./session": {
+      "types": "./dist/session/SessionMiddleware.d.ts",
+      "import": "./dist/session/SessionMiddleware.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "import": "./dist/helpers/index.js"
+    },
+    "./helpers/string": {
+      "types": "./dist/helpers/string.d.ts",
+      "import": "./dist/helpers/string.js"
+    },
+    "./helpers/is": {
+      "types": "./dist/helpers/is.d.ts",
+      "import": "./dist/helpers/is.js"
+    },
+    "./helpers/base64": {
+      "types": "./dist/helpers/base64.d.ts",
+      "import": "./dist/helpers/base64.js"
+    },
+    "./helpers/types": {
+      "types": "./dist/helpers/types.d.ts",
+      "import": "./dist/helpers/types.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/TestClient.d.ts",
+      "import": "./dist/testing/TestClient.js"
+    },
+    "./bootstrap": {
+      "types": "./dist/bootstrap/hyper-server.d.ts",
+      "import": "./dist/bootstrap/hyper-server.js"
+    },
+    "./tsconfig.app.json": "./tsconfig.app.json",
+    "./swcrc.app.json": "./swcrc.app.json"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "index.*.node",
+    "scheduler.*.node",
+    "events.*.node",
+    "scripts",
+    "src",
+    "swcrc.app.json",
+    "tsconfig.app.json"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@types/node": "^22.19.15",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/ream.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:rust": "cargo build --release -p ream-http-napi -p ream-scheduler-napi -p ream-events-napi",
+    "build:napi": "pnpm build:rust && node scripts/copy-napi.mjs",
+    "test": "vitest run",
+    "test:rust": "cargo test --all",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/scripts/copy-napi.mjs

@@ -0,0 +1,113 @@
+// Copy every freshly-built Ream NAPI cdylib out of cargo's target
+// directory and into the package root with the platform-suffix naming
+// convention used by `napi-loader.ts`:
+//
+//     packages/ream/index.linux-x64-gnu.node       (ream-http-napi)
+//     packages/ream/scheduler.linux-x64-gnu.node   (ream-scheduler-napi)
+//     packages/ream/index.darwin-arm64.node
+//     ...
+//
+// The TS loader walks two upper directories from each `loadNapi` caller
+// to find these files, so the binaries MUST live at the package root
+// (not under target/) to be discovered at runtime.
+//
+// Usage:
+//
+//     pnpm --filter @c9up/ream build:rust     # cargo build --release
+//     pnpm --filter @c9up/ream build:napi     # build:rust + this script
+//
+// The package.json script chains both steps. CI / npm publish runs
+// `build:napi` once per platform during the matrix build — every
+// crate listed in `NAPI_CRATES` ships in the tarball.
+
+import { copyFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { arch, env, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+// Rust target triple -> { suffix, os }. Set CARGO_BUILD_TARGET to cross-compile
+// (e.g. build the x86_64-apple-darwin binary on an arm64 macOS runner so we
+// don't depend on the scarce macos-13 Intel runners). When unset we fall back
+// to the host platform/arch and the default target/release dir.
+const TRIPLE_MAP = {
+  'x86_64-unknown-linux-gnu': { suffix: 'linux-x64-gnu', os: 'linux' },
+  'aarch64-unknown-linux-gnu': { suffix: 'linux-arm64-gnu', os: 'linux' },
+  'x86_64-apple-darwin': { suffix: 'darwin-x64', os: 'darwin' },
+  'aarch64-apple-darwin': { suffix: 'darwin-arm64', os: 'darwin' },
+  'x86_64-pc-windows-msvc': { suffix: 'win32-x64-msvc', os: 'win32' },
+}
+
+const HOST_SUFFIX_MAP = {
+  'linux-x64': 'linux-x64-gnu',
+  'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64',
+  'darwin-arm64': 'darwin-arm64',
+  'win32-x64': 'win32-x64-msvc',
+}
+
+const triple = env.CARGO_BUILD_TARGET ?? ''
+let suffix
+let os
+let releaseDir
+if (triple) {
+  const entry = TRIPLE_MAP[triple]
+  if (!entry) {
+    throw new Error(`[ream:napi] unsupported CARGO_BUILD_TARGET: ${triple}`)
+  }
+  suffix = entry.suffix
+  os = entry.os
+  releaseDir = join(root, 'target', triple, 'release')
+} else {
+  suffix = HOST_SUFFIX_MAP[`${platform}-${arch}`]
+  os = platform
+  releaseDir = join(root, 'target', 'release')
+  if (!suffix) {
+    throw new Error(`[ream:napi] unsupported platform/arch: ${platform}-${arch}`)
+  }
+}
+
+// Every NAPI crate shipped from the @c9up/ream package. `crateLib` is the
+// underscore-suffixed name cargo produces under `target/release/`;
+// `targetName` is what `loadNapi({ binaryName })` expects at the package
+// root (see `napi-loader.ts` — the binary lookup prefix matches the
+// `binaryName` option passed by each TS consumer).
+const NAPI_CRATES = [
+  { crateLib: 'ream_http_napi', targetName: 'index' },
+  { crateLib: 'ream_scheduler_napi', targetName: 'scheduler' },
+  { crateLib: 'ream_events_napi', targetName: 'events' },
+]
+
+// `crate-type = ["cdylib"]` settles on the platform-conventional file
+// name. Linux + macOS prepend `lib`; Windows drops the prefix and uses
+// `.dll`. Check both Windows shapes so we degrade gracefully if upstream
+// cargo ever switches naming.
+function buildCandidates(crateLib) {
+  if (os === 'win32') {
+    return [
+      join(releaseDir, `${crateLib}.dll`),
+      join(releaseDir, `lib${crateLib}.dll`),
+    ]
+  }
+  if (os === 'darwin') {
+    return [join(releaseDir, `lib${crateLib}.dylib`)]
+  }
+  return [join(releaseDir, `lib${crateLib}.so`)]
+}
+
+for (const { crateLib, targetName } of NAPI_CRATES) {
+  const candidates = buildCandidates(crateLib)
+  const source = candidates.find((candidate) => existsSync(candidate))
+  if (!source) {
+    throw new Error(
+      `[ream:napi] native library for '${crateLib}' not found. Looked for:\n${candidates
+        .map((p) => `- ${p}`)
+        .join('\n')}\nRun 'pnpm --filter @c9up/ream build:rust' first.`,
+    )
+  }
+  const target = join(root, `${targetName}.${suffix}.node`)
+  copyFileSync(source, target)
+  console.log(`[ream:napi] copied ${source} -> ${target}`)
+}

package/src/Application.ts

@@ -0,0 +1,177 @@
+/**
+ * Application — manages providers, config, lifecycle, and signal handling.
+ *
+ * Like AdonisJS Application:
+ * - app.booting(callback) — register hooks that run during boot
+ * - app.booted(callback) — register hooks that run after boot completes
+ * - app.listen(signal, callback) — listen for process signals
+ * - app.listenIf(condition, signal, callback) — conditional signal listener
+ * - app.terminate() — graceful shutdown
+ * - app.managedByPm2 — PM2 detection
+ * - app.inProduction / app.inDev / app.inTest
+ *
+ * @implements FR17, FR20
+ */
+
+import { ConfigStore } from './ConfigLoader.js'
+import { Container } from './container/Container.js'
+import type { AppContext, ProviderContract } from './Provider.js'
+import { callProviderPhase } from './Provider.js'
+
+export class Application implements AppContext {
+  readonly container: Container
+  readonly config: ConfigStore
+  private providers: ProviderContract[] = []
+  private _booted = false
+  private _bootingHooks: Array<() => Promise<void> | void> = []
+  private _bootedHooks: Array<() => Promise<void> | void> = []
+  private _shutdownHooks: Array<() => Promise<void> | void> = []
+
+  constructor() {
+    this.container = new Container()
+    this.config = new ConfigStore()
+  }
+
+  // ─── Environment ──────────────────────────────────────────
+
+  /** Check if running in production. */
+  get inProduction(): boolean {
+    return process.env.NODE_ENV === 'production'
+  }
+
+  /** Check if running in development. */
+  get inDev(): boolean {
+    const env = process.env.NODE_ENV
+    return env !== 'production' && env !== 'test'
+  }
+
+  /** Check if running in test mode. */
+  get inTest(): boolean {
+    return process.env.NODE_ENV === 'test'
+  }
+
+  /** Check if managed by PM2. */
+  get managedByPm2(): boolean {
+    return 'PM2_HOME' in process.env || 'pm_id' in process.env
+  }
+
+  // ─── Lifecycle hooks ──────────────────────────────────────
+
+  /**
+   * Register a callback that runs during the boot phase (before providers boot).
+   * Like AdonisJS app.booting().
+   */
+  booting(callback: () => Promise<void> | void): void {
+    this._bootingHooks.push(callback)
+  }
+
+  /**
+   * Register a callback that runs after boot completes.
+   * Like AdonisJS app.booted().
+   */
+  booted(callback: () => Promise<void> | void): void {
+    if (this._booted) {
+      // Already booted — run immediately. Invoke callback() INSIDE the
+      // promise chain (not as `Promise.resolve(callback())`, which
+      // evaluates callback() eagerly and lets a synchronous throw
+      // escape to the caller) so both sync throws and async rejections
+      // are funnelled to the logger.
+      Promise.resolve()
+        .then(() => callback())
+        .catch((err) => {
+          process.stderr.write(`[Ream] booted() callback error: ${err}\n`)
+        })
+      return
+    }
+    this._bootedHooks.push(callback)
+  }
+
+  // ─── Signal handling ──────────────────────────────────────
+
+  /**
+   * Listen for a process signal.
+   * Like AdonisJS app.listen('SIGTERM', () => app.terminate()).
+   */
+  listen(signal: NodeJS.Signals, callback: () => void): void {
+    process.on(signal, callback)
+  }
+
+  /**
+   * Conditionally listen for a process signal.
+   * Like AdonisJS app.listenIf(app.managedByPm2, 'SIGINT', ...).
+   */
+  listenIf(condition: boolean, signal: NodeJS.Signals, callback: () => void): void {
+    if (condition) {
+      process.on(signal, callback)
+    }
+  }
+
+  /**
+   * Graceful shutdown — stop all providers and exit.
+   * Like AdonisJS app.terminate().
+   */
+  async terminate(): Promise<void> {
+    await this.shutdown()
+    process.exit(0)
+  }
+
+  // ─── Provider lifecycle ───────────────────────────────────
+
+  /** Register a provider instance. */
+  register(provider: ProviderContract): void {
+    this.providers.push(provider)
+    if (typeof provider.register === 'function') {
+      provider.register()
+    }
+  }
+
+  /** Boot all registered providers. Runs booting/booted hooks. */
+  async boot(): Promise<void> {
+    if (this._booted) return
+
+    // Run booting hooks
+    for (const hook of this._bootingHooks) {
+      await hook()
+    }
+
+    // Boot providers. `callProviderPhase` skips providers that don't
+    // declare the phase — duck-typed packages (spectrum, warden, etc.)
+    // implement only what they need.
+    for (const provider of this.providers) {
+      await callProviderPhase(provider, 'boot')
+    }
+
+    this._booted = true
+
+    // Run booted hooks
+    for (const hook of this._bootedHooks) {
+      await hook()
+    }
+  }
+
+  /** Shutdown all providers in reverse order. */
+  async shutdown(): Promise<void> {
+    // Run shutdown hooks
+    for (const hook of this._shutdownHooks) {
+      await hook()
+    }
+
+    for (const provider of [...this.providers].reverse()) {
+      await callProviderPhase(provider, 'shutdown')
+    }
+    this._booted = false
+  }
+
+  /** Register a shutdown hook. */
+  onShutdown(callback: () => Promise<void> | void): void {
+    this._shutdownHooks.push(callback)
+  }
+
+  get isBooted(): boolean {
+    return this._booted
+  }
+
+  get providerCount(): number {
+    return this.providers.length
+  }
+}