@c9up/atlas 0.1.9 → 0.1.10

package/src/ModelQuery.ts

@@ -10,12 +10,14 @@
 import type { BaseEntity } from "./BaseEntity.js";
 import type { DatabaseConnection } from "./BaseRepository.js";
 import {
+	getColumnMetadata,
 	getEntityMetadata,
 	getPrimaryKey,
 	getRelationMetadata,
 	hasSoftDeletes,
 	type RelationMetadata,
 } from "./decorators/entity.js";
+import { fireHooks } from "./decorators/hooks.js";
 import {
 	type AtlasDialect,
 	compileStatementNative,
@@ -937,11 +939,15 @@ export class ModelQuery<T extends BaseEntity> {
 		return this;
 	}
 
-	/** Execute and return the first matching entity or null. */
+	/** Execute and return the first matching entity or null. Fires beforeFind/afterFind. */
 	async first(): Promise<T | null> {
 		this.#limit = 1;
-		const results = await this.exec();
-		return results[0] ?? null;
+		await fireHooks(this.#entityClass, "beforeFind", this);
+		// Bypass exec() so the multi-row beforeFetch/afterFetch hooks don't ALSO
+		// fire — first() is the single-row terminal and owns beforeFind/afterFind.
+		const result = (await this.#doExec())[0] ?? null;
+		await fireHooks(this.#entityClass, "afterFind", result);
+		return result;
 	}
 
 	/** Execute and return the first matching entity or throw. */
@@ -1035,12 +1041,19 @@ export class ModelQuery<T extends BaseEntity> {
 	 */
 	#cachedExec?: Promise<T[]>;
 
-	/** Execute and return all matching entities, with preloaded relations. */
+	/** Execute and return all matching entities, with preloaded relations. Fires beforeFetch/afterFetch. */
 	exec(): Promise<T[]> {
-		this.#cachedExec ??= this.#doExec();
+		this.#cachedExec ??= this.#execWithFetchHooks();
 		return this.#cachedExec;
 	}
 
+	async #execWithFetchHooks(): Promise<T[]> {
+		await fireHooks(this.#entityClass, "beforeFetch", this);
+		const results = await this.#doExec();
+		await fireHooks(this.#entityClass, "afterFetch", results);
+		return results;
+	}
+
 	async #doExec(): Promise<T[]> {
 		const { sql, params } = this.toSQL();
 		const rawRows = await this.#db.query<Record<string, unknown>>(sql, params);
@@ -1099,12 +1112,28 @@ export class ModelQuery<T extends BaseEntity> {
 		const relatedMeta = getEntityMetadata(relatedClass);
 		if (!relatedMeta) return null;
 
+		// Resolve row keys against declared column metadata, NOT `in entity` —
+		// entities using Adonis' `declare field: T` pattern have no own-properties
+		// on a freshly constructed instance, so `key in entity` is always false and
+		// every column would be silently dropped. Mirrors `BaseRepository.#hydrate`.
+		const relatedPkName = getPrimaryKey(relatedClass) ?? "id";
+		const validColumns = new Set<string>();
+		for (const col of getColumnMetadata(relatedClass)) {
+			validColumns.add(col.propertyKey);
+			validColumns.add(camelToSnake(col.propertyKey));
+		}
+		validColumns.add(relatedPkName);
+		validColumns.add(camelToSnake(relatedPkName));
+
 		const hydrate = (row: Record<string, unknown>): BaseEntity => {
 			const entity = new relatedClass();
 			for (const [key, value] of Object.entries(row)) {
 				const camelKey = snakeToCamel(key);
-				const targetKey =
-					camelKey in entity ? camelKey : key in entity ? key : null;
+				const targetKey = validColumns.has(camelKey)
+					? camelKey
+					: validColumns.has(key)
+						? key
+						: null;
 				if (targetKey !== null) entity.setProp(targetKey, value);
 			}
 			return entity;
@@ -1351,12 +1380,14 @@ export class ModelQuery<T extends BaseEntity> {
 			);
 		}
 		const pivot = ctx.relation.pivot;
+		// Default pivot FK = `<model_snake>_id`, derived from the entity CLASS name
+		// (singular by convention), consistent with hasMany/hasOne/belongsTo. Do NOT
+		// singularize the plural TABLE name by stripping a trailing `s` — that breaks
+		// on `status`/`address`/`campus` (→ `statu_id`). Explicit pivot keys win.
 		const foreignKey =
-			pivot.foreignKey ??
-			`${camelToSnake(this.#tableName.replace(/s$/, ""))}_id`;
+			pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 		const otherKey =
-			pivot.otherKey ??
-			`${camelToSnake(ctx.relatedTable.replace(/s$/, ""))}_id`;
+			pivot.otherKey ?? `${camelToSnake(ctx.relatedClass.name)}_id`;
 		const pk = getPrimaryKey(this.#entityClass) ?? "id";
 
 		const ids = entities.map((e) => e[pk]).filter((v) => v != null);
@@ -1576,12 +1607,12 @@ export class ModelQuery<T extends BaseEntity> {
 					);
 				}
 				const pivot = relation.pivot;
+				// Default pivot FK from the CLASS name (singular), not the plural table
+				// name stripped of a trailing `s` — see the eager loader above.
 				const foreignKey =
-					pivot.foreignKey ??
-					`${camelToSnake(parentTable.replace(/s$/, ""))}_id`;
+					pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
 				const otherKey =
-					pivot.otherKey ??
-					`${camelToSnake(relatedTable.replace(/s$/, ""))}_id`;
+					pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
 				const relatedPk = getPrimaryKey(relatedClass) ?? "id";
 				sub.#pushWhereRaw(
 					`${q(relatedTable)}.${q(relatedPk)} IN ` +
@@ -1590,6 +1621,16 @@ export class ModelQuery<T extends BaseEntity> {
 				);
 				break;
 			}
+			default:
+				// hasOneThrough / hasManyThrough build a 2-hop correlated subquery,
+				// which isn't implemented here. Fail loud — falling through would
+				// leave `sub` WITHOUT a join predicate, so whereHas/withCount would
+				// silently match/count EVERY related row.
+				throw new Error(
+					`whereHas/withCount on a '${relation.type}' relation ` +
+						`(${this.#entityClass.name}.${relationName}) is not supported yet. ` +
+						`Use a direct hasMany/belongsTo/manyToMany relation, or filter via a sub-query.`,
+				);
 		}
 		return sub;
 	}
@@ -1802,6 +1843,9 @@ export class ModelQuery<T extends BaseEntity> {
 	async paginate(page: number, perPage: number): Promise<Paginator<T>> {
 		const p = Math.max(1, Math.floor(page));
 		const pp = Math.max(1, Math.floor(perPage));
+		// beforePaginate runs BEFORE cloning so a hook mutating the query (e.g. a
+		// tenant scope) propagates into both the COUNT and the data fetch.
+		await fireHooks(this.#entityClass, "beforePaginate", this);
 		// Parallel COUNT(*) + data fetch
 		const countQ = this.clone();
 		countQ.#select = ["COUNT(*) AS count"];
@@ -1815,7 +1859,10 @@ export class ModelQuery<T extends BaseEntity> {
 		const dataQ = this.clone();
 		dataQ.#limit = pp;
 		dataQ.#offset = (p - 1) * pp;
-		const items = await dataQ.exec();
+		// `#doExec` (not `exec`) so the generic beforeFetch/afterFetch don't fire on
+		// top of the paginate hooks — paginate is its own terminal.
+		const items = await dataQ.#doExec();
+		await fireHooks(this.#entityClass, "afterPaginate", items);
 		return new Paginator<T>(items, { total, perPage: pp, currentPage: p });
 	}
 
@@ -1880,7 +1927,9 @@ export class ModelQuery<T extends BaseEntity> {
 			direction: "asc" as const,
 		}));
 		clone.#limit = lim + 1;
-		const rows = await clone.exec();
+		// `#doExec` (not `exec`) — cursorPaginate is an atlas-specific terminal, not a
+		// Lucid hook point; don't fire the generic beforeFetch/afterFetch on its clone.
+		const rows = await clone.#doExec();
 		const hasMore = rows.length > lim;
 		const items = hasMore ? rows.slice(0, lim) : rows;
 		const last = items[items.length - 1] as Record<string, unknown> | undefined;

package/src/adapters/NapiDbAdapter.ts

@@ -63,12 +63,8 @@ export async function createNapiConnection(
 	poolMax = 10,
 	pragmas?: Record<string, string | number>,
 ): Promise<AsyncDatabaseConnection> {
+	// Throws with the underlying cause if the binary can't be loaded.
 	const native = await loadNativeDb();
-	if (!native) {
-		throw new Error(
-			"[ATLAS] Rust DB driver (atlas-db-napi) not available. Build with: cargo build --release",
-		);
-	}
 
 	// Validate sqlite pragmas before crossing the NAPI boundary.
 	// PRAGMA syntax doesn't take bound parameters — the Rust side will
@@ -149,7 +145,7 @@ export async function createNapiConnection(
 // shared with AtlasProvider.
 
 /** Load the native DB binding from the prebuilt `.node` binary in the package root. */
-async function loadNativeDb(): Promise<NapiModule | null> {
+async function loadNativeDb(): Promise<NapiModule> {
 	const platform = process.platform;
 	const arch = process.arch;
 	// Same naming convention as napi-rs / src/query/native.ts: the build emits
@@ -172,7 +168,14 @@ async function loadNativeDb(): Promise<NapiModule | null> {
 		// The binary lives at the package root (../../db.<suffix>.node from src/adapters/)
 		const binaryPath = join(here, "..", "..", binaryName);
 		return require(binaryPath) as NapiModule;
-	} catch {
-		return null;
+	} catch (err) {
+		// Surface the real cause (missing file, ABI mismatch, dlopen error) — a
+		// bare `return null` previously erased it and left the caller throwing a
+		// generic "not available" message that was impossible to debug.
+		throw new Error(
+			`[ATLAS] Failed to load Rust DB driver '${binaryName}' for ${platform}-${arch}. ` +
+				"Build with: cargo build --release",
+			{ cause: err },
+		);
 	}
 }

package/src/configure.ts

@@ -11,24 +11,23 @@ interface Codemods {
 export async function configure(codemods: Codemods): Promise<void> {
 	await codemods.addProvider("@c9up/atlas/provider");
 	await codemods.addEnvVars({
-		DB_CONNECTION: "postgres",
 		DB_HOST: "localhost",
 		DB_PORT: "5432",
 		DB_DATABASE: "ream",
 		DB_USER: "postgres",
-		DB_PASSWORD: "secret",
+		DB_PASSWORD: "change-me",
 	});
 	await codemods.writeFile(
 		"config/database.ts",
 		`import { defineConfig } from '@c9up/atlas'
 
 export default defineConfig({
-  connection: process.env.DB_CONNECTION ?? 'postgres',
+  default: 'postgres',
   connections: {
     postgres: {
-      host: process.env.DB_HOST ?? 'localhost',
-      port: Number(process.env.DB_PORT ?? '5432'),
-      database: process.env.DB_DATABASE ?? 'ream',
+      url:
+        process.env.DATABASE_URL ??
+        \`postgres://\${process.env.DB_USER ?? 'postgres'}:\${process.env.DB_PASSWORD ?? ''}@\${process.env.DB_HOST ?? 'localhost'}:\${process.env.DB_PORT ?? '5432'}/\${process.env.DB_DATABASE ?? 'ream'}\`,
     },
   },
 })

package/src/decorators/entity.ts

@@ -9,7 +9,7 @@ import {
 	COLUMN_SERIALIZE_KEY,
 	COMPUTED_KEY,
 	type ColumnSerializeConfig,
-} from "../BaseEntity.js";
+} from "../metadata-keys.js";
 
 const ENTITY_KEY = Symbol("atlas:entity");
 const COLUMNS_KEY = Symbol("atlas:columns");

package/src/metadata-keys.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared entity metadata keys + serialize config.
+ *
+ * Extracted from `BaseEntity` so the decorator layer (`decorators/entity.ts`)
+ * can read them without importing `BaseEntity` — that import-back formed a
+ * runtime cycle `BaseEntity` ↔ `entity` (fallow 2026-06-14). Agnostic: pure
+ * `Symbol.for` keys + a plain interface, zero runtime dependencies.
+ */
+
+/** Symbol metadata key for the computed-property registry on an entity class. */
+export const COMPUTED_KEY = Symbol.for("atlas:computed");
+
+/** Symbol metadata key for the serialize-as / serializer overrides on columns. */
+export const COLUMN_SERIALIZE_KEY = Symbol.for("atlas:columnSerialize");
+
+/** Per-column serialization config (populated by @Column options). */
+export interface ColumnSerializeConfig {
+	/** Rename this column at toJSON time (e.g. `password` → `passwordHash`). Null = hidden. */
+	serializeAs?: string | null;
+	/** Transform function applied to the value at toJSON time. */
+	serialize?: (value: unknown) => unknown;
+}

package/src/query/native.ts

@@ -67,6 +67,16 @@ export interface CompiledStatement {
  */
 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
@@ -143,7 +153,8 @@ 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(

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;
 }