@c9up/atlas 0.2.0 → 0.2.1

package/src/query/DmlBuilder.ts

@@ -0,0 +1,131 @@
+/**
+ * Lazy, chainable, inspectable DML builder — Lucid `insert()`/`update()`/
+ * `delete()` return a builder that only runs on `await`/`.exec()`. This lets the
+ * Lucid-documented order work:
+ *
+ *     db.table('users').insert(data).onConflict('email').merge()
+ *     db.from('users').where(...).update(data).returning('id')
+ *     db.table('users').insert(data).toSQL()
+ *     db.from('users').where(...).delete().timeout(1000)
+ *
+ * The clause methods delegate back to the owning {@link DatabaseQueryBuilder}
+ * (via `hooks`), so the reverse (atlas) order `onConflict(...).insert(...)` keeps
+ * working too — both mutate the same state, read when the query finally compiles.
+ */
+
+import {
+	type CompiledStatement,
+	compiledStatement,
+	interpolateQuery,
+} from "./interpolate.js";
+
+/** The chainable DML clauses the builder forwards to its owner. */
+export interface DmlChainHooks {
+	onConflict(...columns: Array<string | string[]>): void;
+	merge(...args: Array<string | string[] | Record<string, unknown>>): void;
+	ignore(): void;
+	returning(...columns: Array<string | string[]>): void;
+	timeout(ms?: number, options?: { cancel?: boolean }): void;
+	comment(text: string): void;
+	debug(enabled?: boolean): void;
+	reporterData(data: Record<string, unknown>): void;
+}
+
+export class DmlBuilder<R> implements PromiseLike<R> {
+	readonly #run: () => Promise<R>;
+	readonly #compile: () => {
+		sql: string;
+		bindings: unknown[];
+		params: unknown[];
+	};
+	readonly #hooks: DmlChainHooks;
+
+	constructor(
+		run: () => Promise<R>,
+		compile: () => { sql: string; bindings: unknown[]; params: unknown[] },
+		hooks: DmlChainHooks,
+	) {
+		this.#run = run;
+		this.#compile = compile;
+		this.#hooks = hooks;
+	}
+
+	/** The compiled statement without executing (Lucid `toSQL`; `.toNative()` for native form). */
+	toSQL(): CompiledStatement {
+		const c = this.#compile();
+		return compiledStatement(c.sql, c.params);
+	}
+
+	/** SQL with bindings substituted as literals, for inspection (Lucid `toQuery`). */
+	toQuery(): string {
+		const c = this.#compile();
+		return interpolateQuery(c.sql, c.params);
+	}
+
+	/** Conflict target for an upsert (Lucid `insert(...).onConflict(...)`). */
+	onConflict(...columns: Array<string | string[]>): this {
+		this.#hooks.onConflict(...columns);
+		return this;
+	}
+
+	/** On conflict, UPDATE columns / custom values (Lucid `merge`). */
+	merge(...args: Array<string | string[] | Record<string, unknown>>): this {
+		this.#hooks.merge(...args);
+		return this;
+	}
+
+	/** On conflict, do nothing (Lucid `ignore`). */
+	ignore(): this {
+		this.#hooks.ignore();
+		return this;
+	}
+
+	/** Columns to return (Lucid `insert(...).returning(...)`). */
+	returning(...columns: Array<string | string[]>): this {
+		this.#hooks.returning(...columns);
+		return this;
+	}
+
+	/** Caller-facing statement timeout (Lucid `delete().timeout(ms, { cancel })`). */
+	timeout(ms?: number, options?: { cancel?: boolean }): this {
+		this.#hooks.timeout(ms, options);
+		return this;
+	}
+
+	/** Prefix a `/* … *​/` SQL comment (Lucid `comment`). */
+	comment(text: string): this {
+		this.#hooks.comment(text);
+		return this;
+	}
+
+	/** Log the compiled SQL + bindings on the next run (Lucid `debug`). */
+	debug(enabled = true): this {
+		this.#hooks.debug(enabled);
+		return this;
+	}
+
+	/** Attach metadata to this statement's `db:query` event (Lucid `reporterData`). */
+	reporterData(data: Record<string, unknown>): this {
+		this.#hooks.reporterData(data);
+		return this;
+	}
+
+	/** Run the statement and resolve to its result. */
+	exec(): Promise<R> {
+		return this.#run();
+	}
+
+	// biome-ignore lint/suspicious/noThenProperty: Lucid DML builders are awaitable by design — `await db.table(t).insert(...)` must resolve to the result; the thenable is the intended public API.
+	then<TResult1 = R, TResult2 = never>(
+		onfulfilled?:
+			| ((value: R) => TResult1 | PromiseLike<TResult1>)
+			| undefined
+			| null,
+		onrejected?:
+			| ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
+			| undefined
+			| null,
+	): PromiseLike<TResult1 | TResult2> {
+		return this.#run().then(onfulfilled, onrejected);
+	}
+}

