@c9up/atlas 0.1.18 → 0.2.0

package/src/decorators/entity.ts

@@ -10,6 +10,7 @@ import {
 	COMPUTED_KEY,
 	type ColumnSerializeConfig,
 } from "../metadata-keys.js";
+import { getNamingStrategy } from "../naming/NamingStrategy.js";
 
 const ENTITY_KEY = Symbol("atlas:entity");
 const COLUMNS_KEY = Symbol("atlas:columns");
@@ -62,8 +63,14 @@ export interface ColumnAdapter {
 	 *
 	 * MUST stay synchronous; the bind layer cannot await before handing values
 	 * to the Rust DML compiler. Returning a Promise throws.
+	 *
+	 * Signature mirrors Adonis Lucid: `(value, attribute, model)`. `attribute` is
+	 * the model property key; `model` is the entity instance being persisted, or
+	 * `undefined` on query-builder paths that carry no instance (e.g.
+	 * `updateWhere`). Both extra args are optional — a one-argument adapter keeps
+	 * working unchanged.
 	 */
-	prepare?: (value: unknown) => unknown;
+	prepare?: (value: unknown, attribute?: string, model?: unknown) => unknown;
 	/**
 	 * Transform the raw DB value into the model attribute (DB → model). Mirror
 	 * of Adonis Lucid's `@column.consume`. For entity columns, runs in
@@ -76,8 +83,12 @@ export interface ColumnAdapter {
 	 * null/undefined inputs to preserve nullable semantics.
 	 *
 	 * MUST stay synchronous (same constraint as `prepare`).
+	 *
+	 * Signature mirrors Adonis Lucid: `(value, attribute, model)`. `attribute` is
+	 * the model property key; `model` is the entity being hydrated. Both extra
+	 * args are optional — a one-argument adapter keeps working unchanged.
 	 */
-	consume?: (value: unknown) => unknown;
+	consume?: (value: unknown, attribute?: string, model?: unknown) => unknown;
 }
 
 export interface ColumnMetadata extends ColumnAdapter {
@@ -86,17 +97,25 @@ export interface ColumnMetadata extends ColumnAdapter {
 	nullable?: boolean;
 	default?: unknown;
 	serializeAs?: string | null;
-	serialize?: (value: unknown) => unknown;
+	serialize?: (value: unknown, attribute?: string, model?: unknown) => unknown;
+	/** Explicit DB column name override (AdonisJS Lucid `columnName`). */
+	columnName?: string;
 }
 
 export interface ColumnOptions extends ColumnAdapter {
 	type?: string;
 	nullable?: boolean;
 	default?: unknown;
+	/**
+	 * Map this property to an explicitly-named DB column (AdonisJS Lucid
+	 * `columnName`), instead of the default `camelCase → snake_case` convention.
+	 * For legacy/non-conventional schemas, e.g. `@Column({ columnName: 'USR_MAIL' })`.
+	 */
+	columnName?: string;
 	/** Rename this column at `toJSON` time. Use `null` to hide it entirely. */
 	serializeAs?: string | null;
 	/** Transform the value at `toJSON` time (e.g. mask a phone number, coerce a Date). */
-	serialize?: (value: unknown) => unknown;
+	serialize?: (value: unknown, attribute?: string, model?: unknown) => unknown;
 }
 
 type Constructor = new (...args: unknown[]) => unknown;
@@ -202,6 +221,7 @@ export function Column(options?: ColumnOptions): PropertyDecorator {
 				serialize: options?.serialize,
 				prepare: options?.prepare,
 				consume: options?.consume,
+				columnName: options?.columnName,
 			});
 			Reflect.defineMetadata(COLUMNS_KEY, columns, target.constructor);
 		}
@@ -445,7 +465,12 @@ export function HasMany(
 	};
 }
 
