@c9up/atlas 0.2.5 → 0.2.7

package/src/ModelQuery.ts

@@ -2231,41 +2231,77 @@ export class ModelQuery<T extends BaseEntity> {
 
 	// --- Top-level scalar executors (Story 29.5) ---
 
-	/** `SELECT COUNT(col)` — executes and returns the scalar. `col` defaults to `*`. */
-	async count(column: string = "*"): Promise<number> {
+	/**
+	 * `COUNT` — a terminal scalar, or a chainable projection when given an
+	 * alias.
+	 *
+	 * Lucid types this `count: Aggregate<this>`: `count('* as total')` returns
+	 * the BUILDER and the value lands in `$extras`. The no-alias form returning
+	 * a number is atlas's own, and matches what `DatabaseQueryBuilder` already
+	 * does — same method, same two shapes, on both builders.
+	 */
+	count(aliasExpr: `${string} as ${string}`): this;
+	count(column?: string): Promise<number>;
+	count(column?: string): Promise<number> | this {
+		if (column !== undefined && ALIASED.test(column)) {
+			return this.#projectAggregate("COUNT", column);
+		}
+		const col = column ?? "*";
 		const expr =
-			column === "*"
+			col === "*"
 				? "COUNT(*)"
-				: `COUNT(${this.#quoteCol(this.#resolveColumn(column))})`;
-		return Number((await this.#runScalar(expr)) ?? 0);
+				: `COUNT(${this.#quoteCol(this.#resolveColumn(col))})`;
+		return this.#runScalar(expr).then((v) => Number(v ?? 0));
+	}
+
+	/** Project `FN(col) AS alias` and keep chaining — the Lucid `Aggregate` form. */
+	#projectAggregate(fn: string, aliasExpr: string): this {
+		const match = ALIASED.exec(aliasExpr.trim());
+		const column = (match?.[1] ?? "").trim();
+		const alias = match?.[2] ?? "";
+		const inner =
+			column === "*" ? "*" : this.#quoteCol(this.#resolveColumn(column));
+		this.#selectRaw.push({
+			sql: `${fn}(${inner}) AS ${this.#quoteAliasName(alias)}`,
+			params: [],
+		});
+		return this;
 	}
 
-	async sum(column: string): Promise<number | null> {
-		const v = await this.#runScalar(
+	sum(aliasExpr: `${string} as ${string}`): this;
+	sum(column: string): Promise<number | null>;
+	sum(column: string): Promise<number | null> | this {
+		if (ALIASED.test(column)) return this.#projectAggregate("SUM", column);
+		return this.#runScalar(
 			`SUM(${this.#quoteCol(this.#resolveColumn(column))})`,
-		);
-		return v === null || v === undefined ? null : Number(v);
+		).then((v) => (v === null || v === undefined ? null : Number(v)));
 	}
 
-	async avg(column: string): Promise<number | null> {
-		const v = await this.#runScalar(
+	avg(aliasExpr: `${string} as ${string}`): this;
+	avg(column: string): Promise<number | null>;
+	avg(column: string): Promise<number | null> | this {
+		if (ALIASED.test(column)) return this.#projectAggregate("AVG", column);
+		return this.#runScalar(
 			`AVG(${this.#quoteCol(this.#resolveColumn(column))})`,
-		);
-		return v === null || v === undefined ? null : Number(v);
+		).then((v) => (v === null || v === undefined ? null : Number(v)));
 	}
 
-	async min(column: string): Promise<number | null> {
-		const v = await this.#runScalar(
+	min(aliasExpr: `${string} as ${string}`): this;
+	min(column: string): Promise<number | null>;
+	min(column: string): Promise<number | null> | this {
+		if (ALIASED.test(column)) return this.#projectAggregate("MIN", column);
+		return this.#runScalar(
 			`MIN(${this.#quoteCol(this.#resolveColumn(column))})`,
-		);
-		return v === null || v === undefined ? null : Number(v);
+		).then((v) => (v === null || v === undefined ? null : Number(v)));
 	}
 
