@c9up/atlas 0.1.17 → 0.1.19

package/src/BaseRepository.ts

@@ -5,6 +5,7 @@
  */
 
 import { randomUUID } from "node:crypto";
+import type { TransactionOptions } from "./adapters/NapiDbAdapter.js";
 import type {
 	BaseEntity,
 	BelongsToRelationProxy,
@@ -27,9 +28,7 @@ import {
 	type PrimaryKeyGenerator,
 } from "./decorators/entity.js";
 import { fireHooks } from "./decorators/hooks.js";
-import type { TransactionOptions } from "./adapters/NapiDbAdapter.js";
 import { AtlasError, EntityNotFoundError } from "./errors.js";
-import type { TransactionClient } from "./Transaction.js";
 import { ModelQuery, runWithAtlasInternalBypass } from "./ModelQuery.js";
 import {
 	type AtlasDialect,
@@ -38,6 +37,7 @@ import {
 	registerColumnCast,
 	registerTableCasts,
 } from "./query/native.js";
+import { type TransactionClient, transaction } from "./Transaction.js";
 import { camelToSnake, snakeToCamel } from "./utils/casing.js";
 
 type EntityConstructor<T extends BaseEntity> = new () => T;
@@ -147,6 +147,23 @@ const POSTGRES_CAST_TYPES = new Set([
 	"jsonb",
 	"numeric",
 	"decimal",
+	// Nullable integer columns (opt-in via `@Column({ type: 'integer' })`): a JS
+	// number binds as a real int, but a JS `null` binds as text, which Postgres
+	// won't coerce to int on assignment. Untyped `@Column()` int columns never
+	// reach here, so their plain-number bind is untouched.
+	"integer",
+	"int",
+	"bigint",
+	"smallint",
+	// Nullable boolean / float columns hit the same text-bound-NULL issue.
+	"boolean",
+	"bool",
+	"real",
+	"float4",
+	"double precision",
+	"double",
+	"float8",
+	"float",
 ]);
 
 /**
@@ -378,6 +395,14 @@ export class BaseRepository<T extends BaseEntity> {
 	// ─── Finders ──────────────────────────────────────────────
 
 	async find(id: string | number | bigint): Promise<T | null> {
+		// AdonisJS Lucid throws on `undefined`/`null` rather than silently running
+		// `WHERE pk = NULL` (which matches nothing) — a common typo footgun.
+		if (id === undefined || id === null) {
+			throw new AtlasError(
+				"E_INVALID_FIND_VALUE",
+				`${this.#entityClass.name}.find() expects a value, received ${String(id)}.`,
+			);
+		}
 		// 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.
@@ -399,10 +424,40 @@ export class BaseRepository<T extends BaseEntity> {
 		return this.query().where(column, value).first();
 	}
 
+	/** Find by a column or throw `EntityNotFoundError` (AdonisJS `findByOrFail`). */
+	async findByOrFail(column: string, value: unknown): Promise<T> {
+		const entity = await this.findBy(column, value);
+		if (!entity) {
+			throw new EntityNotFoundError(this.#entityClass.name, {
+				[column]: value,
+			});
+		}
+		return entity;
+	}
+
+	/** Find many rows by primary key (AdonisJS `findMany`), ordered PK desc. */
+	async findMany(ids: Array<string | number>): Promise<T[]> {
+		if (ids.length === 0) return [];
+		return this.query()
+			.whereIn(this.#primaryKey, ids)
+			.orderBy(this.#primaryKey, "desc")
+			.exec();
+	}
+
+	/** Find many rows by an arbitrary column (AdonisJS `findManyBy`). */
+	async findManyBy(
+		column: string,
+		values: Array<string | number>,
+	): Promise<T[]> {
+		if (values.length === 0) return [];
+		return this.query().whereIn(column, values).exec();
+	}
+
 	async all(): Promise<T[]> {
 		// 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();
+		// Ordered PK desc for AdonisJS Lucid `all()` parity (newest first).
+		return this.query().orderBy(this.#primaryKey, "desc").exec();
 	}
 
 	async allWithTrashed(): Promise<T[]> {
@@ -664,9 +719,14 @@ export class BaseRepository<T extends BaseEntity> {
 		search: Record<string, unknown>,
 		defaults: Record<string, unknown> = {},
 	): Promise<T> {
-		const existing = await this.#findBySearch(search);
-		if (existing) return existing;
-		return this.create({ ...search, ...defaults });
+		// Atomic (AdonisJS Lucid parity): find-under-lock then create inside one
+		// transaction, so two concurrent callers can't both miss and both INSERT.
+		return transaction(this.#db, async (trx) => {
+			const repo = this.useTransaction(trx);
+			const existing = await repo.#findBySearch(search, true);
+			if (existing) return existing;
+			return repo.create({ ...search, ...defaults });
+		});
 	}
 
 	/** Find a row or build an in-memory instance without persisting. */
@@ -684,23 +744,32 @@ export class BaseRepository<T extends BaseEntity> {
 		return e;
 	}
 
-	/** Atomic find-or-update-or-insert. */
+	/** Atomic find-or-update-or-insert (AdonisJS Lucid parity — locked + transactional). */
 	async updateOrCreate(
 		search: Record<string, unknown>,
 		values: Record<string, unknown>,
 	): Promise<T> {
-		const existing = await this.#findBySearch(search);
-		if (existing) {
-			for (const [k, v] of Object.entries(values)) existing.setProp(k, v);
-			await this.save(existing);
-			return existing;
-		}
-		return this.create({ ...search, ...values });
+		return transaction(this.#db, async (trx) => {
+			const repo = this.useTransaction(trx);
+			const existing = await repo.#findBySearch(search, true);
+			if (existing) {
+				for (const [k, v] of Object.entries(values)) existing.setProp(k, v);
+				await repo.save(existing);
+				return existing;
+			}
+			return repo.create({ ...search, ...values });
+		});
 	}
 
-	async #findBySearch(search: Record<string, unknown>): Promise<T | null> {
+	async #findBySearch(
+		search: Record<string, unknown>,
+		lock = false,
+	): Promise<T | null> {
 		let q = this.query();
 		for (const [k, v] of Object.entries(search)) q = q.where(k, v);
+		// `forUpdate()` row-locks the matched row so a concurrent updateOrCreate
+		// serializes behind it (no-op on SQLite, which serializes writes anyway).
+		if (lock) q = q.forUpdate();
 		return q.first();
 	}
 
@@ -1299,7 +1368,8 @@ export class BaseRepository<T extends BaseEntity> {
 			[fkProp]: parentIdValue,
 		});
 
-		// Shared "has" proxy methods (create/createMany/save/saveMany).
+		// Shared "has" proxy methods (create/createMany/save/saveMany +
+		// firstOrCreate/updateOrCreate scoped to this parent's FK).
 		const hasOps = {
 			async create(data: Record<string, unknown>) {
 				return relatedRepo.create(injectFk(data));
@@ -1307,6 +1377,27 @@ export class BaseRepository<T extends BaseEntity> {
 			async createMany(rows: Array<Record<string, unknown>>) {
 				return relatedRepo.createMany(rows.map(injectFk));
 			},
+			// Scope the search to the parent's FK column so the lookup only sees
+			// this parent's rows; inject the FK into the created/updated row. The
+			// related repo's firstOrCreate/updateOrCreate are atomic (txn + lock).
+			async firstOrCreate(
+				search: Record<string, unknown>,
+				defaults: Record<string, unknown> = {},
+			) {
+				return relatedRepo.firstOrCreate(
+					{ ...search, [fkCol]: parentIdValue },
+					injectFk(defaults),
+				);
+			},
+			async updateOrCreate(
+				search: Record<string, unknown>,
+				values: Record<string, unknown>,
+			) {
+				return relatedRepo.updateOrCreate(
+					{ ...search, [fkCol]: parentIdValue },
+					injectFk(values),
+				);
+			},
 			async save(related: BaseEntity) {
 				related.setProp(fkCol, parentIdValue);
 				related.setProp(fkProp, parentIdValue);
@@ -1646,9 +1737,42 @@ export class BaseRepository<T extends BaseEntity> {
 				}
 			};
 
+			// m2m create/save persist the related row THEN insert a pivot row —
+			// NOT `hasOps.injectFk`, which would write a bogus `<parent>_id` column
+			// onto the related table and never touch the pivot (silent corruption).
+			const relatedPkProp = getPrimaryKey(relatedClass) ?? "id";
+			const attachIds = (rows: BaseEntity[]): Promise<void> => {
+				if (rows.length === 0) return Promise.resolve();
+				const arg: Record<string, Record<string, unknown>> = {};
+				for (const r of rows) arg[String(r[relatedPkProp])] = {};
+				return attach(arg);
+			};
+			const m2mOps = {
+				async create(data: Record<string, unknown>): Promise<BaseEntity> {
+					const created = await relatedRepo.create(data);
+					await attachIds([created]);
+					return created;
+				},
+				async createMany(
+					rows: Array<Record<string, unknown>>,
+				): Promise<BaseEntity[]> {
+					const created = await relatedRepo.createMany(rows);
+					await attachIds(created);
+					return created;
+				},
+				async save(related: BaseEntity): Promise<void> {
+					await relatedRepo.save(related);
+					await attachIds([related]);
+				},
+				async saveMany(related: BaseEntity[]): Promise<BaseEntity[]> {
+					const saved = await relatedRepo.saveMany(related);
+					await attachIds(saved);
+					return saved;
+				},
+			};
 			const proxy: ManyToManyRelationProxy = {
 				type: "manyToMany",
-				...hasOps,
+				...m2mOps,
 				query: scopedQuery,
 				attach,
 				detach,
@@ -1674,6 +1798,8 @@ export class BaseRepository<T extends BaseEntity> {
 				type: "hasOne",
 				create: hasOps.create,
 				save: hasOps.save,
+				firstOrCreate: hasOps.firstOrCreate,
+				updateOrCreate: hasOps.updateOrCreate,
 				createMany: () => reject("createMany"),
 				saveMany: () => reject("saveMany"),
 				query: scopedQuery,