@happyvertical/smrt-vitest 0.30.0

package/dist/test-db.d.ts

@@ -0,0 +1,381 @@
+/**
+ * Test database utilities for SMRT tests
+ *
+ * Automatically uses PostgreSQL when DATABASE_URL is set (CI environment),
+ * otherwise creates unique SQLite temp files to avoid concurrency issues.
+ *
+ * Supports transaction-based test isolation: each test runs in a transaction
+ * that gets rolled back, ensuring clean state between tests.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { getTestDbConfig, createTestDb } from '@happyvertical/smrt-vitest';
+ *
+ * const { config, cleanup } = await createTestDb();
+ * // Use config...
+ * await cleanup();
+ * ```
+ *
+ * @example Transaction isolation (recommended for parallel tests)
+ * ```typescript
+ * import { createIsolatedTestDb } from '@happyvertical/smrt-vitest';
+ *
+ * const { db, cleanup } = await createIsolatedTestDb({ schema: mySchema });
+ * // All operations run in a transaction
+ * await db.insert('users', { id: '1', name: 'Test' });
+ * // cleanup() rolls back the transaction - no data persists
+ * await cleanup();
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { DatabaseInterfaceWithTransaction, TransactionHandle } from './types.js';
+/**
+ * Options for {@link createIsolatedTestDbFromManifest}.
+ */
+export interface ManifestTestDbOptions {
+    /**
+     * Explicit path to a manifest JSON file.
+     *
+     * When omitted the function searches the following locations in order:
+     * 1. `.smrt/manifest.json` — output of `smrtVitestPlugin()` / `smrt generate:test`
+     * 2. `dist/manifest.json` — production build manifest
+     * 3. `src/manifest/manifest.json` — legacy location
+     */
+    manifestPath?: string;
+    /**
+     * Restrict schema creation to a subset of class names.
+     *
+     * Accepts either simple class names (`'Product'`) or fully-qualified
+     * manifest keys (`'@my-org/smrt-models:Product'`).  When omitted, every
+     * object that has a schema in the manifest is included.
+     *
+     * @example `['Product', 'Order', 'OrderItem']`
+     */
+    includeObjects?: string[];
+    /**
+     * Prefix for the SQLite temp-file name.  Ignored for PostgreSQL.
+     * @default 'smrt-manifest'
+     */
+    prefix?: string;
+}
+/**
+ * Supported test database adapters.
+ *
+ * - `'sqlite'` — file-based or in-memory SQLite (default for local development)
+ * - `'postgres'` — PostgreSQL, used when `DATABASE_URL` is set (CI)
+ */
+export type TestDbAdapter = 'sqlite' | 'postgres';
+/**
+ * Database connection configuration for a test run.
+ *
+ * Returned by {@link getTestDbConfig} and {@link getInMemoryDbConfig}.
+ * Pass to `@happyvertical/sql`'s `getDatabase()` to open a connection.
+ */
+export interface TestDbConfig {
+    /** Adapter type — determines the driver used to open the connection. */
+    type: 'sqlite' | 'postgres';
+    /**
+     * Connection URL.
+     *
+     * - SQLite: absolute path to a `.db` file, or `':memory:'`
+     * - PostgreSQL: `postgresql://user:pass@host:port/dbname`
+     */
+    url: string;
+}
+/**
+ * Detect the database adapter to use based on the current environment.
+ *
+ * Resolution order:
+ * 1. `TEST_DB_ADAPTER` env var — explicit override (`'sqlite'` or `'postgres'`)
+ * 2. `DATABASE_URL` env var set → `'postgres'`
+ * 3. Default → `'sqlite'`
+ *
+ * @returns The adapter identifier for the current environment.
+ * @see {@link getTestDbConfig} to obtain a full {@link TestDbConfig}.
+ */
+export declare function getTestAdapter(): TestDbAdapter;
+/**
+ * Check whether PostgreSQL is available for the current test run.
+ *
+ * Returns `true` when the `DATABASE_URL` environment variable is set,
+ * which is the signal used by CI environments to opt into PostgreSQL.
+ *
+ * @returns `true` if `DATABASE_URL` is set, `false` otherwise.
+ * @see {@link getTestAdapter} for full adapter resolution logic.
+ */
+export declare function isPostgresAvailable(): boolean;
+/**
+ * Get a {@link TestDbConfig} appropriate for the current environment.
+ *
+ * Uses PostgreSQL when `DATABASE_URL` is set (CI), otherwise generates
+ * a unique SQLite temp-file path to prevent concurrency conflicts between
+ * parallel test workers.
+ *
+ * @param prefix - Optional prefix used in the SQLite temp-file name.
+ *   Ignored when using PostgreSQL. Defaults to `'smrt-test'`.
+ * @returns A {@link TestDbConfig} ready to pass to `getDatabase()`.
+ * @see {@link getInMemoryDbConfig} for a non-persistent SQLite alternative.
+ * @see {@link createTestDb} to obtain the config alongside a cleanup function.
+ */
+export declare function getTestDbConfig(prefix?: string): TestDbConfig;
+/**
+ * Get a {@link TestDbConfig} backed by an in-memory SQLite database.
+ *
+ * In-memory databases are isolated per connection — safe for concurrent
+ * tests within the same process, but the database cannot be shared across
+ * connections or workers.  No temp files are created or cleaned up.
+ *
+ * Prefer {@link getTestDbConfig} (file-based SQLite or PostgreSQL) when
+ * tests need to be shared or inspected after the run.
+ *
+ * @returns A `TestDbConfig` with `url: ':memory:'`.
+ */
+export declare function getInMemoryDbConfig(): TestDbConfig;
+/**
+ * Create a test database and return a cleanup function.
+ *
+ * Determines the adapter automatically via {@link getTestDbConfig}.  For
+ * SQLite, a unique temp file is created; `cleanup()` removes it along with
+ * any WAL/SHM sidecar files.  For PostgreSQL, `cleanup()` is a no-op
+ * (table isolation must be handled by the test itself).
+ *
+ * Unlike {@link createIsolatedTestDb}, this function does **not** wrap
+ * operations in a transaction — mutations made during the test persist until
+ * the temp file is deleted.  Prefer {@link createIsolatedTestDb} for
+ * isolated, parallel-safe tests.
+ *
+ * @param prefix - Prefix for the SQLite temp-file name.  Ignored for
+ *   PostgreSQL.  Defaults to `'smrt-test'`.
+ * @returns An object containing the resolved {@link TestDbConfig} and an
+ *   async `cleanup()` function that removes the temp file on SQLite.
+ *
+ * @example
+ * ```typescript
+ * import { createTestDb } from '@happyvertical/smrt-vitest';
+ *
+ * const { config, cleanup } = await createTestDb();
+ * const db = await getDatabase(config);
+ * // ... run tests ...
+ * await cleanup();
+ * ```
+ *
+ * @see {@link createIsolatedTestDb} for transaction-isolated test databases.
+ */
+export declare function createTestDb(prefix?: string): Promise<{
+    config: TestDbConfig;
+    cleanup: () => Promise<void>;
+}>;
+/**
+ * Get a human-readable display name for the current test database adapter.
+ *
+ * Useful for labelling `describe` blocks or test output so logs make clear
+ * which backend is under test.
+ *
+ * @returns `'PostgreSQL'` when the adapter is `'postgres'`, otherwise `'SQLite'`.
+ *
+ * @example
+ * ```typescript
+ * import { getAdapterDisplayName } from '@happyvertical/smrt-vitest';
+ *
+ * describe(`Product (${getAdapterDisplayName()})`, () => {
+ *   // ...
+ * });
+ * ```
+ *
+ * @see {@link getTestAdapter} to obtain the raw adapter identifier.
+ */
+export declare function getAdapterDisplayName(): string;
+/**
+ * Options for {@link createIsolatedTestDb}.
+ */
+export interface IsolatedTestDbOptions {
+    /**
+     * Raw SQL DDL to execute against the database before the transaction begins.
+     *
+     * The DDL is applied outside the transaction (required for DDL on SQLite and
+     * some PostgreSQL configurations), so it persists for the lifetime of the
+     * temp database.  The transaction wraps only the DML that follows.
+     *
+     * @example
+     * ```typescript
+     * schema: `
+     *   CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT NOT NULL);
+     *   CREATE TABLE orders (id TEXT PRIMARY KEY, user_id TEXT REFERENCES users(id));
+     * `
+     * ```
+     */
+    schema?: string;
+    /**
+     * Prefix for the SQLite temp-file name.  Ignored for PostgreSQL.
+     * @default 'smrt-isolated'
+     */
+    prefix?: string;
+}
+/**
+ * Result returned by {@link createIsolatedTestDb} and
+ * {@link createIsolatedTestDbFromManifest}.
+ */
+export interface IsolatedTestDbResult {
+    /**
+     * Transaction-scoped database handle.
+     *
+     * Use this for all DML inside your test.  All operations run within the
+     * open transaction and are rolled back when `cleanup()` is called.
+     */
+    db: TransactionHandle;
+    /**
+     * The underlying database connection, opened before the transaction began.
+     *
+     * Use only for operations that must run outside the transaction (e.g.,
+     * reading sequences or checking schema state).  Most tests should use
+     * `db` instead.
+     */
+    baseDb: DatabaseInterfaceWithTransaction;
+    /**
+     * The resolved {@link TestDbConfig} used to open the connection.
+     *
+     * Useful for introspection (e.g., logging which adapter is under test).
+     */
+    config: TestDbConfig;
+    /**
+     * Roll back the transaction, close the connection, and delete any SQLite
+     * temp files.
+     *
+     * **Always** call this in `afterEach()` or a `finally` block to prevent
+     * connection leaks and temp-file accumulation.
+     */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Create a test database with transaction isolation.
+ *
+ * Each test runs in a transaction that gets rolled back on `cleanup()`,
+ * ensuring complete isolation between tests without the overhead of
+ * creating or dropping tables between runs.  Parallel test workers each
+ * receive their own temp database file (SQLite) or an independent
+ * transaction (PostgreSQL).
+ *
+ * Requires `@happyvertical/sql` with `beginTransaction()` support
+ * (SDK PR #722).  Throws if the adapter does not implement it.
+ *
+ * @param options - Optional schema DDL and SQLite prefix.
+ *   Pass `schema` to have the DDL applied before the transaction begins.
+ * @returns An {@link IsolatedTestDbResult} containing the transaction handle,
+ *   base connection, resolved config, and a `cleanup()` function.
+ *
+ * @see {@link createIsolatedTestDbFromManifest} to derive the schema
+ *   automatically from the generated manifest file.
+ *
+ * @example
+ * ```typescript
+ * import { createIsolatedTestDb } from '@happyvertical/smrt-vitest';
+ * import { beforeEach, afterEach, it } from 'vitest';
+ *
+ * let db: TransactionHandle;
+ * let cleanup: () => Promise<void>;
+ *
+ * beforeEach(async () => {
+ *   const result = await createIsolatedTestDb({
+ *     schema: `CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT)`
+ *   });
+ *   db = result.db;
+ *   cleanup = result.cleanup;
+ * });
+ *
+ * afterEach(async () => {
+ *   await cleanup(); // Rolls back - no data persists
+ * });
+ *
+ * it('should insert and query', async () => {
+ *   await db.insert('users', { id: '1', name: 'Alice' });
+ *   const user = await db.get('users', { id: '1' });
+ *   expect(user?.name).toBe('Alice');
+ *   // After this test, cleanup() rolls back - Alice doesn't exist
+ * });
+ *
+ * it('should start with clean state', async () => {
+ *   // This test runs with a fresh transaction
+ *   const users = await db.list('users', {});
+ *   expect(users).toHaveLength(0); // Clean!
+ * });
+ * ```
+ */
+export declare function createIsolatedTestDb(options?: IsolatedTestDbOptions): Promise<IsolatedTestDbResult>;
+/**
+ * Create an isolated test database with schema derived from a manifest file.
+ *
+ * Eliminates the need to manually write or maintain DDL in test files by
+ * reading table definitions directly from the generated manifest.  Handles:
+ *
+ * - **STI deduplication** — multiple classes that share the same table are
+ *   merged into a single `CREATE TABLE` statement that includes all columns.
+ * - **FK dependency ordering** — tables are created in topological order so
+ *   `REFERENCES` constraints are always satisfied.
+ * - **Auto-detection** — searches `.smrt/manifest.json`, `dist/manifest.json`,
+ *   and `src/manifest/manifest.json` when no `manifestPath` is given.
+ *
+ * @param options - Optional manifest path, class filter, and SQLite prefix.
+ * @returns An {@link IsolatedTestDbResult} — same shape as
+ *   {@link createIsolatedTestDb}, with a transaction-scoped `db` handle and
+ *   a `cleanup()` that rolls back and removes temp files.
+ *
+ * @throws When no manifest is found at any of the checked locations.
+ * @throws When the manifest contains no objects with a database schema (or
+ *   none of the filtered `includeObjects` have a schema).
+ *
+ * @see {@link createIsolatedTestDb} if you prefer to supply raw DDL directly.
+ * @see {@link ManifestTestDbOptions} for all available options.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createIsolatedTestDbFromManifest } from '@happyvertical/smrt-vitest';
+ *
+ * let db, cleanup;
+ *
+ * beforeEach(async () => {
+ *   ({ db, cleanup } = await createIsolatedTestDbFromManifest());
+ * });
+ *
+ * afterEach(async () => {
+ *   await cleanup();
+ * });
+ * ```
+ *
+ * @example With tenant scoping
+ * ```typescript
+ * import { createIsolatedTestDbFromManifest } from '@happyvertical/smrt-vitest';
+ * import { withTenant, resetTenancy, setupTestTenancy } from '@happyvertical/smrt-tenancy';
+ *
+ * // In setup file
+ * setupTestTenancy({ enableInterceptors: true, rawQueryPolicy: 'allow' });
+ *
+ * // In test file
+ * let db, cleanup;
+ *
+ * beforeEach(async () => {
+ *   ({ db, cleanup } = await createIsolatedTestDbFromManifest());
+ * });
+ *
+ * afterEach(async () => {
+ *   resetTenancy();
+ *   await cleanup();
+ * });
+ *
+ * it('should auto-populate tenantId', async () => {
+ *   await withTenant({ tenantId: 'test-tenant' }, async () => {
+ *     const product = await collection.create({ name: 'Widget' });
+ *     expect(product.tenantId).toBe('test-tenant');
+ *   });
+ * });
+ * ```
+ *
+ * @example Filter to specific objects
+ * ```typescript
+ * const { db, cleanup } = await createIsolatedTestDbFromManifest({
+ *   includeObjects: ['Product', 'Order', 'OrderItem'],
+ * });
+ * ```
+ */
+export declare function createIsolatedTestDbFromManifest(options?: ManifestTestDbOptions): Promise<IsolatedTestDbResult>;
+//# sourceMappingURL=test-db.d.ts.map

package/dist/test-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-db.d.ts","sourceRoot":"","sources":["../src/test-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAcH,OAAO,KAAK,EACV,gCAAgC,EAChC,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAwCpB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,aAAa,CAa9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,MAAM,SAAc,GAAG,YAAY,CAmBlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,CAKlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,YAAY,CAAC,MAAM,SAAc,GAAG,OAAO,CAAC;IAChE,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC,CA2BD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAQ9C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,EAAE,EAAE,iBAAiB,CAAC;IAEtB;;;;;;OAMG;IACH,MAAM,EAAE,gCAAgC,CAAC;IAEzC;;;;OAIG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CA4E/B;AA2mBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC,CA4D/B"}