-	async max(column: string): Promise<number | null> {
-		const v = await this.#runScalar(
+	max(aliasExpr: `${string} as ${string}`): this;
+	max(column: string): Promise<number | null>;
+	max(column: string): Promise<number | null> | this {
+		if (ALIASED.test(column)) return this.#projectAggregate("MAX", column);
+		return this.#runScalar(
 			`MAX(${this.#quoteCol(this.#resolveColumn(column))})`,
-		);
-		return v === null || v === undefined ? null : Number(v);
+		).then((v) => (v === null || v === undefined ? null : Number(v)));
 	}
 
 	/**
@@ -4589,6 +4625,14 @@ export class ModelQuery<T extends BaseEntity> {
 		cursor?: string;
 		limit: number;
 		orderBy: string | string[];
+		/**
+		 * Which way the cursor walks. Default `asc`.
+		 *
+		 * `desc` is what a newest-first feed needs — the common case for cursor
+		 * pagination. The direction was hardcoded to `asc`, and any `orderBy`
+		 * already set on the query was overwritten by it without a word.
+		 */
+		direction?: "asc" | "desc";
 	}): Promise<{ items: T[]; nextCursor: string | null; hasMore: boolean }> {
 		// Keep BOTH forms: `props` (model property names) to read the cursor value
 		// off the hydrated entity, and `cols` (resolved DB columns) for the SQL
@@ -4600,6 +4644,7 @@ export class ModelQuery<T extends BaseEntity> {
 		if (cols.length === 0)
 			throw new Error("cursorPaginate requires at least one orderBy column");
 		const lim = Math.max(1, Math.floor(opts.limit));
+		const descending = opts.direction === "desc";
 		const clone = this.clone();
 
 		if (opts.cursor) {
@@ -4626,7 +4671,9 @@ export class ModelQuery<T extends BaseEntity> {
 				for (let i = 0; i < cols.length; i++) {
 					q.orWhere((inner) => {
 						for (let j = 0; j < i; j++) inner.where(cols[j], decoded.v[j]);
-						inner.where(cols[i], ">", decoded.v[i]);
+						// The comparison has to follow the walk: `>` reads forward
+						// through an ascending order, `<` through a descending one.
+						inner.where(cols[i], descending ? "<" : ">", decoded.v[i]);
 					});
 				}
 			});
@@ -4634,7 +4681,7 @@ export class ModelQuery<T extends BaseEntity> {
 
 		clone.#orderBys = cols.map((column) => ({
 			column,
-			direction: "asc" as const,
+			direction: descending ? ("desc" as const) : ("asc" as const),
 		}));
 		clone.#limit = lim + 1;
 		// `#doExec` (not `exec`) — cursorPaginate is an atlas-specific terminal, not a
@@ -5485,3 +5532,6 @@ export class ModelQuery<T extends BaseEntity> {
 		}
 	}
 }
+
+/** `col as alias` — the Lucid aggregate spelling. */
+const ALIASED = /^(.*?)\s+as\s+(\S+)$/i;

package/src/Transaction.ts