package/src/query/QueryBuilder.ts

@@ -83,6 +83,14 @@ export class RawSql {
 		this.params = params;
 	}
 
+	/**
+	 * Wrap the fragment with a prefix/suffix — e.g. parentheses (Lucid/Knex raw
+	 * `.wrap('(', ')')`). Immutable: returns a new `RawSql` with the same params.
+	 */
+	wrap(before: string, after: string): RawSql {
+		return new RawSql(`${before}${this.sql}${after}`, this.params);
+	}
+
 	/** Tagged template literal for raw SQL with automatic parameterization. */
 	static sql(strings: TemplateStringsArray, ...values: unknown[]): RawSql {
 		let sql = "";

package/src/query/RawQueryBuilder.ts

@@ -0,0 +1,173 @@
+import type { QueryExecutor } from "./DatabaseQueryBuilder.js";
+import type { AtlasDialect } from "./native.js";
+
+/** Dialect-quote a possibly dotted identifier (`users.id` → `"users"."id"`). */
+function quoteIdent(ident: string, dialect: AtlasDialect): string {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(ident)) {
+		throw new Error(`Invalid identifier binding '${ident}'.`);
+	}
+	const q = dialect === "mysql" ? "`" : '"';
+	return ident
+		.split(".")
+		.map((s) => `${q}${s}${q}`)
+		.join(".");
+}
+
+/**
+ * Resolve Lucid/Knex raw bindings into positional `?` SQL + ordered params.
+ *
+ * Positional (array bindings): `?` binds a value, `??` inlines a quoted
+ * identifier. Named (object bindings): `:name` binds a value, `:name:` inlines a
+ * quoted identifier. Identifiers are quoted for the dialect; values become `?`
+ * placeholders bound in occurrence order.
+ */
+export function resolveRawBindings(
+	sql: string,
+	bindings: unknown[] | Record<string, unknown>,
+	dialect: AtlasDialect,
+): { sql: string; params: unknown[] } {
+	const params: unknown[] = [];
+	if (Array.isArray(bindings)) {
+		let i = 0;
+		const out = sql.replace(/\?\?|\?/g, (m) => {
+			const v = bindings[i++];
+			if (m === "??") return quoteIdent(String(v), dialect);
+			params.push(v);
+			return "?";
+		});
+		return { sql: out, params };
+	}
+	// `::` (Postgres cast) is matched first and passed through untouched, so
+	// `:payload::jsonb` reads as the value binding `:payload` + the cast `::jsonb`
+	// rather than an `:payload:` identifier. `:name:` only matches when its
+	// trailing colon is NOT part of a `::` cast (`(?!:)`).
+	const out = sql.replace(
+		/::|:(\w+):(?!:)|:(\w+)/g,
+		(m: string, ident?: string, name?: string) => {
+			if (m === "::") return "::";
+			if (ident !== undefined) {
+				return quoteIdent(String(bindings[ident]), dialect);
+			}
+			if (name !== undefined) {
+				params.push(bindings[name]);
+				return "?";
+			}
+			return m;
+		},
+	);
+	return { sql: out, params };
+}
+
+/**
+ * Chainable raw query — Lucid `db.rawQuery(sql, bindings)`. Unlike a raw
+ * fragment (`db.raw`), this executes independently and exposes the standard
+ * query surface: `toSQL()`, `toQuery()`, `debug()`, `timeout()`,
+ * `reporterData()`. Thenable, so it can be awaited directly.
+ */
+export class RawQueryBuilder<T = Record<string, unknown>>
+	implements PromiseLike<T[]>
+{
+	readonly #exec: QueryExecutor;
+	readonly #dialect: AtlasDialect;
+	readonly #rawSql: string;
+	readonly #rawBindings: unknown[] | Record<string, unknown>;
+	#timeoutMs?: number;
+	#debugFlag = false;
+	#reporter?: Record<string, unknown>;
+
+	constructor(
+		exec: QueryExecutor,
+		dialect: AtlasDialect,
+		sql: string,
+		bindings: unknown[] | Record<string, unknown> = [],
+	) {
+		this.#exec = exec;
+		this.#dialect = dialect;
+		this.#rawSql = sql;
+		this.#rawBindings = bindings;
+	}
+
+	/** `{ sql, bindings }` with named/identifier bindings resolved (Lucid `toSQL`). */
+	toSQL(): { sql: string; bindings: unknown[] } {
+		const { sql, params } = resolveRawBindings(
+			this.#rawSql,
+			this.#rawBindings,
+			this.#dialect,
+		);
+		return { sql, bindings: params };
+	}
+
+	/** The SQL with bindings substituted for display/debug (Lucid `toQuery`). */
+	toQuery(): string {
+		const { sql, bindings } = this.toSQL();
+		let i = 0;
+		return sql.replace(/\?/g, () => {
+			const v = bindings[i++];
+			if (v === null || v === undefined) return "NULL";
+			if (typeof v === "number" || typeof v === "boolean") return String(v);
+			return `'${String(v).replace(/'/g, "''")}'`;
+		});
+	}
+
+	/** Enable debug logging of the compiled query on execution (Lucid `debug`). */
+	debug(value = true): this {
+		this.#debugFlag = value;
+		return this;
+	}
+
+	/**
+	 * Caller-facing statement timeout (Lucid `timeout(ms, options)`). Matches
+	 * Lucid's DEFAULT non-cancelling timeout — the awaiter rejects after `ms`.
+	 * `{ cancel: true }` server-side cancellation is not wired at this layer.
+	 */
+	timeout(ms?: number, _options?: { cancel?: boolean }): this {
+		this.#timeoutMs = ms;
+		return this;
+	}
+
+	/** Attach metadata to the query (Lucid `reporterData`). */
+	reporterData(data: Record<string, unknown>): this {
+		this.#reporter = data;
+		return this;
+	}
+
+	/** Execute and return the rows. */
+	async exec(): Promise<T[]> {
+		const { sql, bindings } = this.toSQL();
+		// Carry `debug`/`reporterData` in the query meta so the `db:query` observer
+		// fires exactly like Lucid — not a bare console.debug.
+		const meta: { debug?: boolean; reporterData?: Record<string, unknown> } =
+			{};
+		if (this.#debugFlag) meta.debug = true;
+		if (this.#reporter) meta.reporterData = this.#reporter;
+		const work = this.#exec.query<T>(
+			sql,
+			bindings,
+			Object.keys(meta).length > 0 ? meta : undefined,
+		);
+		return this.#race(work);
+	}
+
+	// biome-ignore lint/suspicious/noThenProperty: Lucid raw queries are awaitable by design — `await db.rawQuery(...)` must resolve to the rows; the thenable is the intended public API, matching the other builders.
+	then<R1 = T[], R2 = never>(
+		onfulfilled?: ((value: T[]) => R1 | PromiseLike<R1>) | undefined | null,
+		onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | undefined | null,
+	): PromiseLike<R1 | R2> {
+		return this.exec().then(onfulfilled, onrejected);
+	}
+
+	/** Race the query against the configured `.timeout(ms)`. */
+	#race(work: Promise<T[]>): Promise<T[]> {
+		const ms = this.#timeoutMs;
+		if (!ms || ms <= 0) return work;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const guard = new Promise<never>((_, reject) => {
+			timer = setTimeout(
+				() => reject(new Error(`Query timed out after ${ms}ms`)),
+				ms,
+			);
+		});
+		work.catch(() => {});
+		return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+	}
+}

