@c9up/atlas 0.1.19 → 0.2.1

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;
@@ -108,6 +127,12 @@ export interface ManyToManyOptions {
 	foreignKey?: string;
 	/** Foreign key in the pivot table pointing to the RELATED entity (default: `${relatedTable}_id`). */
 	otherKey?: string;
+	/**
+	 * The column ON THE RELATED model that `otherKey` references (Adonis Lucid
+	 * `relatedKey`). Defaults to the related model's primary key; override when the
+	 * pivot points at a non-PK column of the related side.
+	 */
+	relatedKey?: string;
 	/** Pivot extra columns to project into `$extras.pivot_<col>` on loaded relations (Story 31.8). */
 	pivotColumns?: string[];
 	/** Auto-write `created_at`/`updated_at` on `attach`/`sync` (Story 31.8). */
@@ -119,8 +144,7 @@ export interface ManyToManyOptions {
 	 * `@Column({ prepare, consume })` for entity columns: `prepare` runs on
 	 * every `attach()` / `sync()` write, before the value reaches the SQL bind
 	 * layer; `consume` runs on every load that projects the extra into
-	 * `$extras.pivot_<col>` (when the projection mechanism lands — currently
-	 * the load-side hook is dormant).
+	 * `$extras.pivot_<col>` (Adonis Lucid signature `(value, attribute, model)`).
 	 *
 	 * Keys are pivot-row column names as written in the SQL (e.g. `amount`);
 	 * adapters are reused verbatim from `@c9up/atom/atlas` and friends so a
@@ -202,6 +226,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 +470,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,12 +520,27 @@ 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,
 		});
 	};
 }
 
+// camelCase aliases matching Adonis Lucid's decorator naming (`@belongsTo`,
+// `@hasMany`, `@manyToMany`, …), alongside atlas's PascalCase originals — so a
+// migration/model copied from Lucid resolves without renaming. Same decorators,
+// same options; just the Lucid-idiomatic spelling.
+export const belongsTo = BelongsTo;
+export const hasOne = HasOne;
+export const hasMany = HasMany;
+export const hasOneThrough = HasOneThrough;
+export const hasManyThrough = HasManyThrough;
+export const manyToMany = ManyToMany;
+
 function addRelation(target: object, relation: RelationMetadata): void {
 	const relations: RelationMetadata[] =
 		Reflect.getOwnMetadata(RELATIONS_KEY, target) ?? [];
@@ -510,13 +555,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/decorators/hooks.ts

@@ -20,7 +20,7 @@
 
 import "reflect-metadata";
 import type { BaseEntity } from "../BaseEntity.js";
-import type { ModelQuery } from "../ModelQuery.js";
+import type { ModelQuery, Paginator } from "../ModelQuery.js";
 
 /** All hook kinds Atlas supports — mirrors Lucid's surface. */
 export type HookKind =
@@ -53,8 +53,10 @@ export interface HookArgs {
 	afterFind: BaseEntity | null;
 	beforeFetch: ModelQuery<BaseEntity>;
 	afterFetch: BaseEntity[];
-	beforePaginate: ModelQuery<BaseEntity>;
-	afterPaginate: BaseEntity[];
+	// Adonis Lucid: beforePaginate receives the [countQuery, query] tuple (mutate
+	// both to keep count and results in sync); afterPaginate receives the paginator.
+	beforePaginate: [ModelQuery<BaseEntity>, ModelQuery<BaseEntity>];
+	afterPaginate: Paginator<BaseEntity>;
 }
 
 /** A hook handler is a static function that receives the kind-specific arg. */

package/src/events.ts

@@ -0,0 +1,117 @@
+/**
+ * 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;
+	/**
+	 * Arbitrary metadata a caller attached via `query.reporterData({...})`
+	 * (Adonis Lucid `reporterData`) — request id, user id, feature flag, …
+	 */
+	reporterData?: Record<string, unknown>;
+}
+
+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/factories.ts

@@ -0,0 +1,10 @@
+/**
+ * `@c9up/atlas/factories` — Adonis Lucid `@adonisjs/lucid/factories` parity
+ * subpath. The model factory: `Factory.define(Model, cb).build()` (or the
+ * `factory()` shorthand) for generating and persisting test data.
+ */
+export {
+	type FactoryCommandOptions,
+	makeFactoryCommand,
+} from "./console/factoryCommands.js";
+export { Factory, type FactoryBuilder, factory } from "./testing/Factory.js";

package/src/index.ts

@@ -10,18 +10,59 @@ 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 {
-	type AtlasCommand,
+	type ArgumentMetaData,
+	argument,
+	type CommandOptions,
+	type FlagMetaData,
+	flag,
+} from "./console/contract.js";
+export {
+	type FactoryCommandOptions,
+	makeFactoryCommand,
+} from "./console/factoryCommands.js";
+export {
+	dbWipeCommand,
+	type MigrationCommandOptions,
+	makeMigrationCommand,
+	migrationFreshCommand,
+	migrationRefreshCommand,
+	migrationResetCommand,
+	migrationRollbackCommand,
+	migrationRunCommand,
+	migrationStatusCommand,
+	migrationUnlockCommand,
+} from "./console/migrationCommands.js";
+export {
+	type AtlasCommandClass,
 	schemaCheckCommand,
 } from "./console/schemaCheckCommand.js";