@@ -26,6 +26,15 @@ export interface TransactionClient
 		TransactionQueryBuilders {
 	commit(): Promise<void>;
 	rollback(): Promise<void>;
+	/**
+	 * Whether this transaction has already committed or rolled back (Lucid
+	 * `trx.isCompleted`).
+	 *
+	 * A helper handed a transaction cannot otherwise tell whether it is still
+	 * usable, and issuing a statement on a finished one fails at the driver with
+	 * an error that says nothing about the transaction.
+	 */
+	readonly isCompleted: boolean;
 	/**
 	 * Register a side effect to run AFTER the transaction is durable (Lucid
 	 * `trx.after('commit' | 'rollback', cb)`). A `commit` hook fires only once the
@@ -127,17 +136,25 @@ export async function openSavepoint(
 	const commitHooks: AfterHook[] = [];
 	const rollbackHooks: AfterHook[] = [];
 	const evt = makeTrxEvents();
+	// Flipped by whichever of commit/rollback runs first, so a helper handed
+	// this client can tell whether it is still usable (Lucid `isCompleted`).
+	let completed = false;
 	const base = {
 		execute: parent.execute.bind(parent),
 		query: parent.query.bind(parent),
+		get isCompleted(): boolean {
+			return completed;
+		},
 		async commit(): Promise<void> {
 			await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
+			completed = true;
 			evt.emit("commit"); // synchronous EventEmitter notification (this savepoint)
 			for (const hook of commitHooks) parent.after("commit", hook);
 			for (const hook of rollbackHooks) parent.after("rollback", hook);
 		},
 		async rollback(): Promise<void> {
 			await parent.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
+			completed = true;
 			try {
 				await parent.execute(`RELEASE SAVEPOINT ${name}`, []);
 			} catch {
@@ -250,16 +267,22 @@ export async function transaction<T>(
 	const rollbackHooks: AfterHook[] = [];
 	const evt = makeTrxEvents();
 
+	let completed = false;
 	const base = {
 		execute: db.execute.bind(db),
 		query: db.query.bind(db),
+		get isCompleted(): boolean {
+			return completed;
+		},
 		async commit() {
 			await db.execute("COMMIT", []);
+			completed = true;
 			evt.emit("commit"); // synchronous EventEmitter notification
 			await runAfterHooks(commitHooks);
 		},
 		async rollback() {
 			await db.execute("ROLLBACK", []);
+			completed = true;
 			evt.emit("rollback");
 			await runAfterHooks(rollbackHooks);
 		},

package/src/adapters/NapiDbAdapter.ts

@@ -291,6 +291,8 @@ export async function createNapiConnection(
 		const native = await db.begin(isolationLevel);
 		// Root (non-nested) transaction: after-hooks fire once the underlying
 		// COMMIT / ROLLBACK is durable (Lucid `trx.after(...)`), errors swallowed.
+		// Flipped by whichever of commit/rollback runs first (Lucid isCompleted).
+		let completed = false;
 		const commitHooks: AfterHook[] = [];
 		const rollbackHooks: AfterHook[] = [];
 		const evt = makeTrxEvents();
@@ -320,13 +322,18 @@ export async function createNapiConnection(
 				);
 				return JSON.parse(json, napiReviver) as T[];
 			},
+			get isCompleted(): boolean {
+				return completed;
+			},
 			async commit(): Promise<void> {
 				await native.commit();
+				completed = true;
 				evt.emit("commit"); // synchronous EventEmitter notification (Lucid trx.on)
 				await runAfterHooks(commitHooks);
 			},
 			async rollback(): Promise<void> {
 				await native.rollback();
+				completed = true;
 				evt.emit("rollback");
 				await runAfterHooks(rollbackHooks);
 			},

package/src/decorators/entity.ts

@@ -125,8 +125,12 @@ export interface ManyToManyOptions {
 	pivotTable: string;
 	/** Foreign key in the pivot table pointing to THIS entity (default: `${thisTable}_id`). */
 	foreignKey?: string;
+	/** AdonisJS spelling of {@link foreignKey}. Both are accepted. */
+	pivotForeignKey?: string;
 	/** Foreign key in the pivot table pointing to the RELATED entity (default: `${relatedTable}_id`). */
 	otherKey?: string;
+	/** AdonisJS spelling of {@link otherKey}. Both are accepted. */
+	pivotRelatedForeignKey?: string;
 	/**
 	 * The column ON THE RELATED model that `otherKey` references (Adonis Lucid
 	 * `relatedKey`). Defaults to the related model's primary key; override when the
@@ -533,7 +537,15 @@ export function ManyToMany(
 			propertyKey: String(propertyKey),
 			type: "manyToMany",
 			target,
-			pivot: options,
+			// Normalised HERE, once: AdonisJS names these `pivotForeignKey` /
+			// `pivotRelatedForeignKey`. Folding them in at the decorator means the
+			// half-dozen places that read the pivot keys never learn there are two
+			// spellings — and cannot each forget one.
+			pivot: {
+				...options,
+				foreignKey: options.foreignKey ?? options.pivotForeignKey,
+				otherKey: options.otherKey ?? options.pivotRelatedForeignKey,
+			},
 			// `localKey` selects which parent column the pivot FK references
 			// (default: the parent PK). Without copying it here the value the type
 			// accepts is silently dropped and the pivot always targets the PK.

package/src/decorators/hooks.ts

@@ -59,6 +59,24 @@ export interface HookArgs {
 	afterPaginate: Paginator<BaseEntity>;
 }
 
+/**
+ * The event half of a hook kind — what `Model.before(event)` takes. Lucid
+ * spells these lower-case (`'save'`, `'create'`) and prefixes them itself.
+ */
+export type HookEvent =
+	| "save"
+	| "create"
+	| "update"
+	| "delete"
+	| "find"
+	| "fetch"
+	| "paginate";
+
+/** `'save'` → `'Save'`, so `before` + event names the registry key. */
+export function capitalize<E extends string>(event: E): Capitalize<E> {
+	return (event.charAt(0).toUpperCase() + event.slice(1)) as Capitalize<E>;
+}
+
 /** A hook handler is a static function that receives the kind-specific arg. */
 export type HookHandler<K extends HookKind = HookKind> = (
 	arg: HookArgs[K],
@@ -169,3 +187,52 @@ export async function fireHooks<K extends HookKind>(
 		await handler(arg);
 	}
 }
+
+/**
+ * Register a hook at RUNTIME, without a decorator — Lucid's
+ * `Model.before(event, handler)` / `Model.after(event, handler)`, which do
+ * `this.$hooks.add(\`before:${event}\`, handler)`.
+ *
+ * The decorators cover the common case (a static method on the entity), but a
+ * hook that comes from somewhere else — a plugin, a test, a package wiring
+ * itself into an app's models — has no class body to decorate. Lucid supports
+ * both; so does this.
+ *
+ * Handlers land in the SAME per-class registry the decorators write to, so the
+ * ordering rule is unchanged: parent classes fire before child classes, and
+ * within a class, registration order.
+ */
+export function addHook<K extends HookKind>(
+	entityClass: object,
+	kind: K,
+	handler: HookHandler<K>,
+): void {
+	if (!isHookHandler(handler)) {
+		throw new Error(`${kind} hook must be a function`);
+	}
+	const registry = getOwnRegistry(entityClass);
+	const list: HookHandler[] = registry[kind] ?? [];
+	list.push(handler as HookHandler);
+	registry[kind] = list;
+}
+
+/**
+ * Drop a handler registered with {@link addHook} (or a decorator, if you hold
+ * the same reference). Returns whether one was removed — a test that adds a
+ * hook needs a way to take it back out.
+ */
+export function removeHook<K extends HookKind>(
+	entityClass: object,
+	kind: K,
+	handler: HookHandler<K>,
+): boolean {
+	const registry = Reflect.getOwnMetadata(HOOKS_KEY, entityClass) as
+		| HookRegistry
+		| undefined;
+	const list = registry?.[kind];
+	if (!list) return false;
+	const index = list.indexOf(handler as HookHandler);
+	if (index === -1) return false;
+	list.splice(index, 1);
+	return true;
+}

package/src/index.ts

@@ -99,7 +99,10 @@ export {
 	PrimaryKey,
 	SoftDeletes,
 } from "./decorators/entity.js";
+// Runtime hook registration — what `BaseEntity.before()/after()` call, exported
+// for a plugin that wires hooks into models it does not own.
 export {
+	addHook,
 	afterCreate,
 	afterDelete,
 	afterFetch,
@@ -114,6 +117,10 @@ export {
 	beforePaginate,
 	beforeSave,
 	beforeUpdate,
+	type HookEvent,
+	type HookHandler,
+	type HookKind,
+	removeHook,
 } from "./decorators/hooks.js";
 export type { ScopeFn } from "./decorators/scope.js";
 export { scope } from "./decorators/scope.js";
@@ -173,7 +180,7 @@ export type {
 export { MigrationRunner } from "./schema/MigrationRunner.js";
 export type { DefaultValue } from "./schema/raw.js";
 export type { ColumnDefinition, ColumnType } from "./schema/SchemaBuilder.js";
-export { Schema, TableBuilder } from "./schema/SchemaBuilder.js";
+export { ColumnBuilder, Schema, TableBuilder } from "./schema/SchemaBuilder.js";
 export {
 	checkSchema,
 	formatSchemaFindings,

package/src/query/DatabaseQueryBuilder.ts

@@ -890,6 +890,59 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 		return this;
 	}
 
+	// ─── HAVING EXISTS (Lucid/Knex) ───────────────────────────
+	// A correlated subquery in HAVING is how you filter GROUPS by something
+	// outside the aggregate — "groups that still have an open order", which no
+	// combination of `having(count)` can express.
+
+	/** HAVING EXISTS (subquery). */
+	havingExists(sub: SubqueryArg): this {
+		return this.#pushHavingExists("and", false, sub);
+	}
+
+	/** Alias of {@link havingExists} — AND is the default. */
+	andHavingExists(sub: SubqueryArg): this {
+		return this.#pushHavingExists("and", false, sub);
+	}
+
+	/** OR EXISTS in HAVING. */
+	orHavingExists(sub: SubqueryArg): this {
+		return this.#pushHavingExists("or", false, sub);
+	}
+
+	/** HAVING NOT EXISTS (subquery). */
+	havingNotExists(sub: SubqueryArg): this {
+		return this.#pushHavingExists("and", true, sub);
+	}
+
+	/** Alias of {@link havingNotExists}. */
+	andHavingNotExists(sub: SubqueryArg): this {
+		return this.#pushHavingExists("and", true, sub);
+	}
+
+	/** OR NOT EXISTS in HAVING. */
+	orHavingNotExists(sub: SubqueryArg): this {
+		return this.#pushHavingExists("or", true, sub);
+	}
+
+	#pushHavingExists(
+		type: "and" | "or",
+		negated: boolean,
+		sub: SubqueryArg,
+	): this {
+		// Compiled to a raw HAVING rather than a new clause kind: the engine
+		// already carries raw havings with their bindings, and EXISTS has no
+		// operator/value to model.
+		const { sql, params } = this.#resolveSub(sub).#compiledNative();
+		this.#havings.push({
+			kind: "raw",
+			sql: `${negated ? "NOT EXISTS" : "EXISTS"} (${sql})`,
+			bindings: params,
+			type,
+		});
+		return this;
+	}
+
 	/** `INNER JOIN` — alias of {@link innerJoin} (Lucid/Knex `join`). */
 	join(table: string, left: string, right: string): this;
 	join(table: string, left: string, operator: string, right: string): this;
