@c9up/atlas 0.2.7 → 0.3.1

package/src/BaseRepository.ts

@@ -24,6 +24,7 @@ import type {
 import { REPO_REF } from "./BaseEntity.js";
 import {
 	type DateColumnConfig,
+	defaultRelationForeignKey,
 	ensureEntityMetadata,
 	getColumnMetadata,
 	getDateColumnConfig,
@@ -413,7 +414,8 @@ export class BaseRepository<T extends BaseEntity> {
 			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 fk =
+					rel.foreignKey ?? defaultRelationForeignKey("hasMany", related);
 				const ownerKey = rel.ownerKey ?? getPrimaryKey(related) ?? "id";
 				const ownerDb =
 					getColumnMetadata(related).find((c) => c.propertyKey === ownerKey)
@@ -422,7 +424,8 @@ export class BaseRepository<T extends BaseEntity> {
 				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 fk =
+					rel.foreignKey ?? defaultRelationForeignKey("hasMany", entityClass);
 				const localKey = rel.localKey ?? this.#primaryKey;
 				const cast = this.#castTypes[this.#dbColumn(localKey)];
 				// Boot the related model on demand (Lucid lazy-boot): a related model
@@ -660,7 +663,7 @@ export class BaseRepository<T extends BaseEntity> {
 	 * the specific hook runs before the general `beforeSave`).
 	 *
 	 * An unknown key throws by default (Lucid); pass `{ allowExtraProperties: true }`
-	 * to drop unknown keys instead. A bare boolean is the legacy `quiet` flag.
+	 * to keep it in `$extras` instead. A bare boolean is the legacy `quiet` flag.
 	 */
 	async create(
 		data: Partial<Record<string, unknown>>,
@@ -681,14 +684,20 @@ export class BaseRepository<T extends BaseEntity> {
 			} else if (key.startsWith("$")) {
 				// Framework-internal (`$extras`, `$trx`, …) — leaks in when an entity
 				// instance is passed as data. Not a user column and not a typo; skip.
-			} else if (!allowExtraProperties) {
+			} else if (allowExtraProperties) {
+				// Kept, not dropped: Lucid puts an unknown key in `$extras`
+				// (`this.$extras[key] = value`), which is where an aggregate or a
+				// pivot value travelling with the payload belongs. It is not a
+				// declared column, so it can never reach the INSERT.
+				entity.$extras[key] = value;
+			} else {
 				// Adonis Lucid throws on an unknown property by default (a typo'd or
 				// stray key is a bug, not something to silently drop). Opt out with
 				// `create(data, { allowExtraProperties: true })`.
 				throw new AtlasError(
 					"E_UNKNOWN_COLUMN",
 					`Cannot assign '${key}' — it is not a column on ${this.#entityClass.name}. ` +
-						"Pass { allowExtraProperties: true } to drop unknown keys instead.",
+						"Pass { allowExtraProperties: true } to keep unknown keys in $extras.",
 				);
 			}
 		}
@@ -2163,8 +2172,8 @@ export class BaseRepository<T extends BaseEntity> {
 		const fkCol =
 			relation.foreignKey ??
 			(relation.type === "belongsTo"
-				? `${camelToSnake(relatedClass.name)}_id`
-				: `${camelToSnake(this.#entityClass.name)}_id`);
+				? defaultRelationForeignKey("belongsTo", relatedClass)
+				: defaultRelationForeignKey("hasMany", this.#entityClass));
 		const fkProp = snakeToCamel(fkCol);
 
 		const injectFk = (
@@ -2363,9 +2372,11 @@ export class BaseRepository<T extends BaseEntity> {
 					throw new Error(`@ManyToMany ${relationName} requires pivot options`);
 				const pivot = relation.pivot;
 				const pivotFk =
-					pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+					pivot.foreignKey ??
+					defaultRelationForeignKey("manyToMany", this.#entityClass);
 				const pivotOther =
-					pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
+					pivot.otherKey ??
+					defaultRelationForeignKey("manyToMany", relatedClass);
 				// Resolve the related PK to its DB column (multi-word / columnName),
 				// mirroring the eager-preload fix — a raw property name here targets
 				// the wrong column in the correlated EXISTS.
@@ -2463,9 +2474,11 @@ export class BaseRepository<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);
 				const secondLocal = relation.secondLocalKey ?? throughPk;
 				q.whereIn(
 					secondKey,
@@ -2607,9 +2620,10 @@ export class BaseRepository<T extends BaseEntity> {
 			const pivot = relation.pivot;
 			const pivotTable = pivot.pivotTable;
 			const pivotFk =
-				pivot.foreignKey ?? `${camelToSnake(this.#entityClass.name)}_id`;
+				pivot.foreignKey ??
+				defaultRelationForeignKey("manyToMany", this.#entityClass);
 			const pivotOther =
-				pivot.otherKey ?? `${camelToSnake(relatedClass.name)}_id`;
+				pivot.otherKey ?? defaultRelationForeignKey("manyToMany", relatedClass);
 			const tsConfig = pivot.pivotTimestamps;
 			const pivotAdapters = pivot.pivotColumnAdapters;
 			const dialect = this.#dialect;

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/index.ts

@@ -10,14 +10,16 @@ export { SQLITE_PROD_PRAGMAS } from "./AtlasProvider.js";
 export type {
 	AsyncDatabaseConnection,
 	ConnectRetryOptions,
+	IsolationLevel,
 	ObservabilityOptions,
 	QueryMeta,
+	TransactionOptions,
 } from "./adapters/NapiDbAdapter.js";
 export { createNapiConnection } from "./adapters/NapiDbAdapter.js";
 export type { DomainEvent } from "./BaseEntity.js";
 export { BaseEntity } from "./BaseEntity.js";
 export { BaseModel } from "./BaseModel.js";
-export type { DatabaseConnection } from "./BaseRepository.js";
+export type { CreateOptions, DatabaseConnection } from "./BaseRepository.js";
 export { BaseRepository } from "./BaseRepository.js";
 export { defineConfig } from "./config.js";
 export { configure } from "./configure.js";
@@ -140,6 +142,9 @@ export {
 export {
 	isAtlasStrictMode,
 	ModelQuery,
+	// What `paginate()` hands back. Unexported, an app could not name the value
+	// it had just been given.
+	Paginator,
 	setAtlasStrictMode,
 } from "./ModelQuery.js";
 export type { NamingStrategy } from "./naming/NamingStrategy.js";
@@ -208,7 +213,29 @@ export {
 	runSeeders,
 	Seeder,
 } from "./schema/Seeder.js";
+/**
+ * The vocabulary of a migration callback.
+ *
+ * `onDelete(action)`, `foreign(...)` and the alter operations all take these,
+ * so a migration that pulls one into a named constant — or a helper that wraps
+ * a column definition — needs to be able to spell the type.
+ */
+export type {
+	AlterOperation,
+	CheckExpression,
+	CheckOperator,
+	CheckValue,
+	ColumnPosition,
+	ForeignKeyReference,
+	IndexDefinition,
+	ReferentialAction,
+	TableConstraintSpec,
+	TableOptionsSpec,
+	TextVariant,
+} from "./schema/types.js";
 export type { TransactionClient } from "./Transaction.js";
 export { transaction } from "./Transaction.js";
+export type { TestTransaction } from "./testing/DatabaseCleanup.js";
 export { truncateAll, useTransaction } from "./testing/DatabaseCleanup.js";
+export type { FactoryContext } from "./testing/Factory.js";
 export { Factory, factory } from "./testing/Factory.js";

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 {