@c9up/atlas 0.1.8 → 0.1.10

package/src/query/native.ts

@@ -56,6 +56,93 @@ export interface CompiledStatement {
 	params: unknown[];
 }
 
+/**
+ * Per-table Postgres cast hints (snake column → logical type, e.g. `uuid`).
+ * Populated once per entity by `BaseRepository` and consulted at the single
+ * compile chokepoint below, so EVERY statement built anywhere (the fluent
+ * `ModelQuery`, relation loaders, direct repo methods) gets `$N::uuid` casts
+ * on its WHERE/SET/value params without threading the cast map through every
+ * call site. Postgres-only at the SQL level; the Rust compiler emits casts
+ * only on the postgres dialect.
+ */
+const castRegistry = new Map<string, Record<string, string>>();
+
+/**
+ * Drop every registered cast. Called by `AtlasProvider.shutdown()` so a re-boot
+ * (tests, hot-reload) starts from a clean registry rather than accumulating casts
+ * across runs — two suites declaring the same table with different column types
+ * would otherwise pollute each other depending on execution order.
+ */
+export function clearCastRegistry(): void {
+	castRegistry.clear();
+}
+
+/**
+ * Register an entity table's cast map (MERGES — a FK cast another entity already
+ * published for this table via `registerColumnCast` survives, regardless of
+ * which repository is constructed first).
+ */
+export function registerTableCasts(
+	table: string,
+	casts: Record<string, string>,
+): void {
+	if (Object.keys(casts).length === 0) return;
+	const existing = castRegistry.get(table);
+	castRegistry.set(table, existing ? { ...existing, ...casts } : { ...casts });
+}
+
+/**
+ * Register a single column's cast on a table. Used by `BaseRepository` to publish
+ * relation FK column types (a FK references a typed PK) onto the OTHER table, so
+ * eager/lazy relation WHEREs on an untyped uuid FK still get `::uuid`.
+ */
+export function registerColumnCast(
+	table: string,
+	column: string,
+	type: string,
+): void {
+	const existing = castRegistry.get(table);
+	if (existing) existing[column] = type;
+	else castRegistry.set(table, { [column]: type });
+}
+
+const CAST_BEARING_KINDS = new Set([
+	"select",
+	"insert",
+	"update",
+	"delete",
+	"upsert",
+]);
+
+/**
+ * Inject the registered cast map for a statement's table. A spec that already
+ * carries explicit `casts` for a NON-registered table (e.g. an m2m pivot insert
+ * with bespoke `pivotCasts`) is left untouched — only entity tables are in the
+ * registry, and their explicit casts are identical to the registered map.
+ */
+function isStringRecord(v: unknown): v is Record<string, string> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function withRegistryCasts(spec: object): object {
+	if (!("table" in spec) || !("kind" in spec)) return spec;
+	const { table, kind } = spec;
+	if (
+		typeof table !== "string" ||
+		typeof kind !== "string" ||
+		!CAST_BEARING_KINDS.has(kind)
+	) {
+		return spec;
+	}
+	const registered = castRegistry.get(table);
+	if (!registered) return spec;
+	// Registered casts are the base; any explicit per-statement casts (e.g. a
+	// relation loader hinting a FK column the related entity didn't type) win.
+	const explicit =
+		"casts" in spec && isStringRecord(spec.casts) ? spec.casts : {};
+	return { ...spec, casts: { ...registered, ...explicit } };
+}
+
 /**
  * Compile any statement (SELECT/INSERT/UPDATE/DELETE/DDL) via the Rust compiler.
  * `spec` is a tagged object: `{ kind: 'select' | 'insert' | ..., ... }`.
@@ -66,9 +153,13 @@ export function compileStatementNative(
 ): CompiledStatement {
 	if (!native) {
 		throw new Error(
-			`[ATLAS_NAPI_NOT_FOUND] Rust query compiler not available: ${loadError ?? "binary not found"}`,
+			"[ATLAS_NAPI_NOT_FOUND] Rust query compiler not available. Build with: cargo build --release",
+			loadError !== undefined ? { cause: loadError } : undefined,
 		);
 	}
-	const json = native.compileStatement(JSON.stringify(spec), dialect);
+	const json = native.compileStatement(
+		JSON.stringify(withRegistryCasts(spec)),
+		dialect,
+	);
 	return JSON.parse(json);
 }

package/src/schema/MigrationRunner.ts

@@ -312,7 +312,10 @@ export class MigrationRunner {
 				table: this.#tableName,
 				select: ["name"],
 				wheres: [{ column: "batch", operator: "=", value: batch, type: "and" }],
-				orderBy: [{ column: "name", direction: "desc" }],
+				// Reverse INSERTION order (auto-increment `id`), not name order — a
+				// date- or hash-prefixed naming scheme would otherwise roll back in
+				// the wrong sequence. `id DESC` is always the inverse of application.
+				orderBy: [{ column: "id", direction: "desc" }],
 				groupBy: [],
 				having: [],
 				limit: null,
@@ -499,7 +502,7 @@ export class MigrationRunner {
 	/** Load and instantiate a migration class. */
 	async #loadMigration(name: string): Promise<Migration> {
 		this.#assertSafeName(name);