-/** @HasOneThrough(() => Related, () => Through, { firstKey, secondKey, localKey, secondLocalKey, onQuery }) */
+/**
+ * `@HasOneThrough(() => Related, () => Through, { firstKey, secondKey, localKey, secondLocalKey, onQuery })`
+ *
+ * An atlas addition — Lucid has no hasOneThrough relation. Same two-hop
+ * traversal as {@link HasManyThrough}, returning a single row.
+ */
 export function HasOneThrough(
 	target: () => Constructor,
 	through: () => Constructor,
@@ -490,6 +515,10 @@ export function ManyToMany(
 			type: "manyToMany",
 			target,
 			pivot: options,
+			// `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.
+			localKey: options.localKey,
 			onQuery: options.onQuery,
 			serializeAs: options.serializeAs,
 		});
@@ -510,13 +539,31 @@ export function getEntityMetadata(
 	return Reflect.getMetadata(ENTITY_KEY, target);
 }
 
+/**
+ * Return the class's `@Entity` metadata, SYNTHESIZING it when the decorator is
+ * absent: the table name is inferred from the class name via the naming strategy
+ * (or an explicit `static table`). AdonisJS Lucid parity — a model needs no
+ * explicit `@Entity('table')`. Used by both `BaseModel` and the `BaseRepository`
+ * constructor so the Data-Mapper and Active-Record paths share one convention.
+ */
+export function ensureEntityMetadata(target: Constructor): EntityMetadata {
+	const existing = getEntityMetadata(target);
+	if (existing) return existing;
+	const staticTable = (target as { table?: string }).table;
+	const table = staticTable ?? getNamingStrategy(target).tableName(target.name);
+	Entity(table)(target);
+	return getEntityMetadata(target) ?? { tableName: table };
+}
+
 /** Get column metadata for a class (returns a copy). */
 export function getColumnMetadata(target: Constructor): ColumnMetadata[] {
 	return [...(Reflect.getMetadata(COLUMNS_KEY, target) ?? [])];
 }
 
-/** Get primary key property name. */
+/** Get primary key property name. A `static primaryKey` (AdonisJS Lucid) wins over the `@PrimaryKey()` decorator. */
 export function getPrimaryKey(target: Constructor): string | undefined {
+	const staticPk = (target as { primaryKey?: string }).primaryKey;
+	if (staticPk) return staticPk;
 	return Reflect.getMetadata(PRIMARY_KEY, target);
 }
 

package/src/events.ts

