@c9up/atlas 0.1.3

package/src/testing/TestDatabase.ts

@@ -0,0 +1,81 @@
+/**
+ * TestDatabase — in-memory SQLite database for testing via the ream-db Rust driver.
+ */
+
+import type { DatabaseAdapter } from "../schema/MigrationRunner.js";
+
+/** Simple async database interface for tests. */
+export class Database {
+	#impl: DatabaseImpl;
+
+	constructor(impl: DatabaseImpl) {
+		this.#impl = impl;
+	}
+
+	/** Create an in-memory SQLite database backed by the Rust ream-db driver. */
+	static async memory(): Promise<Database> {
+		const { createNapiConnection } = await import(
+			"../adapters/NapiDbAdapter.js"
+		);
+		const conn = await createNapiConnection("sqlite::memory:", 1, 1);
+		return new Database({
+			async query(sql: string): Promise<Record<string, unknown>[]> {
+				return conn.query(sql);
+			},
+			async queryWithParams(
+				sql: string,
+				params: unknown[],
+			): Promise<Record<string, unknown>[]> {
+				return conn.query(sql, params);
+			},
+			async execute(sql: string, params?: unknown[]): Promise<void> {
+				await conn.execute(sql, params);
+			},
+			async close(): Promise<void> {
+				await conn.close();
+			},
+		});
+	}
+
+	async query(sql: string): Promise<Record<string, unknown>[]> {
+		return this.#impl.query(sql);
+	}
+
+	async queryWithParams(
+		sql: string,
+		params: unknown[],
+	): Promise<Record<string, unknown>[]> {
+		return this.#impl.queryWithParams(sql, params);
+	}
+
+	async execute(sql: string, params?: unknown[]): Promise<void> {
+		return this.#impl.execute(sql, params);
+	}
+
+	async close(): Promise<void> {
+		return this.#impl.close();
+	}
+
+	/** Get a DatabaseAdapter for MigrationRunner compatibility. */
+	asAdapter(): DatabaseAdapter {
+		return {
+			execute: (sql: string, params?: unknown[]) =>
+				this.#impl.execute(sql, params),
+			query: <T>(sql: string, params?: unknown[]) =>
+				params
+					? (this.#impl.queryWithParams(sql, params) as Promise<T[]>)
+					: (this.#impl.query(sql) as Promise<T[]>),
+			close: () => this.#impl.close(),
+		};
+	}
+}
+
+interface DatabaseImpl {
+	query(sql: string): Promise<Record<string, unknown>[]>;
+	queryWithParams(
+		sql: string,
+		params: unknown[],
+	): Promise<Record<string, unknown>[]>;
+	execute(sql: string, params?: unknown[]): Promise<void>;
+	close(): Promise<void>;
+}

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+export { truncateAll, useTransaction } from "./DatabaseCleanup.js";
+export { type FactoryBuilder, factory } from "./Factory.js";
+export { Database } from "./TestDatabase.js";

package/src/utils/casing.ts

@@ -0,0 +1,11 @@
+/** Convert snake_case to camelCase. */
+export function snakeToCamel(s: string): string {
+	return s.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** Convert camelCase or PascalCase to snake_case (no leading underscore). */
+export function camelToSnake(s: string): string {
+	return s.replace(/[A-Z]/g, (c, i) =>
+		i === 0 ? c.toLowerCase() : `_${c.toLowerCase()}`,
+	);
+}

package/src/utils/dialectFromUrl.ts

@@ -0,0 +1,16 @@
+/**
+ * Single source of truth for dialect detection. Both `AtlasProvider` and
+ * `NapiDbAdapter` used to ship their own copy — if a new driver scheme was
+ * added (e.g. `cockroachdb://`), only one side would be updated and the two
+ * would silently drift. Extracted here so every call site resolves the same
+ * way.
+ */
+import type { AtlasDialect } from "../query/native.js";
+
+export function dialectFromUrl(url: string): AtlasDialect {
+	if (url.startsWith("postgres://") || url.startsWith("postgresql://"))
+		return "postgres";
+	if (url.startsWith("mysql://") || url.startsWith("mariadb://"))
+		return "mysql";
+	return "sqlite";
+}

package/src/utils/identifier.ts

@@ -0,0 +1,35 @@
+/**
+ * SQL identifier validation helpers — used by the TS-side fluent builders
+ * before a name is sent to the Rust compiler. Catches obvious garbage
+ * (empty / wrong chars / leading digit) early with a clear error site.
+ *
+ * The Rust compiler ALSO validates and quotes identifiers — these helpers
+ * are a defence-in-depth check, not the source of truth.
+ */
+
+/** Pattern: starts with letter or underscore, then letters/digits/underscore/dot. */
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+
+/** Returns true if `name` is a syntactically valid SQL identifier (table, column, alias, CTE name, …). */
+export function isValidIdentifier(name: unknown): name is string {
+	return (
+		typeof name === "string" && name.length > 0 && IDENTIFIER_RE.test(name)
+	);
+}
+
+/**
+ * Asserts that `name` is a valid identifier; throws a structured error otherwise.
+ *
+ * @param name  the value to validate
+ * @param kind  human-readable label used in the error message (e.g. "CTE name", "column name")
+ * @param errorFactory  builds the error to throw — keeps this helper independent of any specific error class
+ */
+export function assertValidIdentifier(
+	name: unknown,
+	kind: string,
+	errorFactory: (message: string) => Error,
+): asserts name is string {
+	if (!isValidIdentifier(name)) {
+		throw errorFactory(`${kind} must be a valid identifier: '${String(name)}'`);
+	}
+}

package/src/utils/safePath.ts

@@ -0,0 +1,59 @@
+/**
+ * Path/filename validation helpers shared by MigrationRunner and Seeder.
+ *
+ * Centralised here so the "forbidden chars + no `..`" rules + "path must stay
+ * inside its base directory" check live in one place. Previously duplicated
+ * — the audit flagged this as a maintenance hazard.
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { AtlasError } from "../errors.js";
+
+/** Non-throwing async `fs.existsSync` equivalent. Returns false on ENOENT, propagates other errors. */
+export async function pathExists(p: string): Promise<boolean> {
+	try {
+		await fsp.access(p);
+		return true;
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw err;
+	}
+}
+
+/**
+ * Throw if `name` contains characters that could escape a filename context
+ * (path separators, quotes, backticks) or include a directory-walk sequence
+ * (`..`). Does NOT check extension or existence — that's the caller's job.
+ */
+export function assertSafeName(
+	name: string,
+	errorCode: string,
+	kind: string,
+): void {
+	if (/[/\\'";`]/.test(name) || name.includes("..")) {
+		throw new AtlasError(errorCode, `Invalid ${kind} name: ${name}`);
+	}
+}
+
+/**
+ * Resolve `fileName` inside `baseDir` and throw if the resulting path escapes
+ * the base — guards against symlink / `../` traversal attacks when loading
+ * migration or seeder files dynamically.
+ */
+export function assertPathInsideBase(
+	baseDir: string,
+	fileName: string,
+	errorCode: string,
+	kind: string,
+): string {
+	const resolved = path.resolve(baseDir, fileName);
+	const base = path.resolve(baseDir);
+	if (!resolved.startsWith(base + path.sep) && resolved !== base) {
+		throw new AtlasError(
+			errorCode,
+			`${kind} path escapes directory: ${fileName}`,
+		);
+	}
+	return resolved;
+}

package/src/utils/transactionBrand.ts

@@ -0,0 +1,10 @@
+import type { DatabaseConnection } from "../BaseRepository.js";
+import type { TransactionClient } from "../Transaction.js";
+
+export const TRANSACTION_BRAND = Symbol.for("atlas:transaction");
+
+export function isTransactionClient(
+	db: DatabaseConnection,
+): db is TransactionClient {
+	return TRANSACTION_BRAND in db;
+}