-		assertPathInsideBase(
+		await assertPathInsideBase(
 			this.#migrationsDir,
 			`${name}.ts`,
 			"MIGRATION_INVALID",

package/src/schema/Seeder.ts

@@ -1,15 +1,20 @@
 /**
  * Seeder — populate the database with default / reference / test data.
  *
- * The canonical pattern:
+ * The canonical pattern (idempotent via `upsert`, keyed on a unique column):
  *
  *     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' },
- *         ])
+ *         const countries = new BaseRepository(Country, this.db)
+ *         // Conflict on isoCode → update name. Safe to re-run.
+ *         await countries.upsert(
+ *           [
+ *             { isoCode: 'FR', name: 'France' },
+ *             { isoCode: 'IN', name: 'India' },
+ *           ],
+ *           ['isoCode'],
+ *           ['name'],
+ *         )
  *       }
  *     }
  *
@@ -39,7 +44,7 @@ export abstract class BaseSeeder {
 		this.db = db;
 	}
 
-	/** The seeder body. Should be idempotent — `updateOrCreateMany` is the recommended pattern. */
+	/** The seeder body. Should be idempotent — `repo.upsert(...)` is the recommended pattern. */
 	abstract run(): Promise<void> | void;
 }
 
@@ -51,10 +56,7 @@ export const Seeder = BaseSeeder;
  * sequentially so ordering is deterministic and side effects are visible to
  * subsequent seeders.
  */
-export async function runSeeders(
-	seeders: BaseSeeder[],
-	_db?: DatabaseConnection,
-): Promise<void> {
+export async function runSeeders(seeders: BaseSeeder[]): Promise<void> {
 	for (const seeder of seeders) {
 		await seeder.run();
 	}
@@ -102,7 +104,7 @@ export async function runSeederDirectory(
 	const executed: string[] = [];
 	for (const file of selected) {
 		assertSafeName(file, "E_SEEDER_INVALID", "seeder");
-		const resolved = assertPathInsideBase(
+		const resolved = await assertPathInsideBase(
 			dir,
 			file,
 			"E_SEEDER_INVALID_PATH",

package/src/services/db.ts

@@ -22,6 +22,16 @@ export function setDb(connection: AsyncDatabaseConnection): void {
 	instance = connection;
 }
 
+/**
+ * @internal Unbind the singleton IF it still points at `connection` (called by
+ * `AtlasProvider.shutdown()`). Ownership-guarded: when a second provider rebound
+ * the singleton, the older provider's shutdown must not clear the newer binding.
+ * Without this, `db.*` after shutdown would dereference a closed connection.
+ */
+export function clearDb(connection: AsyncDatabaseConnection): void {
+	if (instance === connection) instance = undefined;
+}
+
 /** @internal Read the singleton (or `undefined` pre-boot). */
 export function getDb(): AsyncDatabaseConnection | undefined {
 	return instance;

package/src/testing/Factory.ts

@@ -26,16 +26,15 @@ 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.
-	 */
+	/** Declare a named variation of this factory, stored on the factory's state map. */
 	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).
+	 * Activate one or more declared states for the NEXT build. Multiple applies
+	 * compose (all fire, in order). NOTE: this mutates the builder's shared
+	 * pending state and returns the SAME builder for chaining — there is no
+	 * isolated child builder. The pending set is reset after each make/create
+	 * (audit 2026-06-13). `merge()` behaves the same way.
 	 */
 	apply(...stateNames: string[]): FactoryBuilder<T>;
 
@@ -120,13 +119,11 @@ export function factory<T extends BaseEntity>(
 		},
 
 		makeMany(count) {
-			// Re-evaluate defaults for each row so `Date.now()` / faker generate distinct values.
+			// Re-evaluate defaults for each row so `Date.now()` / faker generate
+			// distinct values. `buildData()` reads (never mutates) the pending
+			// overrides/states, so they stay stable across iterations on their own.
 			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();

package/src/utils/safePath.ts

@@ -40,13 +40,19 @@ export function assertSafeName(
  * Resolve `fileName` inside `baseDir` and throw if the resulting path escapes
  * the base — guards against symlink / `../` traversal attacks when loading
  * migration or seeder files dynamically.
+ *
+ * Two layers: (1) a logical `path.resolve` check that catches `../` walks, and
+ * (2) a `realpath` check that follows symlinks — a symlink FILE sitting inside
+ * the base but pointing at `/etc/passwd` passes the logical check yet is caught
+ * here. When the file doesn't exist yet (ENOENT), only the logical check
+ * applies and the caller's own existence check produces the not-found error.
  */
-export function assertPathInsideBase(
+export async function assertPathInsideBase(
 	baseDir: string,
 	fileName: string,
 	errorCode: string,
 	kind: string,
-): string {
+): Promise<string> {
 	const resolved = path.resolve(baseDir, fileName);
 	const base = path.resolve(baseDir);
 	if (!resolved.startsWith(base + path.sep) && resolved !== base) {
@@ -55,5 +61,24 @@ export function assertPathInsideBase(
 			`${kind} path escapes directory: ${fileName}`,
 		);
 	}
+	// Symlink-aware check: resolve real targets and re-verify containment.
+	try {
+		const realBase = await fsp.realpath(base);
+		const realResolved = await fsp.realpath(resolved);
+		if (
+			!realResolved.startsWith(realBase + path.sep) &&
+			realResolved !== realBase
+		) {
+			throw new AtlasError(
+				errorCode,
+				`${kind} path escapes directory via symlink: ${fileName}`,
+			);
+		}
+	} catch (err) {
+		// File not yet created — the logical check above stands; let the caller's
+		// existence check report the missing file. Re-throw real traversal errors.
+		if (err instanceof AtlasError) throw err;
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+	}
 	return resolved;
 }