package/src/query/interpolate.ts

@@ -0,0 +1,73 @@
+/**
+ * Query-inspection helpers shared by every builder's `toQuery()` / `toSQL()`.
+ *
+ * `toQuery()` returns the SQL with bindings substituted as literals (Adonis
+ * Lucid semantics — `where "is_active" = 1`), for ad-hoc inspection ONLY. It is
+ * NOT injection-safe; forward `toSQL()` + bindings to logs instead.
+ */
+
+/** SQL-literal render of a single binding (inspection only — not injection-safe). */
+export function literalEscape(v: unknown): string {
+	if (v === null || v === undefined) return "NULL";
+	if (typeof v === "number") return String(v);
+	if (typeof v === "boolean") return v ? "1" : "0";
+	if (v instanceof Date) return `'${v.toISOString()}'`;
+	// Strings — escape single quotes per SQL. NOT hardened against `\'`.
+	return `'${String(v).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Substitute native placeholders (`?` sequentially, `$N` by 1-based index) with
+ * dialect-safe literals — Lucid `toQuery`. `$N` is resolved by its own index so
+ * a reused/reordered Postgres placeholder still maps to the right binding.
+ */
+export function interpolateQuery(
+	sql: string,
+	params: readonly unknown[],
+): string {
+	let seq = 0;
+	return sql.replace(/\?|\$\d+/g, (tok) =>
+		literalEscape(params[tok[0] === "$" ? Number(tok.slice(1)) - 1 : seq++]),
+	);
+}
+
+/**
+ * Normalize dialect-native positional placeholders (`$1`, `$2`, … — Postgres) to
+ * Knex-style `?`, matching what Lucid's `toSQL().sql` returns for every dialect.
+ * MySQL/SQLite already emit `?`, so this is a no-op there. Display concern only:
+ * atlas executes with the native statement (see `toNative`).
+ */
+export function toQuestionMarks(sql: string): string {
+	return sql.replace(/\$\d+/g, "?");
+}
+
+/**
+ * The compiled statement Lucid's `toSQL()` returns: `{ sql, bindings }` with `?`
+ * placeholders (Knex-normalized, same on every dialect), plus a `toNative()` that
+ * yields the dialect-native `{ sql, bindings }` (Postgres `$N`) that atlas
+ * actually executes. `params` is atlas's historical alias of `bindings` (same
+ * array), kept so either name ports.
+ */
+export interface CompiledStatement {
+	sql: string;
+	bindings: unknown[];
+	params: unknown[];
+	/** Dialect-native `{ sql, bindings }` (Lucid `toSQL().toNative()`). */
+	toNative(): { sql: string; bindings: unknown[] };
+}
+
+/**
+ * Wrap a NATIVE compiled `sql` + `params` as a Lucid-shaped {@link CompiledStatement}:
+ * the public `.sql` is `?`-normalized, `.toNative()` yields the native form.
+ */
+export function compiledStatement(
+	nativeSql: string,
+	params: unknown[],
+): CompiledStatement {
+	return {
+		sql: toQuestionMarks(nativeSql),
+		bindings: params,
+		params,
+		toNative: () => ({ sql: nativeSql, bindings: params }),
+	};
+}

package/src/query/native.ts

@@ -40,6 +40,35 @@ try {
 
 export type AtlasDialect = "sqlite" | "postgres" | "mysql";
 
+/**
+ * Dialect names accepted by `ifDialect`/`unlessDialect`, including the Lucid/Knex
+ * client aliases — so a callback ported from Lucid (`ifDialect('sqlite3', …)`,
+ * which Lucid names `sqlite3`/`better-sqlite3`, not `sqlite`) still matches.
+ */
+export type DialectName =
+	| AtlasDialect
+	| "sqlite3"
+	| "better-sqlite3"
+	| "postgresql"
+	| "pg"
+	| "mysql2";
+
+const DIALECT_ALIASES: Record<string, AtlasDialect> = {
+	sqlite: "sqlite",
+	sqlite3: "sqlite",
+	"better-sqlite3": "sqlite",
+	postgres: "postgres",
+	postgresql: "postgres",
+	pg: "postgres",
+	mysql: "mysql",
+	mysql2: "mysql",
+};
+
+/** Map a Lucid/Knex dialect name to the atlas dialect, or `undefined` if unknown. */
+export function normalizeDialect(name: string): AtlasDialect | undefined {
+	return DIALECT_ALIASES[name];
+}
+
 /** Module-level default dialect. Set by AtlasProvider at boot. */
 let defaultDialect: AtlasDialect = "sqlite";
 

package/src/query/operators.ts

@@ -0,0 +1,27 @@
+/** SQL operator helpers shared by the query builders. */
+
+const NEGATION: Record<string, string> = {
+	"=": "!=",
+	"!=": "=",
+	"<>": "=",
+	"<": ">=",
+	">": "<=",
+	"<=": ">",
+	">=": "<",
+	IN: "NOT IN",
+	"NOT IN": "IN",
+	LIKE: "NOT LIKE",
+	"NOT LIKE": "LIKE",
+	ILIKE: "NOT ILIKE",
+	BETWEEN: "NOT BETWEEN",
+	"NOT BETWEEN": "BETWEEN",
+	"IS NULL": "IS NOT NULL",
+	"IS NOT NULL": "IS NULL",
+};
+
+/** The logical negation of a comparison operator (`>=` → `<`, `=` → `!=`, …). */
+export function negateOperator(op: string): string {
+	const negated = NEGATION[op.toUpperCase()] ?? NEGATION[op];
+	if (!negated) throw new Error(`whereNot: unsupported operator '${op}'`);
+	return negated;
+}

package/src/schema/Migration.ts

@@ -39,7 +39,22 @@ export type DeferredMigrationCallback = (
 ) => Promise<void> | void;
 
 export abstract class Migration {
+	/**
+	 * Adonis Lucid `static disableTransactions`. Set `static disableTransactions =
+	 * true` on a migration to run it OUTSIDE a transaction — for DDL that cannot
+	 * run inside one (e.g. Postgres `CREATE INDEX CONCURRENTLY`). Applies to both
+	 * `up()` and `down()`; the runner then executes the migration non-atomically
+	 * by design (so `this.defer()` runs loose too). Defaults to `false`.
+	 */
+	static disableTransactions = false;
+
 	readonly schema: Schema;
+	/**
+	 * Adonis Lucid `this.dryRun` — `true` while the runner generates SQL without
+	 * executing it (set by `MigrationRunner.dryRun()`). Read it in `up()`/`down()`
+	 * to conditionally skip side-effectful branches. Defaults to `false`.
+	 */
+	dryRun = false;
 	readonly #dialect: AtlasDialect;
 	#deferred: DeferredMigrationCallback[] = [];
 
@@ -52,19 +67,33 @@ export abstract class Migration {
 	}
 
 	/**
-	 * 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.
+	 * Register a callback to run AFTER this migration's schema statements (Adonis
+	 * Lucid `this.defer`) — typically to seed/backfill data into a table the same
+	 * migration just created. The callback gets a live connection handle and runs
+	 * in registration order, interleaved with the schema.
 	 *
-	 * 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.
+	 * ATOMICITY (Lucid parity): by default the schema, the deferred callbacks AND
+	 * the migration's tracking row all run in ONE transaction — a throwing callback
+	 * rolls the schema back too, so the migration is all-or-nothing and re-runnable
+	 * (fully atomic on sqlite/postgres; MySQL auto-commits DDL, so only its tracking
+	 * row is bound to the callbacks). The one exception is a migration with `static
+	 * disableTransactions = true`: it opts out of the transaction entirely (for
+	 * txn-incompatible DDL), so there the deferred work runs non-atomically, by
+	 * design.
 	 */
 	defer(callback: DeferredMigrationCallback): void {
 		this.#deferred.push(callback);
 	}
 
+	/**
+	 * @internal Effective `static disableTransactions` of the concrete subclass —
+	 * read by the runner to decide whether to wrap this migration in a transaction.
+	 */
+	get transactionsDisabled(): boolean {
+		const ctor = this.constructor;
+		return "disableTransactions" in ctor && ctor.disableTransactions === true;
+	}
+
 	/** @internal Return and clear the deferred callbacks — called by the runner. */
 	consumeDeferred(): DeferredMigrationCallback[] {
 		const deferred = this.#deferred;