@c9up/atlas 0.2.7 → 0.3.0

package/src/ModelQuery.ts

@@ -19,6 +19,7 @@ import {
 	wrapAdapterError,
 } from "./BaseRepository.js";
 import {
+	defaultRelationForeignKey,
 	ensureEntityMetadata,
 	getColumnMetadata,
 	getDateColumnConfig,
@@ -750,6 +751,22 @@ function structuredCloneSafe<T>(value: T): T {
 	return structuredClone(value);
 }
 
+/**
+ * What {@link ModelQuery.pojo} hands back: awaitable for the rows, and
+ * chainable into `first()`.
+ *
+ * NAMED DEVIATION — Lucid's `pojo()` is a flag on the builder
+ * (`pojo(): this`), so the whole builder surface stays available after it.
+ * `ModelQuery<T>` is constrained to `T extends BaseEntity` and cannot be
+ * re-parametrised to a plain record, so ours is a terminal view instead. It
+ * covers what Lucid's own code does with it — `query.pojo().first()` — and
+ * `await query.pojo()` is unchanged.
+ */
+export interface PojoQuery<R> extends PromiseLike<R[]> {
+	/** The first row, or `null`. */
+	first(): Promise<R | null>;
+}
+
 export class ModelQuery<T extends BaseEntity> {
 	#tableName: string;
 	#db: DatabaseConnection;
@@ -3012,6 +3029,24 @@ export class ModelQuery<T extends BaseEntity> {
 		return this.exec().then(onfulfilled, onrejected);
 	}
 
+	/**
+	 * The rest of the promise protocol, so a builder is not a half-promise.
+	 *
+	 * `await query` worked while `query.catch(fn)` and `query.finally(fn)` threw
+	 * "not a function" — a value that answers to `then` and nothing else
+	 * surprises anyone who treats it as the promise it looks like. Lucid's
+	 * builder carries all three.
+	 */
+	catch<TResult = never>(
+		onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+	): Promise<T[] | TResult> {
+		return this.exec().catch(onrejected);
+	}
+
+	finally(onfinally?: (() => void) | null): Promise<T[]> {
+		return this.exec().finally(onfinally);
+	}
+
 	/** Build the spec object that gets sent to the Rust compiler. Extracted so whereHas can reuse it for sub-queries. */
 	/**
 	 * DB column backing the soft-delete `deletedAt` property — honours a
@@ -3339,9 +3374,18 @@ export class ModelQuery<T extends BaseEntity> {
 	 * AdonisJS Lucid `pojo()`. Fast read path for reports/exports where model
 	 * instances aren't needed.
 	 */
-	async pojo<R = Record<string, unknown>>(): Promise<R[]> {
-		const { sql, params } = this.#compiledNative();
-		return this.#db.query<R>(sql, params);
+	pojo<R = Record<string, unknown>>(): PojoQuery<R> {
+		const run = async (limitOne: boolean): Promise<R[]> => {
+			if (limitOne) this.#limit = 1;
+			const { sql, params } = this.#compiledNative();
+			return this.#db.query<R>(sql, params);
+		};
+		return {
+			// biome-ignore lint/suspicious/noThenProperty: deliberately thenable, which is what PromiseLike means — the rule exists to catch ACCIDENTAL thenables. `await query.pojo()` is the existing API and must keep working; same justification as ModelQuery.then above.
+			then: (onfulfilled, onrejected) =>
+				run(false).then(onfulfilled, onrejected),
+			first: async () => (await run(true))[0] ?? null,
+		};
 	}
 
 	/**
@@ -3564,9 +3608,10 @@ export class ModelQuery<T extends BaseEntity> {
 		const parentLocal =
 			relation.localKey ?? getPrimaryKey(this.#entityClass) ?? "id";
 		const firstKey =
-			relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+			relation.firstKey ??
+			defaultRelationForeignKey("hasMany", this.#entityClass);
 		const secondKey =
-			relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
+			relation.secondKey ?? defaultRelationForeignKey("hasMany", throughClass);
 		// secondLocal indexes the THROUGH row (`row[secondLocal]`), so it must be a
 		// DB column — resolve the through model's key (default: its PK), honouring a
 		// multi-word / columnName PK. (parentLocal stays a property: it's read off
@@ -3628,7 +3673,8 @@ export class ModelQuery<T extends BaseEntity> {
 		ctx: PreloadContext,
 	): Promise<BaseEntity[]> {
 		const fk =
-			ctx.relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+			ctx.relation.foreignKey ??
+			defaultRelationForeignKey("hasMany", this.#entityClass);
 		const pk =
 			ctx.relation.localKey ?? getPrimaryKey(this.#entityClass) ?? "id";
 		const ids = entities.map((e) => e[pk]).filter((v) => v != null);
@@ -3670,7 +3716,8 @@ export class ModelQuery<T extends BaseEntity> {
 		ctx: PreloadContext,
 	): Promise<BaseEntity[]> {
 		const fk =
-			ctx.relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+			ctx.relation.foreignKey ??
+			defaultRelationForeignKey("hasMany", this.#entityClass);
 		const pk =
 			ctx.relation.localKey ?? getPrimaryKey(this.#entityClass) ?? "id";
 		const ids = entities.map((e) => e[pk]).filter((v) => v != null);
@@ -3699,7 +3746,8 @@ export class ModelQuery<T extends BaseEntity> {
 		ctx: PreloadContext,
 	): Promise<BaseEntity[]> {
 		const fk =
-			ctx.relation.foreignKey ?? `${camelToSnake(ctx.relatedClass.name)}_id`;
+			ctx.relation.foreignKey ??
+			defaultRelationForeignKey("belongsTo", ctx.relatedClass);
 		const fkProp = `${relationName}Id`;
 		const ids = entities
 			.map((e) => e[fkProp] ?? e[fk])
@@ -3739,9 +3787,11 @@ export class ModelQuery<T extends BaseEntity> {
 		// 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.#entityClass.name)}_id`;
+			pivot.foreignKey ??
+			defaultRelationForeignKey("manyToMany", this.#entityClass);
 		const otherKey =
-			pivot.otherKey ?? `${camelToSnake(ctx.relatedClass.name)}_id`;
+			pivot.otherKey ??
+			defaultRelationForeignKey("manyToMany", ctx.relatedClass);
 		// The pivot FK stores `parent[localKey]` (default PK) — attach() writes it,
 		// so preload MUST read back with the SAME key, else a custom-localKey m2m
 		// writes `user_code = code` but reads `user_code IN (id)` and never matches.
@@ -4138,7 +4188,8 @@ export class ModelQuery<T extends BaseEntity> {
 				// Honour custom foreignKey/localKey exactly like the eager loader —
 				// hard-coding them here produced silently-wrong whereHas/withCount SQL.
 				const fk =
-					relation.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+					relation.foreignKey ??
+					defaultRelationForeignKey("hasMany", this.#entityClass);
 				const localKey = resolveParent(relation.localKey ?? parentPk);
 				sub.#pushWhereRaw(
 					`${qTable(relatedTable)}.${q(fk)} = ${qTable(parentTable)}.${q(localKey)}`,
@@ -4147,7 +4198,8 @@ export class ModelQuery<T extends BaseEntity> {
 			}
 			case "belongsTo": {
 				const fk =
-					relation.foreignKey ?? `${camelToSnake(relatedClass.name)}_id`;
+					relation.foreignKey ??
+					defaultRelationForeignKey("belongsTo", relatedClass);
 				const ownerKey = buildColumnResolver(relatedClass)(
 					relation.ownerKey ?? getPrimaryKey(relatedClass) ?? "id",
 				);
@@ -4166,9 +4218,11 @@ export class ModelQuery<T extends BaseEntity> {
 				// 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(this.#entityClass.name)}_id`;
+					pivot.foreignKey ??
+					defaultRelationForeignKey("manyToMany", this.#entityClass);
 				const otherKey =
-					pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
+					pivot.otherKey ??
+					defaultRelationForeignKey("manyToMany", relatedClass);
 				const relatedPkProp = getPrimaryKey(relatedClass) ?? "id";
 				const relatedPk =
 					getColumnMetadata(relatedClass).find(
@@ -4198,9 +4252,11 @@ export class ModelQuery<T extends BaseEntity> {
 				const throughPk = getPrimaryKey(throughClass) ?? "id";
 				const parentLocal = resolveParent(relation.localKey ?? parentPk);
 				const firstKey =
-					relation.firstKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+					relation.firstKey ??
+					defaultRelationForeignKey("hasMany", this.#entityClass);
 				const secondKey =
-					relation.secondKey ?? `${camelToSnake(throughClass.name)}_id`;
+					relation.secondKey ??
+					defaultRelationForeignKey("hasMany", throughClass);
 				const secondLocal = buildColumnResolver(throughClass)(
 					relation.secondLocalKey ?? throughPk,
 				);
@@ -4462,8 +4518,14 @@ export class ModelQuery<T extends BaseEntity> {
 		return !(await this.exists());
 	}
 
-	/** Flat column projection. Rejects object/relation columns. */
-	async pluck(column: string): Promise<unknown[]> {
+	/**
+	 * Flat column projection (Knex `pluck`, which Lucid inherits). Rejects
+	 * object/relation columns.
+	 *
+	 * Generic like Knex's, so a caller who knows the column type does not have
+	 * to cast the whole array at the call site.
+	 */
+	async pluck<V = unknown>(column: string): Promise<V[]> {
 		const col = this.#resolveColumn(column);
 		const clone = this.clone();
 		clone.#select = [col];
@@ -4476,7 +4538,7 @@ export class ModelQuery<T extends BaseEntity> {
 					`pluck('${column}') rejected — column is an object/relation`,
 				);
 			}
-			return v;
+			return v as V;
 		});
 	}
 
@@ -4548,7 +4610,7 @@ export class ModelQuery<T extends BaseEntity> {
 	// === Story 29.10 — pagination =====================================================================
 
 	/** Offset-based paginator. */
-	async paginate(page: number, perPage: number): Promise<Paginator<T>> {
+	async paginate(page: number, perPage = 20): Promise<Paginator<T>> {
 		const p = Math.max(1, Math.floor(page));
 		const pp = Math.max(1, Math.floor(perPage));
 		// Adonis Lucid hook order:

package/src/decorators/entity.ts

@@ -609,6 +609,27 @@ export function getPrimaryKey(target: Constructor): string | undefined {
 	return Reflect.getMetadata(PRIMARY_KEY, target);
 }
 
+/**
+ * The foreign key a relation falls back to when none is declared.
+ *
+ * Goes through the entity's naming strategy rather than hardcoding `_id`, so a
+ * model whose primary key is not `id` gets `user_uuid` instead of a `user_id`
+ * column that does not exist. Lucid derives it the same way
+ * (`relationForeignKey` / `relationPivotForeignKey`), and for the usual `id`
+ * the result is unchanged.
+ */
+export function defaultRelationForeignKey(
+	kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
+	entityClass: Constructor,
+): string {
+	const pk = getPrimaryKey(entityClass) ?? "id";
+	return getNamingStrategy(entityClass).relationForeignKey(
+		kind,
+		entityClass.name,
+		pk,
+	);
+}
+
 /** Get relation metadata for a class (returns a copy). */
 export function getRelationMetadata(target: Constructor): RelationMetadata[] {
 	return [...(Reflect.getMetadata(RELATIONS_KEY, target) ?? [])];

package/src/naming/NamingStrategy.ts

@@ -30,7 +30,15 @@ export interface NamingStrategy {
 		kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
 		parentPk: string,
 	): string;
-	/** Foreign key column name on the owning side of a relation. */
+	/**
+	 * Foreign key COLUMN name on the owning side of a relation.
+	 *
+	 * NAMED DEVIATION — Lucid's method of the same name returns the model
+	 * ATTRIBUTE (camelCase), which it then runs through `columnName()`; the one
+	 * that returns a column upstream is `relationPivotForeignKey`. Atlas
+	 * resolves relations by column throughout, so one method answers for both
+	 * and it answers in snake_case. An override must return a column name.
+	 */
 	relationForeignKey(
 		kind: "belongsTo" | "hasMany" | "hasOne" | "manyToMany",
 		parentClass: string,
@@ -82,7 +90,12 @@ export class CamelCaseNamingStrategy implements NamingStrategy {
 		parentClass: string,
 		parentPk: string,
 	): string {
-		return `${camelToSnake(parentClass)}_${parentPk}`;
+		// The PK is snake_cased too, as Lucid does
+		// (`snakeCase(`${model.name}_${model.primaryKey}`)`). Identical to the
+		// old output for the usual `id`; a multi-word PK now yields a column
+		// name a migration would actually have created (`user_user_id`, not
+		// `user_userId`).
+		return `${camelToSnake(parentClass)}_${camelToSnake(parentPk)}`;
 	}
 
 	relationPivotTable(aClass: string, bClass: string): string {