@classytic/arc-testkit 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,65 @@
+# @classytic/arc-testkit
+
+> Boot a real [`@classytic/arc`](https://www.npmjs.com/package/@classytic/arc) app around the module(s) under test, on a real (in-memory) database.
+
+The ecosystem's contributor contract for the `@classytic/arc-*` module fleet: **if your module boots green here, it composes into any arc host.**
+
+## Install
+
+```bash
+npm i -D @classytic/arc-testkit @classytic/mongokit mongodb-memory-server
+```
+
+`@classytic/mongokit` + `mongodb-memory-server` are **optional peers** — needed only for the default backend, and dynamically imported so they never enter a production bundle. Pass your own `backend` to skip them entirely.
+
+## Usage
+
+```ts
+import { bootModuleApp } from '@classytic/arc-testkit';
+import { createAccountingModule } from '@classytic/arc-accounting';
+
+const t = await bootModuleApp(({ connection }) => [
+  createAccountingModule({ connection, permissions }),
+]);
+
+const res = await t.app.inject({ method: 'GET', url: '/accounting/accounts' });
+expect(res.statusCode).toBe(200);
+
+await t.close();
+```
+
+The module input is a factory receiving `{ connection, mongoUri }` (or a plain module / array). It boots arc with `preset: 'testing'`, `auth: false` — override via `options.app`.
+
+## Transactions
+
+Modules that open multi-document transactions need a replica set:
+
+```ts
+const t = await bootModuleApp(({ connection }) => [createReservationModule({ connection, permissions })],
+  { replset: true });
+```
+
+## Bring your own backend
+
+The default backend is `mongoMemoryBackend()` from `@classytic/mongokit/testkit`. Override it to point at a shared server, a real Atlas cluster, or a different kit's backend — anything that satisfies the `TestBackend` shape (`setup() → { ctx: { connection, uri }, teardown }`):
+
+```ts
+import { mongoMemoryBackend } from '@classytic/mongokit/testkit';
+
+const t = await bootModuleApp(mods, {
+  backend: mongoMemoryBackend({ uri: process.env.ATLAS_TEST_URI }), // real cluster
+});
+```
+
+## API
+
+| Export | |
+| --- | --- |
+| `bootModuleApp(modules, options?)` | boot arc around modules on a backend; returns `{ app, connection, mongoUri, close }` |
+| `TestBackend` | the backend seam — `setup() → { ctx: { connection, uri }, teardown }` |
+| `TestkitContext` | what a module factory receives: `{ connection, mongoUri }` |
+| `BootModuleAppOptions` | `{ replset?, app?, backend? }` |
+
+## License
+
+MIT © Classytic

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+import { BootModuleAppOptions as BootModuleAppOptions$1, BootModulesInput, ModuleTestApp as ModuleTestApp$1, TestkitContext as TestkitContext$1 } from "@classytic/arc/testing";
+import { Connection } from "mongoose";
+//#region src/index.d.ts
+type TestkitContext = TestkitContext$1<Connection>;
+type ModulesInput = BootModulesInput<Connection>;
+type BootModuleAppOptions = BootModuleAppOptions$1<Connection>;
+type ModuleTestApp = ModuleTestApp$1<Connection>;
+declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;
+//#endregion
+export { BootModuleAppOptions, ModuleTestApp, ModulesInput, TestkitContext, bootModuleApp };

package/dist/index.mjs

@@ -0,0 +1,27 @@
+import { bootModuleApp as bootModuleApp$1 } from "@classytic/arc/testing";
+//#region src/index.ts
+/**
+* @classytic/arc-testkit — boots a REAL arc app around the module(s) under
+* test on in-memory MongoDB. The contributor contract: if your module boots
+* green here, it composes into any arc vertical.
+*
+*   const t = await bootModuleApp(({ connection }) => [
+*     createAccountingModule({ connection, country, permissions }),
+*   ]);
+*   const res = await t.app.inject({ method: 'GET', url: '/accounting/accounts' });
+*   const engine = t.exports<AccountingEngine>('accounting'); // typed module export
+*   await t.close();
+*
+* Since arc 2.22 the harness itself lives in `@classytic/arc/testing`
+* (upstreamed from this package — default-connection ownership, boot-failure
+* cleanup, idempotent close, the typed `exports()` accessor, `sensible: false`
+* and all). This package is now the MONGO-TYPED face of it: arc core stays
+* DB-agnostic (`connection: unknown` generic), the module fleet is Mongoose —
+* the wrapper pins `TConn = Connection` once so every module test gets a typed
+* connection with zero casts.
+*/
+function bootModuleApp(modules, options = {}) {
+	return bootModuleApp$1(modules, options);
+}
+//#endregion
+export { bootModuleApp };

package/package.json

@@ -1,40 +1,55 @@
 {
   "name": "@classytic/arc-testkit",
-  "version": "0.1.1",
-  "description": "Test harness for @classytic arc modules — boots a real arc app around the module under test on in-memory MongoDB. If your module boots green here, it composes.",
+  "version": "0.2.0",
+  "description": "Boot a real @classytic/arc app around the module(s) under test on in-memory MongoDB — the ecosystem test harness. Thin Mongo-typed wrapper over @classytic/arc/testing (arc 2.22+). If your arc module boots green here, it composes into any arc host.",
   "type": "module",
-  "license": "UNLICENSED",
-  "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
   },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
   "files": [
     "dist",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+    "test": "vitest run --root ../.. packages/arc-testkit/tests",
+    "lint": "biome check src/",
+    "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
   },
   "dependencies": {
-    "mongodb-memory-server": "^10.2.3"
+    "mongodb-memory-server": ">=10.0.0"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.20.0",
+    "@classytic/arc": ">=2.23.0",
     "mongoose": ">=9.4.1"
   },
-  "devDependencies": {
-    "@classytic/arc": "^2.20.0",
-    "@types/node": "^24.3.0",
-    "mongoose": "^9.7.2",
-    "tsdown": "^0.14.2",
-    "typescript": "^5.8.2",
-    "fastify": "^5.8.4"
+  "keywords": [
+    "arc",
+    "fastify",
+    "testing",
+    "test-harness",
+    "mongodb",
+    "in-memory",
+    "classytic"
+  ],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/arc-ecosystem.git",
+    "directory": "packages/arc-testkit"
   }
 }

