@jongodb/memory-server 0.1.1 → 0.1.3

package/README.md

@@ -1,68 +1,38 @@
 # @jongodb/memory-server
 
-Node test runtime adapter for `jongodb`.
+Node test runtime adapter for [`jongodb`](https://github.com/midagedev/jongodb).
 
-It starts a local `jongodb` launcher process, exposes a MongoDB URI, and manages process lifecycle for test runners.
+It starts a local `jongodb` launcher process, provides a MongoDB URI, and manages lifecycle for test runners.
+
+## Why This Package Exists
+
+`mongodb-memory-server` is useful, but it still depends on `mongod` bootstrap behavior.
+
+`@jongodb/memory-server` focuses on a different tradeoff:
+- faster integration-test startup loops
+- deterministic local process lifecycle control
+- simple test runner integration (Jest, Vitest, Nest Jest)
+
+This package is for test runtime usage only. It is not a production MongoDB server.
+
+## Value for Integration Test Suites
+
+Observed benchmark summary on one NestJS integration suite shape:
+- historical suite-scoped lifecycle: about `55.9%` faster than `mongodb-memory-server`
+- current single-boot lifecycle: about `64.2%` faster than `mongodb-memory-server`
+
+Actual deltas vary by test shape, dataset size, and CI machine characteristics.
 
 ## Scope
 
-- integration-test runtime only
-- launcher lifecycle management (start/stop/detach)
-- framework-agnostic base helper
-- Jest/Vitest/Nest Jest convenience helpers
-
-This package is not a production MongoDB server.
-
-## Why This vs Embedded MongoDB (`mongodb-memory-server`)
-
-`@jongodb/memory-server` can run in native binary mode instead of booting a full `mongod` test binary.
-
-Practical effects:
-
-- no `mongod` binary download/extract step in cold environments
-- lower launcher startup overhead in many integration-test loops
-- fewer environment issues tied to `mongod` binary provisioning
-
-Rough performance expectation (not a guarantee):
-
-- cold CI/dev machine: often much faster because there is no `mongod` artifact fetch/unpack
-- warm cache environment: startup-phase wins are usually smaller
-
-Observed benchmarks (NestJS integration suite subset, same machine):
-
-- Benchmark A: suite-scoped lifecycle (historical)
-  - workload: `9 suites / 102 tests` (`--runInBand`)
-  - server boots: `9` times per run (once per suite)
-  - `mongodb-memory-server` real:
-    - run1: `28.17s`
-    - run2: `27.19s`
-    - average: `27.68s`
-  - `jongodb` native real:
-    - run1: `12.35s`
-    - run2: `12.04s`
-    - average: `12.20s`
-  - delta: about `55.9%` faster (`15.48s` less wall clock)
-- Benchmark B: single-boot lifecycle (current)
-  - workload: `45 suites / 510 tests` (`--runInBand`)
-  - server boots: `1` time per run (shared for full Jest process)
-  - `mongodb-memory-server` real:
-    - run1: `92.40s`
-    - run2: `91.84s`
-    - average: `92.12s`
-  - `jongodb` native real:
-    - run1: `33.03s`
-    - run2: `32.90s`
-    - average: `32.97s`
-  - delta: about `64.2%` faster (`59.15s` less wall clock)
-
-Your actual delta depends on test shape, I/O, and query workload.
+- integration-test runtime helper
+- launcher process start/stop/detach lifecycle
+- framework-agnostic runtime API
+- convenience hooks for Jest, Vitest, and Nest Jest
 
 ## Requirements
 
 - Node.js 20+
-- one launcher runtime:
-  - native binary, or
-  - Java 17+ with `jongodb` classpath
 
 ## Install
 
@@ -70,16 +40,24 @@ Your actual delta depends on test shape, I/O, and query workload.
 npm i -D @jongodb/memory-server
 ```
 
-## Quick Start (Recommended)
+## Module Format
+
+This package supports both:
+- ESM (`import`)
+- CommonJS (`require`)
 
-Use `createJongodbEnvRuntime` and keep one runtime per test process.
+## Quick Start
+
+Recommended pattern: one runtime per test process.
 
 ```ts
 import { beforeAll, afterAll } from "@jest/globals";
 import { createJongodbEnvRuntime } from "@jongodb/memory-server/runtime";
 
 const runtime = createJongodbEnvRuntime({
-  databaseName: "test"
+  databaseName: "test",
+  databaseNameStrategy: "worker",
+  envVarNames: ["MONGODB_URI", "DATABASE_URL"],
 });
 
 beforeAll(async () => {
@@ -91,77 +69,67 @@ afterAll(async () => {
 });
 ```
 
-Behavior:
-
-- `setup()` starts launcher and writes `process.env.MONGODB_URI` (default)
-- `teardown()` stops launcher and restores previous env value
-
-## Launcher Modes
-
-`launchMode` values:
-
-- `auto` (default): binary first, Java fallback
-- `binary`: binary only, fail fast if binary not resolvable
-- `java`: Java only, fail fast if classpath not configured
-
-In `auto` mode, launch failures are attempted in order and reported with source tags.
+Runtime behavior:
+- `setup()` starts launcher and writes URI to configured env key(s)
+- `teardown()` stops launcher and restores previous env values
 
-## Binary Runtime
+CommonJS example:
 
-Binary resolution order:
-
-1. `options.binaryPath`
-2. `JONGODB_BINARY_PATH`
-3. bundled platform package (if installed)
+```js
+const { createJongodbEnvRuntime } = require("@jongodb/memory-server/runtime");
+const runtime = createJongodbEnvRuntime({ databaseName: "test" });
+```
 
-Current bundled package targets:
+## Migration from `mongodb-memory-server`
 
-- `@jongodb/memory-server-bin-darwin-arm64`
-- `@jongodb/memory-server-bin-linux-x64-gnu`
-- `@jongodb/memory-server-bin-win32-x64`
+Basic Jest migration:
 
-Version policy:
+Before:
 
-- binary package versions are pinned to the core package version (`optionalDependencies`)
-- if a bundled binary is not installed/available for your version, `auto` mode can still run with Java fallback
+```ts
+import { MongoMemoryServer } from "mongodb-memory-server";
 
-Binary-only example:
+let mongod: MongoMemoryServer;
 
-```ts
-import { startJongodbMemoryServer } from "@jongodb/memory-server";
+beforeAll(async () => {
+  mongod = await MongoMemoryServer.create();
+  process.env.MONGODB_URI = mongod.getUri();
+});
 
-const server = await startJongodbMemoryServer({
-  launchMode: "binary",
-  binaryPath: process.env.JONGODB_BINARY_PATH
+afterAll(async () => {
+  await mongod.stop();
 });
 ```
 
-## Java Runtime
+After:
 
-Provide classpath by:
+```ts
+import { beforeAll, afterAll } from "@jest/globals";
+import { createJongodbEnvRuntime } from "@jongodb/memory-server/runtime";
 
-1. `startJongodbMemoryServer({ classpath: "..." })`, or
-2. `JONGODB_CLASSPATH`
+const runtime = createJongodbEnvRuntime({ databaseName: "test" });
 
-Repository helper command (when using this repo launcher build):
+beforeAll(async () => {
+  await runtime.setup();
+});
 
-```bash
-./.tooling/gradle-8.10.2/bin/gradle -q printLauncherClasspath
+afterAll(async () => {
+  await runtime.teardown();
+});
 ```
 
-## Standalone Launcher Contract
-
-Binary and Java launchers follow one contract:
+Option mapping:
+- `MongoMemoryServer.create({ instance: { port } })` -> `createJongodbEnvRuntime({ port })`
+- `MongoMemoryServer.create({ instance: { dbName } })` -> `createJongodbEnvRuntime({ databaseName })`
+- `mongod.getUri()` -> `runtime.uri` (after `setup`) or configured env var
+- `mongod.stop()` -> `runtime.teardown()`
 
-- readiness line on stdout: `JONGODB_URI=mongodb://...`
-- optional failure line on stderr: `JONGODB_START_FAILURE=...`
-- process remains alive until terminated by signal (`SIGTERM`/`SIGINT`)
-
-The adapter relies on this contract for deterministic startup/teardown handling.
+Parallel test tip:
+- set `databaseNameStrategy: "worker"` to isolate worker data by database name
 
-## Runner Helpers
+## Runner Integrations
 
-### Jest (per-file hooks)
+Jest (per-file hooks):
 
 ```ts
 import { beforeAll, afterAll } from "@jest/globals";
@@ -170,9 +138,9 @@ import { registerJongodbForJest } from "@jongodb/memory-server/jest";
 registerJongodbForJest({ beforeAll, afterAll });
 ```
 
-### Jest (global setup/teardown)
+Jest (global setup/teardown):
 
-`jest.global-setup.ts`:
+`jest.global-setup.ts`
 
 ```ts
 import { createJestGlobalSetup } from "@jongodb/memory-server/jest";
@@ -180,7 +148,7 @@ import { createJestGlobalSetup } from "@jongodb/memory-server/jest";
 export default createJestGlobalSetup();
 ```
 
-`jest.global-teardown.ts`:
+`jest.global-teardown.ts`
 
 ```ts
 import { createJestGlobalTeardown } from "@jongodb/memory-server/jest";
@@ -188,7 +156,7 @@ import { createJestGlobalTeardown } from "@jongodb/memory-server/jest";
 export default createJestGlobalTeardown();
 ```
 
-### Vitest
+Vitest:
 
 ```ts
 import { beforeAll, afterAll } from "vitest";
@@ -197,7 +165,7 @@ import { registerJongodbForVitest } from "@jongodb/memory-server/vitest";
 registerJongodbForVitest({ beforeAll, afterAll });
 ```
 
-### NestJS (Jest E2E)
+NestJS (Jest E2E):
 
 ```ts
 import { beforeAll, afterAll } from "@jest/globals";
@@ -206,25 +174,45 @@ import { registerJongodbForNestJest } from "@jongodb/memory-server/nestjs";
 registerJongodbForNestJest({ beforeAll, afterAll });
 ```
 
-## Common Integration Patterns
+Common patterns:
+- NestJS + Mongoose: use `process.env.MONGODB_URI` in `forRootAsync`
+- Prisma (Mongo): set runtime `envVarNames` to include `DATABASE_URL`
+- TypeORM (Mongo): pass runtime URI into `url`
 
-- NestJS + Mongoose: `MongooseModule.forRootAsync({ useFactory: () => ({ uri: process.env.MONGODB_URI }) })`
-- Express/Fastify: inject `process.env.MONGODB_URI` into DB bootstrap before app init
-- Prisma (Mongo): set `envVarName: "DATABASE_URL"` for runtime helper
-- TypeORM (Mongo): pass runtime URI as `url`
+## Runtime Resolution
+
+`launchMode` values:
+- `auto` (default): binary first, Java fallback
+- `binary`: binary only
+- `java`: Java only
+
+Binary resolution order:
+1. `options.binaryPath`
+2. `JONGODB_BINARY_PATH`
+3. bundled platform binary package
+
+Bundled targets:
+- `@jongodb/memory-server-bin-darwin-arm64`
+- `@jongodb/memory-server-bin-linux-x64-gnu`
+- `@jongodb/memory-server-bin-win32-x64`
+
+Java fallback:
+- set `classpath` option or `JONGODB_CLASSPATH`
+
+Launcher contract:
+- stdout ready line: `JONGODB_URI=mongodb://...`
+- optional stderr failure line: `JONGODB_START_FAILURE=...`
+- process stays alive until termination signal
 
 ## API Surface
 
 Main export (`@jongodb/memory-server`):
-
 - `startJongodbMemoryServer(options?)`
 
 Runtime export (`@jongodb/memory-server/runtime`):
-
 - `createJongodbEnvRuntime(options?)`
 
 Jest export (`@jongodb/memory-server/jest`):
-
 - `registerJongodbForJest(hooks, options?)`
 - `createJestGlobalSetup(options?)`
 - `createJestGlobalTeardown(options?)`
@@ -232,39 +220,40 @@ Jest export (`@jongodb/memory-server/jest`):
 - `readJestGlobalUri(options?)`
 
 Nest export (`@jongodb/memory-server/nestjs`):
-
 - `registerJongodbForNestJest(hooks, options?)`
 
 Vitest export (`@jongodb/memory-server/vitest`):
-
 - `registerJongodbForVitest(hooks, options?)`
 
 ## Options Reference
 
-Core options:
-
+Core:
 - `launchMode`: `auto` | `binary` | `java` (default: `auto`)
-- `binaryPath`: binary executable path
+- `binaryPath`: binary executable override path
 - `classpath`: Java classpath string or string array
 - `javaPath`: Java executable path (default: `java`)
 - `launcherClass`: Java launcher class (default: `org.jongodb.server.TcpMongoServerLauncher`)
-- `databaseName`: default DB in generated URI (default: `test`)
+- `databaseName`: base DB name (default: `test`)
+- `databaseNameSuffix`: suffix appended to `databaseName` (example: `_ci`)
+- `databaseNameStrategy`: `static` | `worker` (default: `static`)
 - `host`: bind host (default: `127.0.0.1`)
-- `port`: bind port (`0` for ephemeral, default: `0`)
+- `port`: bind port (`0` means ephemeral)
 - `startupTimeoutMs`: startup timeout (default: `15000`)
 - `stopTimeoutMs`: stop timeout before forced kill (default: `5000`)
-- `env`: additional child process env vars
+- `env`: extra child process environment variables
 - `logLevel`: `silent` | `info` | `debug` (default: `silent`)
-- `envVarName` (runtime/jest/vitest helpers): target env key (default: `MONGODB_URI`)
+
+Runtime helper options:
+- `envVarName`: single target env key (default: `MONGODB_URI`)
+- `envVarNames`: multiple target env keys (example: `["MONGODB_URI", "DATABASE_URL"]`)
 
 ## Troubleshooting
 
-- `No launcher runtime configured`: set binary path/env or classpath/env
+- `No launcher runtime configured`: set `binaryPath` / `JONGODB_BINARY_PATH` / `classpath` / `JONGODB_CLASSPATH`
 - `Binary launch mode requested but no binary was found`: provide `binaryPath` or `JONGODB_BINARY_PATH`
 - `Java launch mode requested but Java classpath is not configured`: provide `classpath` or `JONGODB_CLASSPATH`
-- `spawn ... ENOENT`: missing binary/java executable path
+- `spawn ... ENOENT`: missing runtime executable path
 - startup timeout: launcher did not emit `JONGODB_URI=...`
 
 Parallel test tip:
-
-- use unique `databaseName` per worker/process to avoid data collisions
+- use `databaseNameStrategy: "worker"` or per-worker suffixes to prevent data collisions