@@ -1980,6 +2033,47 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 		return this;
 	}
 
+	// ─── Clearing clauses (Lucid/Knex `clear*`) ───────────────
+	// A builder handed to a helper that added a filter, an order or a slice can
+	// be reset clause by clause instead of rebuilt from scratch — which is what
+	// a shared scope or a reusable base query needs.
+
+	/** Drop every selected column, back to `*`. */
+	clearSelect(): this {
+		this.#selects = [];
+		return this;
+	}
+
+	/** Drop every WHERE, including the raw and grouped ones. */
+	clearWhere(): this {
+		this.#wheres = [];
+		return this;
+	}
+
+	/** Drop every ORDER BY. */
+	clearOrder(): this {
+		this.#orderBys = [];
+		return this;
+	}
+
+	/** Drop every HAVING. */
+	clearHaving(): this {
+		this.#havings = [];
+		return this;
+	}
+
+	/** Drop the LIMIT. */
+	clearLimit(): this {
+		this.#limit = undefined;
+		return this;
+	}
+
+	/** Drop the OFFSET. */
+	clearOffset(): this {
+		this.#offset = undefined;
+		return this;
+	}
+
 	/** The table, qualified with a schema when {@link withSchema} was used. */
 	#qualifiedTable(): string {
 		return this.#schema ? `${this.#schema}.${this.#table}` : this.#table;