package/dist/index-C0gS_j5G.d.ts

@@ -1,29 +0,0 @@
-import { Connection } from "mongoose";
-import { ArcModuleInput, CreateAppOptions } from "@classytic/arc/factory";
-import { FastifyInstance } from "fastify";
-
-//#region src/index.d.ts
-interface TestkitContext {
-  connection: Connection;
-  mongoUri: string;
-}
-type ModulesInput = ArcModuleInput | readonly ArcModuleInput[] | ((ctx: TestkitContext) => ArcModuleInput | readonly ArcModuleInput[]);
-interface BootModuleAppOptions {
-  /**
-   * Use a single-node replica set instead of a standalone mongod. Required
-   * when the domain under test uses multi-document transactions.
-   */
-  replset?: boolean;
-  /** Merged over the testkit defaults (`preset: 'testing'`, `auth: false`). */
-  app?: Partial<CreateAppOptions>;
-}
-interface ModuleTestApp {
-  app: FastifyInstance;
-  connection: Connection;
-  mongoUri: string;
-  /** Close app → disconnect mongoose → stop the in-memory server. Idempotent. */
-  close(): Promise<void>;
-}
-declare function bootModuleApp(modules: ModulesInput, options?: BootModuleAppOptions): Promise<ModuleTestApp>;
-//#endregion
-export { BootModuleAppOptions, ModuleTestApp, ModulesInput, TestkitContext, bootModuleApp };

package/dist/index.js

@@ -1,62 +0,0 @@
-import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
-import mongoose from "mongoose";
-import { createApp } from "@classytic/arc/factory";
-//#region src/index.ts
-/**
-* @classytic/spine-testkit — boots a REAL arc app around the module(s) under
-* test on in-memory MongoDB (the Next.js `nextTestSetup` fixture-app pattern,
-* backend-shaped). The contributor contract: if your module boots green here,
-* it composes into any arc vertical.
-*
-*   const t = await bootModuleApp(({ connection }) => [
-*     createAccountingModule({ connection, country, permissions }),
-*   ]);
-*   const res = await t.app.inject({ method: 'GET', url: '/accounting/accounts' });
-*   await t.close();
-*
-* Modules usually need the live DB connection in their deps, so the primary
-* input is a FACTORY receiving `{ connection, mongoUri }` — mirroring the
-* AppContext convention (wiki/modules.md). Plain module lists also accepted.
-*/
-async function bootModuleApp(modules, options = {}) {
-	const server = options.replset ? await MongoMemoryReplSet.create({ replSet: { count: 1 } }) : await MongoMemoryServer.create();
-	const mongoUri = server.getUri();
-	if (mongoose.connection.readyState !== 0) await mongoose.disconnect();
-	await mongoose.connect(mongoUri);
-	const connection = mongoose.connection;
-	const resolved = typeof modules === "function" ? modules({
-		connection,
-		mongoUri
-	}) : modules;
-	const list = Array.isArray(resolved) ? resolved : [resolved];
-	let app;
-	try {
-		app = await createApp({
-			preset: "testing",
-			auth: false,
-			sensible: false,
-			...options.app,
-			modules: list
-		});
-		await app.ready();
-	} catch (err) {
-		await mongoose.disconnect().catch(() => void 0);
-		await server.stop().catch(() => void 0);
-		throw err;
-	}
-	let closed = false;
-	return {
-		app,
-		connection,
-		mongoUri,
-		close: async () => {
-			if (closed) return;
-			closed = true;
-			await app.close().catch(() => void 0);
-			if (mongoose.connection.readyState !== 0) await mongoose.disconnect().catch(() => void 0);
-			await server.stop().catch(() => void 0);
-		}
-	};
-}
-//#endregion
-export { bootModuleApp };