@c9up/atlas 0.1.3

package/src/schema/Seeder.ts

@@ -0,0 +1,132 @@
+/**
+ * Seeder — populate the database with default / reference / test data.
+ *
+ * The canonical pattern:
+ *
+ *     export default class CountrySeeder extends BaseSeeder {
+ *       async run() {
+ *         // Idempotent via updateOrCreateMany — safe to re-run.
+ *         await Country.updateOrCreateMany('isoCode', [
+ *           { isoCode: 'FR', name: 'France' },
+ *           { isoCode: 'IN', name: 'India' },
+ *         ])
+ *       }
+ *     }
+ *
+ * @implements MISS-4, Story 32.12
+ */
+
+import * as fsp from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import type { DatabaseConnection } from "../BaseRepository.js";
+import { AtlasError } from "../errors.js";
+import {
+	assertPathInsideBase,
+	assertSafeName,
+	pathExists,
+} from "../utils/safePath.js";
+
+/**
+ * Base class for all seeders.
+ *
+ * Subclasses receive the database connection via the constructor so they can
+ * build repositories inside `run()` without resorting to globals.
+ */
+export abstract class BaseSeeder {
+	protected db: DatabaseConnection;
+
+	constructor(db: DatabaseConnection) {
+		this.db = db;
+	}
+
+	/** The seeder body. Should be idempotent — `updateOrCreateMany` is the recommended pattern. */
+	abstract run(): Promise<void> | void;
+}
+
+/** Legacy alias kept for code using the previous API. */
+export const Seeder = BaseSeeder;
+
+/**
+ * Run a pre-built list of seeder INSTANCES in order. Each `run()` is awaited
+ * sequentially so ordering is deterministic and side effects are visible to
+ * subsequent seeders.
+ */
+export async function runSeeders(
+	seeders: BaseSeeder[],
+	_db?: DatabaseConnection,
+): Promise<void> {
+	for (const seeder of seeders) {
+		await seeder.run();
+	}
+}
+
+/**
+ * Discover seeder files under `dir`, import them in alphabetical order, build
+ * instances with the given DB connection, and run them sequentially.
+ *
+ * Usage: `await runSeederDirectory('./database/seeders', db)`
+ *
+ * @param dir      Directory containing `.ts` / `.js` seeder files
+ * @param db       Database connection passed to each seeder constructor
+ * @param options  Optional filter (`files: ['CountrySeeder']`) to run a subset
+ *
+ * @implements Story 32.12
+ */
+export async function runSeederDirectory(
+	dir: string,
+	db: DatabaseConnection,
+	options?: { files?: readonly string[] },
+): Promise<string[]> {
+	if (!(await pathExists(dir))) {
+		throw new AtlasError(
+			"E_SEEDER_DIR_NOT_FOUND",
+			`Seeder directory not found: ${dir}`,
+			{
+				hint: "Create the directory or adjust the path passed to runSeederDirectory.",
+			},
+		);
+	}
+
+	const allFiles = (await fsp.readdir(dir))
+		.filter(
+			(f) => (f.endsWith(".ts") || f.endsWith(".js")) && !f.endsWith(".d.ts"),
+		)
+		.sort();
+
+	const selected = options?.files
+		? allFiles.filter((f) =>
+				options.files?.includes(f.replace(/\.(ts|js)$/, "")),
+			)
+		: allFiles;
+
+	const executed: string[] = [];
+	for (const file of selected) {
+		assertSafeName(file, "E_SEEDER_INVALID", "seeder");
+		const resolved = assertPathInsideBase(
+			dir,
+			file,
+			"E_SEEDER_INVALID_PATH",
+			"Seeder",
+		);
+
+		// `pathToFileURL` is required on Windows where bare `C:\…` paths
+		// trip ESM's ERR_UNSUPPORTED_ESM_URL_SCHEME on dynamic import.
+		const mod = await import(pathToFileURL(resolved).href);
+		const SeederClass = mod.default;
+		if (!SeederClass || typeof SeederClass !== "function") {
+			throw new AtlasError(
+				"E_SEEDER_INVALID",
+				`Seeder ${file} must export a default class extending BaseSeeder`,
+				{
+					hint: "Example: `export default class UserSeeder extends BaseSeeder { async run() { ... } }`",
+				},
+			);
+		}
+
+		const instance: BaseSeeder = new SeederClass(db);
+		await instance.run();
+		executed.push(file.replace(/\.(ts|js)$/, ""));
+	}
+
+	return executed;
+}

package/src/schema/TableBuilder.ts

