@c9up/atlas 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @c9up/atlas
+
+Data Mapper ORM for Node.js. Entity decorators, fluent QueryBuilder, domain events.
+
+## Usage
+
+```typescript
+import { Entity, Column, PrimaryKey, BaseEntity, QueryBuilder } from '@c9up/atlas'
+
+@Entity('orders')
+class Order extends BaseEntity {
+  @PrimaryKey({ generated: 'uuid' }) declare id: string
+  @Column() declare status: string
+  @Column({ type: 'decimal' }) declare total: number
+}
+
+const { sql, params } = new QueryBuilder('orders')
+  .where('status', 'active')
+  .orderBy('createdAt', 'desc')
+  .paginate(1, 20)
+  .toSQL()
+```
+
+## Features
+
+- `@Entity`, `@Column`, `@PrimaryKey`, `@BelongsTo`, `@HasMany`, `@ManyToMany`
+- Fluent QueryBuilder with parameterized SQL (injection-safe)
+- CTE (`.with()`), UNION, WHERE EXISTS, GROUP BY, HAVING, DISTINCT
+- `RawSql` tagged template for edge cases
+- Domain events accumulated on entities, dispatched after save
+- BaseRepository with query builder access
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@c9up/atlas",
+  "version": "0.1.3",
+  "description": "Atlas — Data Mapper ORM for the Ream framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "AUDIT-migration-templates.md",
+    "LICENSE",
+    "README.md",
+    "db.*.node",
+    "dist",
+    "index.*.node",
+    "scripts",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/AtlasProvider.d.ts",
+      "import": "./dist/AtlasProvider.js"
+    },
+    "./services/db": {
+      "types": "./dist/services/db.d.ts",
+      "import": "./dist/services/db.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "@types/node": "^22"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/atlas.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:rust": "cargo build --release -p atlas-query-napi && cargo build --release -p atlas-db-napi",
+    "build:napi": "pnpm build:rust && node scripts/copy-napi.mjs && node scripts/copy-napi.mjs --basename db",
+    "test": "vitest run",
+    "test:rust": "cargo test -p atlas-query",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/scripts/copy-napi.mjs

@@ -0,0 +1,86 @@
+// Atlas ships TWO NAPI artefacts:
+//   - atlas-query-napi → index.<suffix>.node  (default)
+//   - atlas-db-napi    → db.<suffix>.node     (--basename db)
+//
+// Usage:
+//   node scripts/copy-napi.mjs                  # query → index.<suffix>.node
+//   node scripts/copy-napi.mjs --basename db    # db    → db.<suffix>.node
+
+import { copyFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { argv, arch, env, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+// Cross-compile aware: set CARGO_BUILD_TARGET (e.g. x86_64-apple-darwin on an
+// arm64 runner so we don't depend on the scarce macos-13 Intel runners) and we
+// read target/<triple>/release. Unset = host platform / target/release.
+const tripleMap = {
+  '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 hostSuffixMap = {
+  'linux-x64': 'linux-x64-gnu',
+  'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64',
+  'darwin-arm64': 'darwin-arm64',
+  'win32-x64': 'win32-x64-msvc',
+}
+
+const basenameIdx = argv.indexOf('--basename')
+const basename = basenameIdx >= 0 ? argv[basenameIdx + 1] : 'index'
+if (!basename || basename.startsWith('-')) {
+  throw new Error(`[atlas:napi] --basename requires a value (got: ${basename ?? '<missing>'})`)
+}
+
+const crateMap = {
+  index: 'atlas_query_napi',
+  db: 'atlas_db_napi',
+}
+const crate = crateMap[basename]
+if (!crate) {
+  throw new Error(`[atlas:napi] unknown basename '${basename}'. Expected one of: ${Object.keys(crateMap).join(', ')}`)
+}
+
+const triple = env.CARGO_BUILD_TARGET ?? ''
+let suffix
+let os
+let releaseDir
+if (triple) {
+  const entry = tripleMap[triple]
+  if (!entry) {
+    throw new Error(`[atlas:napi] unsupported CARGO_BUILD_TARGET: ${triple}`)
+  }
+  suffix = entry.suffix
+  os = entry.os
+  releaseDir = join(root, 'target', triple, 'release')
+} else {
+  suffix = hostSuffixMap[`${platform}-${arch}`]
+  os = platform
+  releaseDir = join(root, 'target', 'release')
+  if (!suffix) {
+    throw new Error(`[atlas:napi] unsupported platform/arch: ${platform}-${arch}`)
+  }
+}
+
+const candidates = os === 'win32'
+  ? [join(releaseDir, `${crate}.dll`), join(releaseDir, `lib${crate}.dll`)]
+  : os === 'darwin'
+  ? [join(releaseDir, `lib${crate}.dylib`)]
+  : [join(releaseDir, `lib${crate}.so`)]
+
+const source = candidates.find((candidate) => existsSync(candidate))
+if (!source) {
+  throw new Error(
+    `[atlas:napi] native library not found. Looked for:\n${candidates.map((p) => `- ${p}`).join('\n')}`,
+  )
+}
+
+const target = join(root, `${basename}.${suffix}.node`)
+copyFileSync(source, target)
+console.log(`[atlas:napi] copied ${source} -> ${target}`)

package/src/AtlasProvider.ts

@@ -0,0 +1,297 @@
+/**
+ * AtlasProvider — Ream provider for the Atlas ORM.
+ *
+ * Connects to one or more databases via the Rust ream-db driver
+ * (SQLite/PostgreSQL/MySQL). Runs migrations on boot for the default
+ * connection.
+ *
+ * Multi-connection support (story 32.9):
+ *
+ *     // config/database.ts
+ *     export default {
+ *       default: 'primary',
+ *       connections: {
+ *         primary: { url: 'postgres://.../primary' },
+ *         tenant1: { url: 'postgres://.../tenant1' },
+ *       },
+ *     }
+ *
+ *     // Code
+ *     const primary = app.container.resolve('db')              // default
+ *     const tenant1 = app.container.resolve('db:tenant1')     // named
+ */
+
+import {
+	type AsyncDatabaseConnection,
+	createNapiConnection,
+} from "./adapters/NapiDbAdapter.js";
+import { setAtlasDialect } from "./query/native.js";
+import {
+	type DatabaseAdapter,
+	MigrationRunner,
+} from "./schema/MigrationRunner.js";
+import { dialectFromUrl } from "./utils/dialectFromUrl.js";
+
+/**
+ * Structural slice of the host framework's app context — only the surface
+ * AtlasProvider actually uses. Declared locally so atlas does NOT import
+ * `@c9up/ream`; any framework whose context exposes a `config.get(key)`
+ * reader and a `container.singleton(token, factory)` binder satisfies this
+ * contract via TypeScript structural compatibility.
+ *
+ * The `token` type mirrors ream's `ServiceToken` union (`string | symbol |
+ * ctor`) so AtlasProvider can grow into class-as-token / Symbol-keyed
+ * bindings without re-coupling to `@c9up/ream`. AtlasProvider itself only
+ * uses `string` tokens today.
+ */
+export interface AtlasAppContext {
+	container: {
+		singleton(
+			token: string | symbol | (new (...args: never[]) => unknown),
+			factory: () => unknown,
+		): void;
+	};
+	config: { get<T = unknown>(key: string): T | undefined };
+}
+
+/**
+ * Canonical sqlite production pragma recipe.
+ *
+ *   journal_mode = WAL        // writes go to a side-log, readers don't block
+ *   synchronous  = NORMAL     // one fsync per commit (on the WAL); recovery
+ *                             // still rebuilds a consistent DB after crash
+ *
+ * Drops INSERT latency by ~5–10x vs sqlite's default
+ * (`journal_mode=delete` + `synchronous=FULL`) without sacrificing
+ * durability. Spread the constant into `pragmas` so app-specific overrides
+ * stay literal:
+ *
+ *   pragmas: { ...SQLITE_PROD_PRAGMAS, foreign_keys: "ON" }
+ */
+export const SQLITE_PROD_PRAGMAS = Object.freeze({
+	journal_mode: "WAL",
+	synchronous: "NORMAL",
+} as const);
+
+/** One connection's settings. */
+export interface ConnectionConfig {
+	/** Connection URL: "sqlite:data/app.db", "postgres://...", "mysql://..." */
+	url: string;
+	/** Minimum pool connections (default: 1) */
+	poolMin?: number;
+	/** Maximum pool connections (default: 10) */
+	poolMax?: number;
+	/**
+	 * Connection-level pragmas (sqlite only). Each entry becomes a
+	 * `PRAGMA <key> = <value>;` issued before the first query.
+	 *
+	 * Most apps want `{ journal_mode: "WAL", synchronous: "NORMAL" }` —
+	 * disk-backed, durable, and ~5–10x faster than the default
+	 * `journal_mode=delete` + `synchronous=FULL` (two fsyncs per
+	 * commit). Ignored for postgres / mysql URLs.
+	 */
+	pragmas?: Record<string, string | number>;
+}
+
+/** Full database config — single-connection (legacy) OR multi-connection. */
+export interface AtlasDatabaseConfig extends ConnectionConfig {
+	/** Name of the default connection when `connections` is set. Defaults to `"primary"`. */
+	default?: string;
+	/** Named connections. When present, top-level `url` is treated as `connections[default].url`. */
+	connections?: Record<string, ConnectionConfig>;
+	migrations?: {
+		path?: string;
+		/**
+		 * Custom name for the migrations tracking table. Defaults to `"_migrations"`.
+		 * Must match `/^[A-Za-z_][A-Za-z0-9_]*$/` — the `MigrationRunner` constructor
+		 * throws `AtlasError("MIGRATION_INVALID_TABLE_NAME")` otherwise.
+		 */
+		table?: string;
+	};
+}
+
+export default class AtlasProvider {
+	/** Map of connection name → open connection. Populated at boot. */
+	#connections = new Map<string, AsyncDatabaseConnection>();
+	#defaultName = "primary";
+
+	constructor(protected app: AtlasAppContext) {}
+
+	register() {}
+
+	async boot() {
+		const config = this.app.config.get<AtlasDatabaseConfig>("database");
+		if (!config) return;
+
+		// Normalize: if `connections` is not set, build a single-entry map from top-level config.
+		const { connections, defaultName } = this.#resolveConnections(config);
+		this.#defaultName = defaultName;
+
+		// Open every connection in parallel — multi-database apps with slow-to-
+		// handshake drivers (Postgres over TLS, RDS proxies) previously paid the
+		// sum of the round-trip times on boot; now it's the max.
+		//
+		// `Promise.allSettled` lets us distinguish successes from failures without
+		// losing the already-opened connections. If any connection rejected, we
+		// close every successful one before rethrowing so a partial boot never
+		// leaks pools/sockets.
+		const entries = Object.entries(connections);
+		const results = await Promise.allSettled(
+			entries.map(([, settings]) =>
+				createNapiConnection(
+					settings.url,
+					settings.poolMin ?? 1,
+					settings.poolMax ?? 10,
+					settings.pragmas,
+				),
+			),
+		);
+		const failures: Array<{ name: string; error: unknown }> = [];
+		const successes: Array<{ name: string; conn: AsyncDatabaseConnection }> =
+			[];
+		results.forEach((r, i) => {
+			const [name] = entries[i];
+			if (r.status === "fulfilled") successes.push({ name, conn: r.value });
+			else failures.push({ name, error: r.reason });
+		});
+		if (failures.length > 0) {
+			// Tear down the successes so we don't leak any pool that the runtime
+			// has already opened. Closures run in parallel with allSettled so a
+			// stuck close doesn't block the rollback path.
+			await Promise.allSettled(successes.map((s) => s.conn.close()));
+			const first = failures[0];
+			const others = failures
+				.slice(1)
+				.map((f) => `${f.name}: ${String(f.error)}`)
+				.join("; ");
+			throw new Error(
+				`AtlasProvider: failed to open ${failures.length} connection(s) — ` +
+					`'${first.name}' failed: ${String(first.error)}` +
+					(others ? ` (also: ${others})` : ""),
+			);
+		}
+		for (const { name, conn } of successes) {
+			this.#connections.set(name, conn);
+			this.app.container.singleton(`db:${name}`, () => conn);
+		}
+
+		// Expose the default under the short aliases `db` and `db.connection`.
+		const defaultConn = this.#connections.get(defaultName);
+		if (!defaultConn) {
+			throw new Error(
+				`AtlasProvider: default connection '${defaultName}' is not defined in config.database.connections`,
+			);
+		}
+		this.app.container.singleton("db", () => defaultConn);
+		this.app.container.singleton("db.connection", () => defaultConn);
+
+		// Populate the `@c9up/atlas/services/db` proxy so apps can
+		// `import db from '@c9up/atlas/services/db'` from anywhere.
+		// Done inside the lazy-import to avoid pulling the services
+		// module at construction time when the provider is type-imported
+		// by `@c9up/ream`'s discovery scan.
+		const { setDb } = await import("./services/db.js");
+		setDb(defaultConn);
+
+		// The dialect set module-wide is the DEFAULT connection's dialect.
+		// Per-connection dialect (when a user hits a non-default) is read from
+		// the connection URL at query time by each call site that cares.
+		setAtlasDialect(dialectFromUrl(connections[defaultName]?.url));
+
+		if (config.migrations?.path) {
+			await this.#runMigrations(
+				config.migrations.path,
+				connections[defaultName]?.url,
+				defaultConn,
+				config.migrations.table,
+			);
+		}
+	}
+
+	async shutdown() {
+		// Close every connection in parallel — same reasoning as boot. We use
+		// `allSettled` so a single driver failing to close doesn't prevent the
+		// rest from shutting down, BUT we surface the failures afterwards:
+		//
+		//   - the map is cleared unconditionally (the process is shutting down
+		//     and we don't want to hand out closed handles)
+		//   - any rejection is aggregated into a single `AggregateError` thrown
+		//     at the end so supervisors / health-checks see a non-zero exit
+		//     signal instead of a silent "everything is fine" shutdown
+		const named = [...this.#connections.entries()];
+		const results = await Promise.allSettled(named.map(([, c]) => c.close()));
+		this.#connections.clear();
+		const errors = results
+			.map((r, i) =>
+				r.status === "rejected" ? { name: named[i][0], error: r.reason } : null,
+			)
+			.filter((x): x is { name: string; error: unknown } => x !== null);
+		if (errors.length > 0) {
+			const summary = errors
+				.map((e) => `'${e.name}': ${String(e.error)}`)
+				.join("; ");
+			throw new AggregateError(
+				errors.map((e) => e.error),
+				`AtlasProvider: ${errors.length} connection(s) failed to close — ${summary}`,
+			);
+		}
+	}
+
+	async start() {}
+	async ready() {}
+
+	/** Normalize the config into a `{ name → ConnectionConfig }` map + default name. */
+	#resolveConnections(config: AtlasDatabaseConfig): {
+		connections: Record<string, ConnectionConfig>;
+		defaultName: string;
+	} {
+		if (config.connections && Object.keys(config.connections).length > 0) {
+			return {
+				connections: config.connections,
+				defaultName: config.default ?? "primary",
+			};
+		}
+		// Legacy single-connection shape — promote to multi-connection under "primary".
+		return {
+			connections: {
+				primary: {
+					url: config.url,
+					poolMin: config.poolMin,
+					poolMax: config.poolMax,
+					pragmas: config.pragmas,
+				},
+			},
+			defaultName: "primary",
+		};
+	}
+
+	async #runMigrations(
+		migrationsPath: string,
+		url: string,
+		db: AsyncDatabaseConnection,
+		tableName: string | undefined,
+	): Promise<void> {
+		const { existsSync } = await import("node:fs");
+		if (!existsSync(migrationsPath)) return;
+
+		const adapter: DatabaseAdapter = {
+			execute: async (sql, params) => {
+				await db.execute(sql, params);
+			},
+			query: <T>(sql: string, params?: unknown[]) =>
+				db.query(sql, params) as Promise<T[]>,
+			close: () => db.close(),
+			// Thread the transactional path through so MigrationRunner takes the
+			// atomic branch (a mid-migration failure rolls back both the SQL and the
+			// `_migrations` bookkeeping row together). Without this, the runner
+			// silently falls back to non-transactional execution.
+			runInTransaction: async (batch) => db.runInTransaction(batch),
+		};
+		const runner = new MigrationRunner(adapter, {
+			migrationsDir: migrationsPath,
+			dialect: dialectFromUrl(url),
+			tableName,
+		});
+		await runner.migrate();
+	}
+}