+export {
+	type SchemaDumpCommandOptions,
+	schemaDumpCommand,
+} from "./console/schemaDumpCommand.js";
+export {
+	generateSchemaFile,
+	renderSchemaFile,
+	type SchemaGenerateOptions,
+	schemaGenerateCommand,
+} from "./console/schemaGenerateCommand.js";
+export {
+	dbSeedCommand,
+	makeSeederCommand,
+	type SeederCommandOptions,
+} from "./console/seederCommands.js";
 export type {
 	ColumnAdapter,
 	ColumnMetadata,
@@ -34,6 +75,7 @@ export type {
 } from "./decorators/entity.js";
 export {
 	BelongsTo,
+	belongsTo,
 	Column,
 	column,
 	computed,
@@ -47,8 +89,13 @@ export {
 	HasManyThrough,
 	HasOne,
 	HasOneThrough,
+	hasMany,
+	hasManyThrough,
+	hasOne,
+	hasOneThrough,
 	hasSoftDeletes,
 	ManyToMany,
+	manyToMany,
 	PrimaryKey,
 	SoftDeletes,
 } from "./decorators/entity.js";
@@ -77,6 +124,12 @@ export {
 	OptimisticLockError,
 	RelationNotLoadedError,
 } from "./errors.js";
+export type { DbQueryEvent, DbQueryListener } from "./events.js";
+export {
+	clearDbQueryListeners,
+	onDbQuery,
+	prettyPrintQuery,
+} from "./events.js";
 export {
 	isAtlasStrictMode,
 	ModelQuery,
@@ -103,7 +156,9 @@ export {
 	type IntrospectedColumn,
 	introspectTable,
 } from "./schema/introspect.js";
-export { Migration } from "./schema/Migration.js";
+// `BaseSchema` is Lucid's name for the migration base class; `Migration` is the
+// atlas alias kept for back-compat. Prefer `extends BaseSchema` (AdonisJS parity).
+export { Migration, Migration as BaseSchema } from "./schema/Migration.js";
 export type {
 	DatabaseAdapter,
 	MigrationRecord,
@@ -124,6 +179,17 @@ export {
 	typesCompatible,
 	verifySchema,
 } from "./schema/SchemaCheck.js";
+export {
+	type PgForeignKey,
+	readSchemaDumpManifest,
+	renderPgCreateTable,
+	renderPgForeignKeyDdl,
+	SchemaDumper,
+	type SchemaDumperOptions,
+	type SchemaDumpManifest,
+	type SchemaDumpResult,
+	schemaDumpManifestPath,
+} from "./schema/SchemaDumper.js";
 export {
 	BaseSeeder,
 	runSeederDirectory,
@@ -133,4 +199,4 @@ export {
 export type { TransactionClient } from "./Transaction.js";
 export { transaction } from "./Transaction.js";
 export { truncateAll, useTransaction } from "./testing/DatabaseCleanup.js";
-export { factory } from "./testing/Factory.js";
+export { Factory, factory } from "./testing/Factory.js";

package/src/lucid-schema.ts

@@ -0,0 +1,22 @@
+/**
+ * `@c9up/atlas/schema` — Adonis Lucid `@adonisjs/lucid/schema` parity subpath.
+ *
+ * The migration base class ({@link Migration}, Lucid's `BaseSchema`), the schema
+ * builder and the table builder — everything for authoring migrations. (The file
+ * is named `lucid-schema` to avoid colliding with the `schema/` source folder;
+ * the public subpath is `@c9up/atlas/schema`.)
+ */
+export { RawSql } from "./query/QueryBuilder.js";
+export * from "./schema/Migration.js";
+// Lucid's name for the migration base class (`extends BaseSchema`).
+export { Migration as BaseSchema } from "./schema/Migration.js";
+export * from "./schema/Schema.js";
+export {
+	readSchemaDumpManifest,
+	SchemaDumper,
+	type SchemaDumperOptions,
+	type SchemaDumpManifest,
+	type SchemaDumpResult,
+	schemaDumpManifestPath,
+} from "./schema/SchemaDumper.js";
+export * from "./schema/TableBuilder.js";

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

@@ -0,0 +1,13 @@
+/**
+ * `@c9up/atlas/orm` — Adonis Lucid `@adonisjs/lucid/orm` parity subpath.
+ *
+ * The Active Record model, the Data Mapper repository, the column/relation
+ * decorators and the model lifecycle hooks — everything for defining and
+ * querying models. Import organisation mirrors Lucid; the symbols are the same
+ * ones re-exported from the package root (`@c9up/atlas`).
+ */
+export * from "./BaseEntity.js";
+export * from "./BaseModel.js";
+export * from "./BaseRepository.js";
+export * from "./decorators/entity.js";
+export * from "./decorators/hooks.js";