@@ -0,0 +1,238 @@
+/**
+ * TableBuilder — fluent column/index builder used inside `Schema.createTable()`.
+ *
+ * Builds an in-memory column/index spec, then delegates SQL generation to the
+ * Rust compiler via `compileStatementNative`. No SQL strings are produced in TS.
+ *
+ * @implements FR34
+ */
+
+import {
+	type AtlasDialect,
+	compileStatementNative,
+	getAtlasDialect,
+} from "../query/native.js";
+import {
+	type ColumnDefinition,
+	type ColumnType,
+	type IndexDefinition,
+	TYPE_KIND_MAP,
+} from "./types.js";
+
+/** Table builder — used inside `schema.createTable(name, callback)`. */
+export class TableBuilder {
+	readonly tableName: string;
+	#columns: ColumnDefinition[] = [];
+	#indexes: IndexDefinition[] = [];
+	#currentColumn?: ColumnDefinition;
+
+	constructor(tableName: string) {
+		this.tableName = tableName;
+	}
+
+	// ─── Column types ─────────────────────────────────────────
+
+	uuid(name: string): this {
+		return this.#addColumn(name, "uuid");
+	}
+
+	string(name: string, length = 255): this {
+		this.#addColumn(name, "string");
+		if (this.#currentColumn) this.#currentColumn.length = length;
+		return this;
+	}
+
+	text(name: string): this {
+		return this.#addColumn(name, "text");
+	}
+	integer(name: string): this {
+		return this.#addColumn(name, "integer");
+	}
+	bigInteger(name: string): this {
+		return this.#addColumn(name, "bigInteger");
+	}
+
+	decimal(name: string, precision = 10, scale = 2): this {
+		this.#addColumn(name, "decimal");
+		if (this.#currentColumn) {
+			this.#currentColumn.precision = precision;
+			this.#currentColumn.scale = scale;
+		}
+		return this;
+	}
+
+	boolean(name: string): this {
+		return this.#addColumn(name, "boolean");
+	}
+	date(name: string): this {
+		return this.#addColumn(name, "date");
+	}
+	timestamp(name: string): this {
+		return this.#addColumn(name, "timestamp");
+	}
+	json(name: string): this {
+		return this.#addColumn(name, "json");
+	}
+	binary(name: string): this {
+		return this.#addColumn(name, "binary");
+	}
+
+	// ─── Shortcuts ────────────────────────────────────────────
+
+	/**
+	 * UUID primary key with Postgres-only `gen_random_uuid()` default.
+	 *
+	 * **Portability warning — DO NOT use in framework-shipped migration templates.**
+	 *
+	 * `gen_random_uuid()` is a Postgres-13+ built-in. SQLite and MySQL do NOT
+	 * provide a function by that name; calling `id()` in a migration that
+	 * runs on those dialects fails at `migrations:run` with a "no such
+	 * function" error. The helper is retained for user-app migrations where
+	 * the target dialect is known to be Postgres.
+	 *
+	 * In framework-shipped templates, write the column explicitly and supply
+	 * the UUID at INSERT time:
+	 *
+	 *     t.uuid('id').primary()                  // no DEFAULT
+	 *     // and at insert: db.insert({ id: crypto.randomUUID(), ... })
+	 *
+	 * See `AUDIT-migration-templates.md` (shipped at the package root) for
+	 * the full audit and the escape-hatch procedure if a future story makes
+	 * the helper dialect-aware.
+	 */
+	id(): this {
+		return this.uuid("id").primary().defaultTo("gen_random_uuid()");
+	}
+
+	/**
+	 * `created_at` + `updated_at` columns with Postgres-only `DEFAULT NOW()`.
+	 *
+	 * **Portability warning — DO NOT use in framework-shipped migration templates.**
+	 *
+	 * `NOW()` is a Postgres/MySQL function — SQLite does NOT recognise it
+	 * (SQLite accepts `CURRENT_TIMESTAMP`, not `NOW()`). Calling
+	 * `timestamps()` in a migration that runs on SQLite fails at
+	 * `migrations:run` with a "no such function" error. The helper is
+	 * retained for user-app migrations where the target dialect is known to
+	 * be Postgres or MySQL.
+	 *
+	 * In framework-shipped templates, write the columns explicitly without a
+	 * DEFAULT and supply the value at INSERT/UPSERT time:
+	 *
+	 *     t.timestamp('created_at').notNullable()  // no DEFAULT
+	 *     t.timestamp('updated_at').notNullable()
+	 *     // and at insert: db.insert({ created_at: new Date().toISOString(), ... })
+	 *
+	 * See `AUDIT-migration-templates.md` (shipped at the package root) for
+	 * the full audit and the escape-hatch procedure if a future story makes
+	 * the helper dialect-aware.
+	 */
+	timestamps(): this {
+		this.timestamp("created_at").notNullable().defaultTo("NOW()");
+		this.timestamp("updated_at").notNullable().defaultTo("NOW()");
+		return this;
+	}
+
+	// ─── Column modifiers ─────────────────────────────────────
+
+	primary(): this {
+		if (this.#currentColumn) this.#currentColumn.primary = true;
+		return this;
+	}
+
+	notNullable(): this {
+		if (this.#currentColumn) this.#currentColumn.nullable = false;
+		return this;
+	}
+
+	nullable(): this {
+		if (this.#currentColumn) this.#currentColumn.nullable = true;
+		return this;
+	}
+
+	unique(): this {
+		if (this.#currentColumn) this.#currentColumn.unique = true;
+		return this;
+	}
+
+	defaultTo(value: string): this {
+		if (this.#currentColumn) this.#currentColumn.defaultValue = value;
+		return this;
+	}
+
+	references(table: string, column = "id"): this {
+		if (this.#currentColumn) this.#currentColumn.references = { table, column };
+		return this;
+	}
+
+	// ─── Indexes ──────────────────────────────────────────────
+
+	index(columns: string | string[], name?: string): this {
+		const cols = Array.isArray(columns) ? columns : [columns];
+		this.#indexes.push({
+			name: name ?? `idx_${this.tableName}_${cols.join("_")}`,
+			columns: cols,
+			unique: false,
+		});
+		return this;
+	}
+
+	uniqueIndex(columns: string | string[], name?: string): this {
+		const cols = Array.isArray(columns) ? columns : [columns];
+		this.#indexes.push({
+			name: name ?? `idx_${this.tableName}_${cols.join("_")}_unique`,
+			columns: cols,
+			unique: true,
+		});
+		return this;
+	}
+
+	// ─── Accessors ────────────────────────────────────────────
+
+	getColumns(): ColumnDefinition[] {
+		return [...this.#columns];
+	}
+	getIndexes(): IndexDefinition[] {
+		return [...this.#indexes];
+	}
+
+	/** Compile to SQL statements via the Rust compiler. */
+	toStatements(dialect: AtlasDialect = getAtlasDialect()): string[] {
+		const spec = {
+			kind: "createTable",
+			table: this.tableName,
+			columns: this.#columns.map((c) => ({
+				name: c.name,
+				kind: TYPE_KIND_MAP[c.type],
+				length: c.length ?? null,
+				precision: c.precision ?? null,
+				scale: c.scale ?? null,
+				nullable: c.nullable,
+				primary: c.primary,
+				unique: c.unique,
+				default: c.defaultValue ?? null,
+				references: c.references ?? null,
+			})),
+			indexes: this.#indexes.map((i) => ({
+				name: i.name,
+				columns: i.columns,
+				unique: i.unique,
+			})),
+			ifNotExists: false,
+		};
+		return compileStatementNative(spec, dialect).statements;
+	}
+
+	#addColumn(name: string, type: ColumnType): this {
+		const col: ColumnDefinition = {
+			name,
+			type,
+			nullable: true,
+			primary: false,
+			unique: false,
+		};
+		this.#columns.push(col);
+		this.#currentColumn = col;
+		return this;
+	}
+}