@@ -0,0 +1,112 @@
+/**
+ * Query observability — atlas's equivalent of Lucid's `db:query` event.
+ *
+ * Agnostic by design: atlas cannot import the framework's emitter (it is a
+ * standalone package), so it owns a tiny listener registry instead. An
+ * integration package bridges it to whatever emitter the app uses:
+ *
+ *     onDbQuery((event) => emitter.emit('db:query', event))
+ *
+ * Emission is opt-in. It costs a `performance.now()` pair per query, so it only
+ * happens when a connection is configured with `debug: true` or a single query
+ * asks via `.debug()` — and even then, only if someone is listening.
+ */
+
+/**
+ * A single executed SQL statement. Mirrors Lucid's `db:query` payload, minus
+ * the fields that only make sense inside AdonisJS.
+ */
+export interface DbQueryEvent {
+	/** The SQL as sent to the driver, placeholders included. */
+	sql: string;
+	/** The bound parameters. Never interpolated into `sql`. */
+	bindings: readonly unknown[];
+	/** Wall-clock duration in milliseconds, including the NAPI round-trip. */
+	duration: number;
+	/** Connection name, when the app named it. */
+	connection?: string;
+	/** Entity class name, when the query came from a repository/model. */
+	model?: string;
+	/** The call that produced it (`exec`, `first`, `paginate`, …). */
+	method?: string;
+	/** True for schema statements (migrations), false for DML/queries. */
+	ddl?: boolean;
+	/** True when the statement ran inside an interactive transaction. */
+	inTransaction?: boolean;
+	/** Set when the statement threw — the event is emitted either way. */
+	error?: Error;
+}
+
+export type DbQueryListener = (event: DbQueryEvent) => void;
+
+const listeners = new Set<DbQueryListener>();
+
+/**
+ * Subscribe to every observed query. Returns an unsubscribe function.
+ *
+ * A listener that throws would otherwise take down the query that triggered it,
+ * so throws are swallowed — observability must never change behaviour.
+ */
+export function onDbQuery(listener: DbQueryListener): () => void {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+
+/** Remove every listener. Intended for test teardown. */
+export function clearDbQueryListeners(): void {
+	listeners.clear();
+}
+
+/**
+ * Whether anyone is listening. Checked before timing a query so the
+ * instrumentation costs nothing when unused.
+ */
+export function hasDbQueryListeners(): boolean {
+	return listeners.size > 0;
+}
+
+/** Emit to every listener. Package-internal. */
+export function emitDbQuery(event: DbQueryEvent): void {
+	for (const listener of listeners) {
+		try {
+			listener(event);
+		} catch {
+			// A broken listener must not fail the query it is reporting on.
+		}
+	}
+}
+
+/**
+ * Render a query event as a single log line (Lucid's `prettyPrint`).
+ *
+ * The bindings are appended as JSON, NOT interpolated into the SQL: an
+ * interpolated line reads like runnable SQL while having none of the escaping
+ * that made the real statement safe, and it is exactly the string someone
+ * copies into a console later.
+ */
+export function prettyPrintQuery(event: DbQueryEvent): string {
+	const parts = [`${event.duration.toFixed(2)}ms`];
+	if (event.connection) parts.push(event.connection);
+	if (event.model) parts.push(event.model);
+	if (event.method) parts.push(event.method);
+	if (event.inTransaction) parts.push("trx");
+	if (event.error) parts.push(`ERROR: ${event.error.message}`);
+
+	const head = `[atlas] ${parts.join(" ")}`;
+	const bindings =
+		event.bindings.length > 0 ? ` -- ${safeJson(event.bindings)}` : "";
+	return `${head} ${event.sql}${bindings}`;
+}
+
+/** JSON that can't throw on a circular / non-serialisable binding. */
+function safeJson(value: unknown): string {
+	try {
+		return JSON.stringify(value, (_k, v) =>
+			typeof v === "bigint" ? `${v}n` : v,
+		);
+	} catch {
+		return "[unserialisable bindings]";
+	}
+}

package/src/index.ts

@@ -10,14 +10,27 @@ export { SQLITE_PROD_PRAGMAS } from "./AtlasProvider.js";
 export type {
 	AsyncDatabaseConnection,
 	ConnectRetryOptions,
+	ObservabilityOptions,
+	QueryMeta,
 } 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 { BaseRepository } from "./BaseRepository.js";
 export { defineConfig } from "./config.js";
 export { configure } from "./configure.js";
+export {
+	dbWipeCommand,
+	type MigrationCommandOptions,
+	makeMigrationCommand,
+	migrationRefreshCommand,
+	migrationResetCommand,
+	migrationRollbackCommand,
+	migrationRunCommand,
+	migrationStatusCommand,
+} from "./console/migrationCommands.js";
 export {
 	type AtlasCommand,
 	schemaCheckCommand,
@@ -77,6 +90,12 @@ export {
 	OptimisticLockError,
 	RelationNotLoadedError,
 } from "./errors.js";
+export type { DbQueryEvent, DbQueryListener } from "./events.js";
+export {
+	clearDbQueryListeners,
+	onDbQuery,
+	prettyPrintQuery,
+} from "./events.js";
 export {
 	isAtlasStrictMode,
 	ModelQuery,

package/src/metadata-keys.ts

@@ -17,6 +17,7 @@ export const COLUMN_SERIALIZE_KEY = Symbol.for("atlas:columnSerialize");
 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;
+	/** Transform function applied to the value at toJSON time. Signature mirrors
+	 * Adonis Lucid: `(value, attribute, model)`; extra args optional. */
+	serialize?: (value: unknown, attribute?: string, model?: unknown) => unknown;
 }

package/src/naming/NamingStrategy.ts

@@ -38,6 +38,12 @@ export interface NamingStrategy {
 	): string;
 	/** Default pivot table name for a manyToMany relation. */
 	relationPivotTable(aClass: string, bClass: string): string;
+	/**
+	 * Remap the pagination `meta` key names emitted by `Paginator.toJSON()`
+	 * (AdonisJS Lucid `paginationMetaKeys`), e.g. `{ total: 'count', perPage:
+	 * 'per_page' }`. Optional — omitted keys keep their default name.
+	 */
+	paginationMetaKeys?(): Record<string, string>;
 }
 
 /**
@@ -84,6 +90,23 @@ export class CamelCaseNamingStrategy implements NamingStrategy {
 		const [x, y] = [camelToSnake(aClass), camelToSnake(bClass)].sort();
 		return `${x}_${y}`;
 	}
+
+	paginationMetaKeys(): Record<string, string> {
+		// snake_case, matching Adonis Lucid's default paginator meta shape — even
+		// though model attributes serialize as camelCase, Lucid emits pagination
+		// meta in snake_case. Override this method to customize.
+		return {
+			total: "total",
+			perPage: "per_page",
+			currentPage: "current_page",
+			lastPage: "last_page",
+			firstPage: "first_page",
+			firstPageUrl: "first_page_url",
+			lastPageUrl: "last_page_url",
+			nextPageUrl: "next_page_url",
+			previousPageUrl: "previous_page_url",
+		};
+	}
 }
 
 /** The default singleton — used when an entity doesn't override `static namingStrategy`. */

package/src/schema/Migration.ts

@@ -6,6 +6,7 @@
 
 import type { AtlasDialect } from "../query/native.js";
 import { RawSql } from "../query/QueryBuilder.js";
+import type { CatalogConnection } from "./catalog.js";
 import { Schema } from "./SchemaBuilder.js";
 
 /**
@@ -29,9 +30,18 @@ import { Schema } from "./SchemaBuilder.js";
  *     }
  *   }
  */
+/**
+ * A deferred operation registered with `this.defer()`. Runs after the
+ * migration's schema statements, with a live connection handle (execute/query).
+ */
+export type DeferredMigrationCallback = (
+	db: CatalogConnection,
+) => Promise<void> | void;
+
 export abstract class Migration {
 	readonly schema: Schema;
 	readonly #dialect: AtlasDialect;
+	#deferred: DeferredMigrationCallback[] = [];
 
 	constructor(dialect?: AtlasDialect) {
 		this.schema = new Schema(dialect);
@@ -41,6 +51,27 @@ export abstract class Migration {
 		this.#dialect = dialect ?? "sqlite";
 	}
 
+	/**
+	 * Register a callback to run AFTER this migration's schema statements execute
+	 * (Adonis Lucid `this.defer`). Typically used to seed data into a table the
+	 * same migration just created. The callback gets a live connection handle.
+	 *
+	 * Note: deferred callbacks run after the schema statements have committed, so
+	 * they are outside the schema transaction (atlas builds schema as a batch);
+	 * the migration is only recorded as applied once every deferred callback
+	 * succeeds. Make deferred work idempotent.
+	 */
+	defer(callback: DeferredMigrationCallback): void {
+		this.#deferred.push(callback);
+	}
+
+	/** @internal Return and clear the deferred callbacks — called by the runner. */
+	consumeDeferred(): DeferredMigrationCallback[] {
+		const deferred = this.#deferred;
+		this.#deferred = [];
+		return deferred;
+	}
+
 	/** Apply the migration. */
 	abstract up(): Promise<void> | void;
 
@@ -69,15 +100,23 @@ export abstract class Migration {
 		);
 	}
 
-	/** Get the SQL statements generated by this migration. */
-	async getUpSQL(): Promise<string[]> {
+	/**
+	 * Get the SQL statements generated by this migration. A `connection` (passed
+	 * by the runner) is bound to the schema so `this.schema.hasTable()` /
+	 * `hasColumn()` can query the live catalog from inside `up`/`down`.
+	 */
+	async getUpSQL(connection?: CatalogConnection): Promise<string[]> {
+		if (connection) this.schema.bindConnection(connection);
 		this.schema.reset();
+		this.#deferred = [];
 		await this.up();
 		return this.schema.toSQL();
 	}
 
-	async getDownSQL(): Promise<string[]> {
+	async getDownSQL(connection?: CatalogConnection): Promise<string[]> {
+		if (connection) this.schema.bindConnection(connection);
 		this.schema.reset();
+		this.#deferred = [];
 		await this.down();
 		return this.schema.toSQL();
 	}