@c9up/atlas 0.1.8 → 0.1.10

package/src/BaseRepository.ts

@@ -33,6 +33,8 @@ import {
 	type AtlasDialect,
 	compileStatementNative,
 	getAtlasDialect,
+	registerColumnCast,
+	registerTableCasts,
 } from "./query/native.js";
 import { camelToSnake, snakeToCamel } from "./utils/casing.js";
 
@@ -265,6 +267,37 @@ export class BaseRepository<T extends BaseEntity> {
 		// Postgres cast hints: sqlx binds JS strings as `text`, which Postgres
 		// won't coerce to timestamp/uuid/date. See `computeCastTypes`.
 		this.#castTypes = computeCastTypes(entityClass);
+		// Publish this table's casts to the compile-time registry so EVERY
+		// statement on this table — including the fluent `ModelQuery` and relation
+		// loaders, which never receive `#castTypes` directly — gets `$N::uuid`
+		// casts on its params. Without this, `repo.query().where('id', uuid)` and
+		// relation WHEREs fail on Postgres with `operator does not exist: uuid = text`.
+		registerTableCasts(this.#tableName, this.#castTypes);
+		// Publish relation FK column casts to the (merging) registry so eager AND
+		// lazy relation WHEREs on a uuid FK get `::uuid` even when the FK column
+		// wasn't explicitly `@Column({ type })`-typed. A FK references a typed PK
+		// whose logical type we know. (m2m FKs live on the pivot table — handled
+		// separately via `pivotKeyCasts`.)
+		for (const rel of getRelationMetadata(entityClass)) {
+			if (rel.type === "manyToMany") continue;
+			const related = rel.target();
+			if (rel.type === "belongsTo") {
+				// FK lives on THIS table, references the related (owner) PK.
+				const fk = rel.foreignKey ?? `${camelToSnake(related.name)}_id`;
+				const ownerKey = rel.ownerKey ?? getPrimaryKey(related) ?? "id";
+				const cast = computeCastTypes(related)[camelToSnake(ownerKey)];
+				if (cast) registerColumnCast(this.#tableName, fk, cast);
+			} else {
+				// hasOne / hasMany: FK lives on the RELATED table, references THIS PK.
+				const fk = rel.foreignKey ?? `${camelToSnake(entityClass.name)}_id`;
+				const localKey = rel.localKey ?? this.#primaryKey;
+				const cast = this.#castTypes[camelToSnake(localKey)];
+				const relatedMeta = getEntityMetadata(related);
+				if (cast && relatedMeta) {
+					registerColumnCast(relatedMeta.tableName, fk, cast);
+				}
+			}
+		}
 	}
 
 	// ─── Column validation ────────────────────────────────────
@@ -318,15 +351,10 @@ export class BaseRepository<T extends BaseEntity> {
 	// ─── Finders ──────────────────────────────────────────────
 
 	async find(id: string | number | bigint): Promise<T | null> {
-		const wheres: Array<Record<string, unknown>> = [
-			{ column: this.#primaryKey, operator: "=", value: id, type: "and" },
-		];
-		this.#appendSoftScope(wheres);
-		const { sql, params } = this.#compileSelect({ wheres, limit: 1 });
-		const rows = await this.#db.query<Row>(sql, params);
-		const row = rows[0];
-		if (!row) return null;
-		return this.#hydrate(row);
+		// Route through the query builder so the read hooks (beforeFind/afterFind)
+		// fire and a `beforeFind` hook can mutate the query — the previous direct
+		// `#compileSelect` fast path bypassed every read hook silently.
+		return this.query().where(this.#primaryKey, id).first();
 	}
 
 	async findOrFail(id: string | number): Promise<T> {
@@ -340,60 +368,34 @@ export class BaseRepository<T extends BaseEntity> {
 	}
 
 	async findBy(column: string, value: unknown): Promise<T | null> {
-		const col = this.#resolveColumn(column);
-		const wheres: Array<Record<string, unknown>> = [
-			{ column: col, operator: "=", value, type: "and" },
-		];
-		this.#appendSoftScope(wheres);
-		const { sql, params } = this.#compileSelect({ wheres, limit: 1 });
-		const rows = await this.#db.query<Row>(sql, params);
-		const row = rows[0];
-		if (!row) return null;
-		return this.#hydrate(row);
+		// Through the builder for read-hook parity (see `find`).
+		return this.query().where(column, value).first();
 	}
 
 	async all(): Promise<T[]> {
-		const wheres: Array<Record<string, unknown>> = [];
-		this.#appendSoftScope(wheres);
-		return this.#runSelect({ wheres });
+		// Through the builder so beforeFetch/afterFetch fire. The builder applies
+		// the soft-delete scope by default, exactly like the old fast path.
+		return this.query().exec();
 	}
 
 	async allWithTrashed(): Promise<T[]> {
-		return this.#runSelect({});
+		return this.query().withTrashed().exec();
 	}
 
 	async onlyTrashed(): Promise<T[]> {
 		if (!this.#softDeletes) return [];
-		return this.#runSelect({
-			wheres: [
-				{
-					column: "deleted_at",
-					operator: "IS NOT NULL",
-					value: null,
-					type: "and",
-				},
-			],
-		});
+		return this.query().onlyTrashed().exec();
 	}
 
 	async where(column: string, value: unknown): Promise<T[]> {
-		const col = this.#resolveColumn(column);
-		const wheres: Array<Record<string, unknown>> = [
-			{ column: col, operator: "=", value, type: "and" },
-		];
-		this.#appendSoftScope(wheres);
-		// Order by the resolved primary key (DESC = most recent insert first when
-		// the PK is an auto-increment integer or a monotonic UUID). Previously
-		// this hard-coded `rowid DESC`, which is a SQLite-only pseudo-column and
-		// blew up on Postgres/MySQL the moment the app ran against a real driver.
-		// Using the PK works on every dialect and matches the user's actual
-		// schema — the ordering contract is "most recent first by PK" for
-		// `repo.where(col, val)` as a convenience finder.
-		const pkCol = camelToSnake(this.#primaryKey);
-		return this.#runSelect({
-			wheres,
-			orderBy: [{ column: pkCol, direction: "desc" }],
-		});
+		// Order by the primary key (DESC = most recent insert first when the PK is
+		// an auto-increment integer or a monotonic UUID). The ordering contract is
+		// "most recent first by PK" for `repo.where(col, val)` as a convenience
+		// finder. Through the builder for read-hook parity (see `find`).
+		return this.query()
+			.where(column, value)
+			.orderBy(this.#primaryKey, "desc")
+			.exec();
 	}
 
 	// ─── Create / Save / Delete ───────────────────────────────
@@ -417,6 +419,7 @@ export class BaseRepository<T extends BaseEntity> {
 		await this.#insert(entity);
 		await fireHooks(this.#entityClass, "afterCreate", entity);
 		await fireHooks(this.#entityClass, "afterSave", entity);
+		await this.#dispatchDomainEvents(entity);
 		return entity;
 	}
 
@@ -461,6 +464,17 @@ export class BaseRepository<T extends BaseEntity> {
 		}
 		await fireHooks(this.#entityClass, "afterSave", entity);
 
+		await this.#dispatchDomainEvents(entity);
+	}
+
+	/**
+	 * Flush the entity's accumulated domain events through `onDomainEvents`.
+	 * On dispatch failure the events are re-queued on the entity and the error
+	 * propagates, so a caller can retry without losing them. Shared by `save`,
+	 * `create` and `createMany` — every persistence path that produces a live
+	 * entity must dispatch, otherwise events silently vanish on batch inserts.
+	 */
+	async #dispatchDomainEvents(entity: BaseEntity): Promise<void> {
 		const events = entity.flushDomainEvents();
 		if (events.length > 0 && this.onDomainEvents) {
 			try {
@@ -543,6 +557,9 @@ export class BaseRepository<T extends BaseEntity> {
 			await fireHooks(this.#entityClass, "afterCreate", e);
 			await fireHooks(this.#entityClass, "afterSave", e);
 		}
+		for (const e of entities) {
+			await this.#dispatchDomainEvents(e);
+		}
 		return entities;
 	}
 
@@ -680,15 +697,32 @@ export class BaseRepository<T extends BaseEntity> {
 
 	#applyConsume(propertyKey: string, value: unknown): unknown {
 		const consume = this.#columnConsumes.get(propertyKey);
-		if (!consume) return value;
-		let result: unknown;
-		try {
-			result = consume(value);
-		} catch (err) {
-			throw wrapAdapterError("consume", propertyKey, err);
+		if (consume) {
+			let result: unknown;
+			try {
+				result = consume(value);
+			} catch (err) {
+				throw wrapAdapterError("consume", propertyKey, err);
+			}
+			assertNotPromise("consume", propertyKey, result);
+			return result;
 		}
-		assertNotPromise("consume", propertyKey, result);
-		return result;
+		// No explicit `@Column({ consume })`: a `@column.date()` / `@column.dateTime()`
+		// column hydrates its DB value (an ISO string from the Rust decode) into a
+		// JS `Date`, so `.getTime()` / date arithmetic work on read. Mirrors Adonis
+		// Lucid hydrating date columns to a Luxon `DateTime` — atlas standardises on
+		// the native `Date` (no Luxon dependency). An unparseable string is left
+		// untouched rather than turned into `Invalid Date`.
+		if (
+			this.#dateColumns[propertyKey] &&
+			value != null &&
+			!(value instanceof Date) &&
+			(typeof value === "string" || typeof value === "number")
+		) {
+			const d = new Date(value);
+			if (!Number.isNaN(d.getTime())) return d;
+		}
+		return value;
 	}
 
 	#plainToRowPairs(obj: Record<string, unknown>): Array<[string, unknown]> {
@@ -858,43 +892,6 @@ export class BaseRepository<T extends BaseEntity> {
 
 	// ─── Private helpers ──────────────────────────────────────
 
-	#compileSelect(opts: {
-		wheres?: Array<Record<string, unknown>>;
-		orderBy?: Array<Record<string, unknown>>;
-		limit?: number;
-	}): { sql: string; params: unknown[] } {
-		const spec = {
-			kind: "select",
-			table: this.#tableName,
-			select: ["*"],
-			wheres: opts.wheres ?? [],
-			orderBy: opts.orderBy ?? [],
-			groupBy: [],
-			having: [],
-			limit: opts.limit ?? null,
-			offset: null,
-			distinct: false,
-			ctes: [],
-			unions: [],
-			// Cast WHERE params on native-typed columns (uuid/timestamp/…) so a
-			// `WHERE id = $1` on a uuid PK emits `$1::uuid` — otherwise Postgres
-			// rejects it with `operator does not exist: uuid = text`.
-			casts: this.#castTypes,
-		};
-		const compiled = compileStatementNative(spec, this.#dialect);
-		return { sql: compiled.statements[0], params: compiled.params };
-	}
-
-	async #runSelect(opts: {
-		wheres?: Array<Record<string, unknown>>;
-		orderBy?: Array<Record<string, unknown>>;
-		limit?: number;
-	}): Promise<T[]> {
-		const { sql, params } = this.#compileSelect(opts);
-		const rows = await this.#db.query<Row>(sql, params);
-		return rows.map((r) => this.#hydrate(r));
-	}
-
 	async #runDelete(wheres: Array<Record<string, unknown>>): Promise<void> {
 		const compiled = compileStatementNative(
 			{ kind: "delete", table: this.#tableName, wheres },
@@ -973,17 +970,6 @@ export class BaseRepository<T extends BaseEntity> {
 		return {};
 	}
 
-	#appendSoftScope(wheres: Array<Record<string, unknown>>): void {
-		if (this.#softDeletes) {
-			wheres.push({
-				column: "deleted_at",
-				operator: "IS NULL",
-				value: null,
-				type: "and",
-			});
-		}
-	}
-
 	async #insert(entity: T): Promise<void> {
 		// Auto-generate the PK when declared via `@PrimaryKey({ generated })`.
 		this.#applyPrimaryKeyGenerator(entity);
@@ -1264,6 +1250,10 @@ export class BaseRepository<T extends BaseEntity> {
 		const relatedRepo = new BaseRepository<BaseEntity>(relatedClass, this.#db, {
 			dialect: this.#dialect,
 		});
+		// Propagate the domain-event sink so entities persisted through a relation
+		// proxy (user.related('posts').create(...)) dispatch their events too —
+		// otherwise the related entity's events silently vanish.
+		relatedRepo.onDomainEvents = this.onDomainEvents;
 		const db = this.#db;
 
 		// FK column naming: belongsTo stores the FK on THIS side; has* / m2m on the OTHER side.
@@ -1326,6 +1316,14 @@ export class BaseRepository<T extends BaseEntity> {
 					}
 					return dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
 				};
+				// The bound `?` carries the parent PK type (often uuid). A raw `?`
+				// can't be cast by the structured `casts` mechanism, so emit the
+				// `::uuid` inline — `whereRaw` rewrites `?`→`$N`, yielding `$N::uuid`.
+				// Postgres-only; sqlite/mysql coerce. Without it: `pivotFk = $N` is
+				// `uuid = text`.
+				const parentPkCast = this.#castTypes[camelToSnake(this.#primaryKey)];
+				const ph =
+					dialect === "postgres" && parentPkCast ? `?::${parentPkCast}` : "?";
 				// EXISTS (SELECT 1 FROM pivot WHERE pivot.pivotFk = ? AND pivot.pivotOther = related.pk)
 				// Framework-internal raw fragment (identifiers already validated by
 				// the `quote` helper above) — bypass strict mode so this path still
@@ -1333,7 +1331,7 @@ export class BaseRepository<T extends BaseEntity> {
 				runWithAtlasInternalBypass(() => {
 					q.whereRaw(
 						`EXISTS (SELECT 1 FROM ${quote(pivot.pivotTable)} ` +
-							`WHERE ${quote(pivot.pivotTable)}.${quote(pivotFk)} = ? ` +
+							`WHERE ${quote(pivot.pivotTable)}.${quote(pivotFk)} = ${ph} ` +
 							`AND ${quote(pivot.pivotTable)}.${quote(pivotOther)} = ${quote(relatedTable)}.${quote(relatedPk)})`,
 						[parentIdValue],
 					);
@@ -1395,6 +1393,20 @@ export class BaseRepository<T extends BaseEntity> {
 			const pivotAdapters = pivot.pivotColumnAdapters;
 			const dialect = this.#dialect;
 
+			// Postgres cast hints for the two pivot FK columns — they reference the
+			// parent / related PK types (often uuid). The pivot table is NOT an
+			// entity table, so the compile-time cast registry never covers it;
+			// every pivot statement (sync's currentIds SELECT, detach DELETE, attach
+			// INSERT) must carry these explicitly, else `pivotFk = $1` is `uuid = text`.
+			const pivotKeyCasts: Record<string, string> = {};
+			const parentPkCast = this.#castTypes[camelToSnake(this.#primaryKey)];
+			if (parentPkCast) pivotKeyCasts[pivotFk] = parentPkCast;
+			const relatedPkCast =
+				computeCastTypes(relatedClass)[
+					camelToSnake(getPrimaryKey(relatedClass) ?? "id")
+				];
+			if (relatedPkCast) pivotKeyCasts[pivotOther] = relatedPkCast;
+
 			/**
 			 * Resolve pivot timestamp column names from the decorator config.
 			 *
@@ -1467,6 +1479,7 @@ export class BaseRepository<T extends BaseEntity> {
 					unions: [],
 					joins: [],
 					lockMode: null,
+					casts: pivotKeyCasts,
 				};
 				const compiled = compileStatementNative(selectSpec, dialect);
 				const rows = await db.query<Record<string, unknown>>(
@@ -1496,6 +1509,7 @@ export class BaseRepository<T extends BaseEntity> {
 					table: pivotTable,
 					wheres,
 					returning: [],
+					casts: pivotKeyCasts,
 				};
 				const compiled = compileStatementNative(spec, dialect);
 				await db.execute(compiled.statements[0], compiled.params);
@@ -1557,17 +1571,10 @@ export class BaseRepository<T extends BaseEntity> {
 					for (const [k, v] of Object.entries(ts)) pairs.push([k, v]);
 					return pairs;
 				});
-				// Postgres casts for the pivot row: the two FK columns reference the
-				// parent / related PK types (often uuid), and pivot timestamps are
-				// bound strings — all need `$N::<type>` on Postgres.
-				const pivotCasts: Record<string, string> = {};
-				const parentPkCast = this.#castTypes[camelToSnake(this.#primaryKey)];
-				if (parentPkCast) pivotCasts[pivotFk] = parentPkCast;
-				const relatedPkCast =
-					computeCastTypes(relatedClass)[
-						camelToSnake(getPrimaryKey(relatedClass) ?? "id")
-					];
-				if (relatedPkCast) pivotCasts[pivotOther] = relatedPkCast;
+				// Postgres casts for the pivot row: the two FK columns (parent /
+				// related PK types, often uuid) reuse `pivotKeyCasts`; pivot
+				// timestamps are bound strings — all need `$N::<type>` on Postgres.
+				const pivotCasts: Record<string, string> = { ...pivotKeyCasts };
 				for (const k of Object.keys(ts)) pivotCasts[k] = "timestamp";
 				const spec = {
 					kind: "insert",

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");
@@ -20,7 +20,7 @@ const RELATIONS_KEY = Symbol("atlas:relations");
 /** Auto-generation strategy for `@PrimaryKey({ generated: ... })`. */
 export type PrimaryKeyGenerator = "uuid";
 
-export interface PrimaryKeyOptions {
+export interface PrimaryKeyOptions extends ColumnOptions {
 	/**
 	 * Auto-generate the primary-key value on INSERT when the entity has none
 	 * (undefined). `'uuid'` produces an RFC-4122 v4 string via `crypto.randomUUID()`.
@@ -355,8 +355,16 @@ export function PrimaryKey(options?: PrimaryKeyOptions): PropertyDecorator {
 				target.constructor,
 			);
 		}
-		// Also register as a column
-		Column()(target, propertyKey);
+		// Register as a column, PROPAGATING the options so a typed PK records its
+		// SQL type — needed for the `::uuid` cast in WHERE/INSERT (otherwise a
+		// uuid PK compared to a bound string fails `operator does not exist:
+		// uuid = text`). A uuid generator implies a uuid column type unless the
+		// caller set one explicitly.
+		const columnOptions: ColumnOptions = { ...options };
+		if (columnOptions.type === undefined && options?.generated === "uuid") {
+			columnOptions.type = "uuid";
+		}
+		Column(columnOptions)(target, propertyKey);
 	};
 }
 

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