package/src/schema/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared schema types — column type names, definitions, and the
+ * mapping from logical TS types to the Rust ColumnTypeKind.
+ */
+
+export type ColumnType =
+	| "string"
+	| "text"
+	| "integer"
+	| "bigInteger"
+	| "decimal"
+	| "boolean"
+	| "date"
+	| "timestamp"
+	| "uuid"
+	| "json"
+	| "binary";
+
+/** Maps our logical type names to the ColumnTypeKind expected by the Rust compiler. */
+export const TYPE_KIND_MAP: Record<ColumnType, string> = {
+	string: "string",
+	text: "text",
+	integer: "integer",
+	bigInteger: "bigInteger",
+	decimal: "decimal",
+	boolean: "boolean",
+	date: "date",
+	timestamp: "timestamp",
+	uuid: "uuid",
+	json: "json",
+	binary: "binary",
+};
+
+export interface ColumnDefinition {
+	name: string;
+	type: ColumnType;
+	length?: number;
+	precision?: number;
+	scale?: number;
+	nullable: boolean;
+	primary: boolean;
+	unique: boolean;
+	defaultValue?: string;
+	references?: { table: string; column: string };
+}
+
+export interface IndexDefinition {
+	name: string;
+	columns: string[];
+	unique: boolean;
+}