@@ -2672,19 +2766,36 @@ export class DatabaseQueryBuilder<T = Record<string, unknown>> {
 			},
 			this.#dialect,
 		);
+		// A flat `SELECT COUNT(*) … GROUP BY x` returns one row PER GROUP, each
+		// holding that group's size — so `rows[0]` would be the first group's
+		// size, not the number of rows. Wrap the grouped query and count ITS
+		// rows, which is what ModelQuery.paginate already does.
+		const countSql =
+			this.#groupBys.length > 0
+				? `SELECT COUNT(*) AS aggregate FROM (${this.#compiledNative().sql}) AS __paginate_count`
+				: countCompiled.statements[0];
+		const countParams =
+			this.#groupBys.length > 0
+				? this.#compiledNative().params
+				: countCompiled.params;
 		const countRows = await this.#exec.query<{
 			aggregate: number | string | null;
-		}>(
-			countCompiled.statements[0],
-			countCompiled.params,
-			this.#queryMeta("paginate"),
-		);
+		}>(countSql, countParams, this.#queryMeta("paginate"));
 		const total = Number(countRows[0]?.aggregate ?? 0);
 
+		// Restore the slice afterwards: `paginate()` is a read, and a builder
+		// left carrying a LIMIT silently truncated the next query run off it.
+		const previousLimit = this.#limit;
+		const previousOffset = this.#offset;
 		this.#limit = pp;
 		this.#offset = (p - 1) * pp;
-		const items = await this.exec();
-		return new Paginator<T>(items, { total, perPage: pp, currentPage: p });
+		try {
+			const items = await this.exec();
+			return new Paginator<T>(items, { total, perPage: pp, currentPage: p });
+		} finally {
+			this.#limit = previousLimit;
+			this.#offset = previousOffset;
+		}
 	}
 
 	/** Thenable, so `await db.from('users').where(...)` resolves to the rows. */

package/src/schema/SchemaBuilder.ts

@@ -4,11 +4,12 @@
  * The classes were split into one-class-per-file:
  *   - {@link Schema}        → ./Schema.ts
  *   - {@link TableBuilder}  → ./TableBuilder.ts
+ *   - {@link ColumnBuilder} → ./TableBuilder.ts
  *   - shared types          → ./types.ts
  *
  * @implements FR34
  */
 
 export { Schema } from "./Schema.js";
-export { TableBuilder } from "./TableBuilder.js";
+export { ColumnBuilder, TableBuilder } from "./TableBuilder.js";
 export type { ColumnDefinition, ColumnType, IndexDefinition } from "./types.js";