package/src/services/db.ts

@@ -0,0 +1,45 @@
+/**
+ * Default `db` singleton — Adonis Lucid–style ergonomic access to the
+ * configured database connection.
+ *
+ *   import db from '@c9up/atlas/services/db'
+ *
+ *   const rows = await db.query('SELECT * FROM users WHERE id = ?', [id])
+ *
+ * Populated by `AtlasProvider.boot()`. The instance is whatever the
+ * `database.connections[default]` config block resolves to (typically
+ * a `NapiDbAdapter` wrapping the Rust sqlite driver, but apps can
+ * swap in a custom `AsyncDatabaseConnection` through the provider's
+ * container hooks).
+ */
+
+import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+
+let instance: AsyncDatabaseConnection | undefined;
+
+/** @internal Bind the singleton (called by AtlasProvider). */
+export function setDb(connection: AsyncDatabaseConnection): void {
+	instance = connection;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getDb(): AsyncDatabaseConnection | undefined {
+	return instance;
+}
+
+const db: AsyncDatabaseConnection = new Proxy({} as AsyncDatabaseConnection, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[atlas] db singleton accessed before AtlasProvider.boot() ran. " +
+					"Check that `@c9up/atlas/provider` is listed in your reamrc.ts " +
+					"providers and that `config/database.ts` defines at least one " +
+					"connection.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default db;

package/src/testing/DatabaseCleanup.ts

@@ -0,0 +1,49 @@
+/**
+ * Database cleanup utilities for testing.
+ *
+ * @implements MISS-19
+ */
+
+import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import { compileStatementNative, getAtlasDialect } from "../query/native.js";
+
+/**
+ * Wrap a test in a savepoint that is rolled back after.
+ */
+export async function useTransaction(
+	db: AsyncDatabaseConnection,
+): Promise<() => Promise<void>> {
+	await db.execute("SAVEPOINT test_savepoint");
+	return async () => {
+		await db.execute("ROLLBACK TO SAVEPOINT test_savepoint");
+		await db.execute("RELEASE SAVEPOINT test_savepoint");
+	};
+}
+
+/**
+ * Truncate all user tables (excludes _migrations and internal tables).
+ *
+ * The SELECT on `sqlite_master` is SQLite-specific introspection and is kept
+ * as raw SQL intentionally — it's not a user query. The resulting DELETEs
+ * go through the Rust compiler.
+ */
+export async function truncateAll(db: AsyncDatabaseConnection): Promise<void> {
+	// SQL LIKE `_` is a single-char wildcard, not a literal underscore.
+	// `NOT LIKE '_%'` without `ESCAPE` matches NOTHING (every non-empty name
+	// matches `_%`). The `ESCAPE '\'` clause makes `\_` a literal underscore,
+	// so the exclusion targets only names starting with `_` (the convention
+	// for framework-private tables, including `_migrations`).
+	const tables = await db.query(
+		"SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '\\_%' ESCAPE '\\' AND name NOT LIKE 'sqlite_%'",
+	);
+	const dialect = getAtlasDialect();
+	for (const row of tables) {
+		const name = row.name;
+		if (typeof name !== "string") continue;
+		const compiled = compileStatementNative(
+			{ kind: "delete", table: name, wheres: [] },
+			dialect,
+		);
+		await db.execute(compiled.statements[0], compiled.params);
+	}
+}

package/src/testing/Factory.ts

@@ -0,0 +1,164 @@
+/**
+ * Model Factory — Lucid-compatible factory surface for generating test data.
+ *
+ * Supports named states (variations), relations (nested `with`), many-to-many
+ * pivot attributes, stubbing (build without persisting), and ad-hoc merges.
+ *
+ *     const UserFactory = factory(User, () => ({ email: `user-${Date.now()}@test.com`, name: 'Test' }))
+ *       .state('admin', (u) => { u.role = 'admin' })
+ *
+ *     const user = await UserFactory.create(db)
+ *     const users = await UserFactory.apply('admin').createMany(5, db)
+ *     const draft = UserFactory.merge({ name: 'Alice' }).makeStubbed()
+ *
+ * @implements MISS-18, Story 32.13
+ */
+
+import type { BaseEntity } from "../BaseEntity.js";
+import { BaseRepository, type DatabaseConnection } from "../BaseRepository.js";
+
+type EntityConstructor<T extends BaseEntity> = new () => T;
+
+/** A named state — mutates an in-progress data object in place. */
+type StateFn<D> = (data: D) => void;
+
+export interface FactoryBuilder<T extends BaseEntity> {
+	/** Override specific fields for the next call (reset after consumption). */
+	merge(overrides: Partial<Record<string, unknown>>): FactoryBuilder<T>;
+
+	/**
+	 * Declare a named variation of this factory. States are stored on the
+	 * factory itself and don't mutate the caller — `apply()` returns a child
+	 * builder with the state active.
+	 */
+	state(name: string, fn: StateFn<Record<string, unknown>>): FactoryBuilder<T>;
+
+	/**
+	 * Activate one or more declared states for the next call. Multiple applies
+	 * compose (all applied states fire, in order).
+	 */
+	apply(...stateNames: string[]): FactoryBuilder<T>;
+
+	/** Create and persist a single entity (fires lifecycle hooks via `repo.create`). */
+	create(db: DatabaseConnection): Promise<T>;
+
+	/** Create and persist multiple entities (fires hooks per row). */
+	createMany(count: number, db: DatabaseConnection): Promise<T[]>;
+
+	/** Build the data object without persisting and without instantiating an entity. */
+	make(): Record<string, unknown>;
+
+	/** Build multiple data objects without persisting. */
+	makeMany(count: number): Record<string, unknown>[];
+
+	/**
+	 * Build an entity INSTANCE without persisting it (Lucid's `makeStubbed`).
+	 * Useful when you need a `new User()` object but want to avoid the DB.
+	 */
+	makeStubbed(): T;
+}
+
+/**
+ * Define a model factory.
+ *
+ *     const UserFactory = factory(User, () => ({
+ *       email: `user-${Date.now()}@test.com`,
+ *       name: 'Test User',
+ *     }))
+ */
+export function factory<T extends BaseEntity>(
+	entityClass: EntityConstructor<T>,
+	defaults: () => Record<string, unknown>,
+): FactoryBuilder<T> {
+	// Persistent state — lives across calls.
+	const states = new Map<string, StateFn<Record<string, unknown>>>();
+	// Transient state — resets after every `make`/`create`.
+	let pendingOverrides: Partial<Record<string, unknown>> = {};
+	let pendingStates: string[] = [];
+
+	const buildData = (): Record<string, unknown> => {
+		const data: Record<string, unknown> = {
+			...defaults(),
+			...pendingOverrides,
+		};
+		for (const name of pendingStates) {
+			const fn = states.get(name);
+			if (!fn)
+				throw new Error(
+					`Factory state '${name}' is not defined on ${entityClass.name}Factory`,
+				);
+			fn(data);
+		}
+		return data;
+	};
+
+	const resetPending = (): void => {
+		pendingOverrides = {};
+		pendingStates = [];
+	};
+
+	const builder: FactoryBuilder<T> = {
+		merge(overrides) {
+			pendingOverrides = { ...pendingOverrides, ...overrides };
+			return builder;
+		},
+
+		state(name, fn) {
+			states.set(name, fn);
+			return builder;
+		},
+
+		apply(...names) {
+			pendingStates.push(...names);
+			return builder;
+		},
+
+		make() {
+			const data = buildData();
+			resetPending();
+			return data;
+		},
+
+		makeMany(count) {
+			// Re-evaluate defaults for each row so `Date.now()` / faker generate distinct values.
+			const rows: Record<string, unknown>[] = [];
+			const capturedOverrides = pendingOverrides;
+			const capturedStates = pendingStates;
+			for (let i = 0; i < count; i++) {
+				pendingOverrides = capturedOverrides;
+				pendingStates = capturedStates;
+				rows.push(buildData());
+			}
+			resetPending();
+			return rows;
+		},
+
+		makeStubbed() {
+			const data = buildData();
+			resetPending();
+			const entity = new entityClass();
+			for (const [key, value] of Object.entries(data)) {
+				entity.setProp(key, value);
+			}
+			return entity;
+		},
+
+		async create(db) {
+			const data = builder.make();
+			const repo = new BaseRepository(entityClass, db);
+			return repo.create(data);
+		},
+
+		async createMany(count, db) {
+			const rows = builder.makeMany(count);
+			const repo = new BaseRepository(entityClass, db);
+			const created: T[] = [];
+			for (const data of rows) {
+				created.push(await repo.create(data));
+			}
+			return created;
+		},
+	};
+
+	return builder;
+}