@geekmidas/testkit 10.0.0-alpha.3 → 10.0.0-alpha.31

package/dist/VitestTransactionIsolator.cjs

@@ -1,5 +1,188 @@
-const require_VitestTransactionIsolator = require('./VitestTransactionIsolator-DyiX-QtK.cjs');
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _geekmidas_envkit = require("@geekmidas/envkit");
+let _geekmidas_services = require("@geekmidas/services");
+//#region src/VitestTransactionIsolator.ts
+/**
+* PostgreSQL transaction isolation levels.
+* Controls the visibility of concurrent transactions.
+*
+* @see https://www.postgresql.org/docs/current/transaction-iso.html
+*/
+let IsolationLevel = /* @__PURE__ */ function(IsolationLevel) {
+	/**
+	* Lowest isolation level. Allows dirty reads.
+	* Not recommended for testing.
+	*/
+	IsolationLevel["READ_UNCOMMITTED"] = "READ UNCOMMITTED";
+	/**
+	* Default PostgreSQL isolation level.
+	* Prevents dirty reads but allows non-repeatable reads.
+	*/
+	IsolationLevel["READ_COMMITTED"] = "READ COMMITTED";
+	/**
+	* Prevents dirty reads and non-repeatable reads.
+	* Recommended for most test scenarios.
+	*/
+	IsolationLevel["REPEATABLE_READ"] = "REPEATABLE READ";
+	/**
+	* Highest isolation level. Prevents all phenomena.
+	* May cause performance overhead in tests.
+	*/
+	IsolationLevel["SERIALIZABLE"] = "SERIALIZABLE";
+	return IsolationLevel;
+}({});
+/**
+* Abstract base class for implementing database transaction isolation in Vitest tests.
+* Provides automatic transaction rollback after each test to maintain test isolation.
+* Subclasses must implement the transact() method for their specific database driver.
+*
+* @template TConn - The database connection type
+* @template Transaction - The transaction type
+*
+* @example
+* ```typescript
+* // Implement for your database driver
+* class MyDatabaseIsolator extends VitestPostgresTransactionIsolator<MyDB, MyTx> {
+*   async transact(conn: MyDB, level: IsolationLevel, fn: (tx: MyTx) => Promise<void>) {
+*     await conn.transaction(level, fn);
+*   }
+* }
+*
+* // Use in tests
+* const isolator = new MyDatabaseIsolator(test);
+* const isolatedTest = isolator.wrapVitestWithTransaction(db);
+*
+* isolatedTest('should create user', async ({ trx }) => {
+*   await trx.insert('users', { name: 'Test' });
+*   // Data is automatically rolled back after test
+* });
+* ```
+*/
+var VitestPostgresTransactionIsolator = class {
+	api;
+	/**
+	* Creates a new VitestPostgresTransactionIsolator instance.
+	*
+	* @param api - The Vitest test API (usually the `test` export from vitest)
+	*/
+	constructor(api) {
+		this.api = api;
+	}
+	/**
+	* Creates a wrapped version of Vitest's test API that provides transaction isolation.
+	* Each test will run within a database transaction that is automatically rolled back.
+	*
+	* @param options - Configuration options for transaction wrapping
+	* @returns A wrapped test API with transaction support
+	*
+	* @example
+	* ```typescript
+	* const isolatedTest = isolator.wrapVitestWithTransaction({
+	*   connection: db,
+	*   setup: async (trx) => {
+	*     await trx.insert('settings', { key: 'test', value: 'true' });
+	*   },
+	*   fixtures: {
+	*     factory: (trx) => new Factory(trx),
+	*   },
+	* });
+	*
+	* isolatedTest('test with transaction', async ({ trx, factory }) => {
+	*   const user = await factory.insert('user', { name: 'Test' });
+	*   expect(user).toBeDefined();
+	* });
+	* ```
+	*/
+	wrapVitestWithTransaction(options) {
+		const { connection, setup, isolationLevel = "REPEATABLE READ", fixtures } = options;
+		let resolved;
+		const resolveConnection = async () => {
+			if (resolved === void 0) resolved = await (isConstruct(connection) ? connection.service.register({
+				envParser: new _geekmidas_envkit.EnvironmentParser({ ...process.env }),
+				context: _geekmidas_services.serviceContext
+			}) : connection());
+			return resolved;
+		};
+		const additionalFixtures = {};
+		if (fixtures) for (const [key, creator] of Object.entries(fixtures)) additionalFixtures[key] = async ({ trx }, use) => {
+			await use(await creator(trx));
+		};
+		return this.api.extend({
+			trx: async ({}, use) => {
+				class TestRollback extends Error {
+					constructor() {
+						super("Test rollback");
+						this.name = "TestRollback";
+					}
+				}
+				let testError;
+				const conn = await resolveConnection();
+				try {
+					await this.transact(conn, isolationLevel, async (transaction) => {
+						try {
+							await setup?.(transaction);
+							await use(transaction);
+						} catch (error) {
+							testError = error;
+						}
+						throw new TestRollback();
+					});
+				} catch (error) {
+					if (!(error instanceof TestRollback)) throw error;
+					if (testError) throw testError;
+				}
+			},
+			...additionalFixtures
+		});
+	}
+};
+/** A construct is distinguished from a factory by owning a service. */
+function isConstruct(connection) {
+	return typeof connection !== "function";
+}
+/**
+* Extends a wrapped test API with additional fixtures that depend on the transaction.
+* This allows composing test context with factories, repositories, or other helpers.
+*
+* @template Transaction - The transaction type
+* @template Extended - The type of additional context to provide
+* @param wrappedTest - The base wrapped test from wrapVitestWithTransaction
+* @param fixtures - Object mapping fixture names to creator functions
+* @returns An extended test API with both trx and the additional fixtures
+*
+* @example
+* ```typescript
+* import { wrapVitestKyselyTransaction, extendWithFixtures } from '@geekmidas/testkit/kysely';
+*
+* // Create base wrapped test
+* const baseTest = wrapVitestKyselyTransaction(test, {
+*   connection: db,
+*   setup: createTestTables,
+* });
+*
+* // Extend with fixtures
+* const it = extendWithFixtures(baseTest, {
+*   factory: (trx) => new KyselyFactory(builders, seeds, trx),
+*   userRepo: (trx) => new UserRepository(trx),
+* });
+*
+* // Use in tests - trx and all fixtures are available
+* it('should create user with factory', async ({ trx, factory, userRepo }) => {
+*   const user = await factory.insert('user', { name: 'Test' });
+*   expect(user).toBeDefined();
+* });
+* ```
+*/
+function extendWithFixtures(wrappedTest, fixtures) {
+	const fixtureDefinitions = {};
+	for (const [key, creator] of Object.entries(fixtures)) fixtureDefinitions[key] = async ({ trx }, use) => {
+		await use(await creator(trx));
+	};
+	return wrappedTest.extend(fixtureDefinitions);
+}
+//#endregion
+exports.IsolationLevel = IsolationLevel;
+exports.VitestPostgresTransactionIsolator = VitestPostgresTransactionIsolator;
+exports.extendWithFixtures = extendWithFixtures;
 
-exports.IsolationLevel = require_VitestTransactionIsolator.IsolationLevel;
-exports.VitestPostgresTransactionIsolator = require_VitestTransactionIsolator.VitestPostgresTransactionIsolator;
-exports.extendWithFixtures = require_VitestTransactionIsolator.extendWithFixtures;
+//# sourceMappingURL=VitestTransactionIsolator.cjs.map

package/dist/VitestTransactionIsolator.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"VitestTransactionIsolator.cjs","names":["EnvironmentParser","serviceContext"],"sources":["../src/VitestTransactionIsolator.ts"],"sourcesContent":["import { EnvironmentParser } from '@geekmidas/envkit';\nimport { type Service, serviceContext } from '@geekmidas/services';\nimport type { TestAPI } from 'vitest';\n\n/**\n * Type definition for test fixtures that provide transaction access.\n * Used with Vitest's test.extend() API to inject transactions into tests.\n *\n * @template Transaction - The transaction type specific to the database driver\n * @template Extended - Additional context properties provided by the extend function\n */\nexport interface DatabaseFixtures<Transaction, _Extended = object> {\n\t/**\n\t * The database transaction available to the test.\n\t * All database operations should use this transaction to ensure proper rollback.\n\t */\n\ttrx: Transaction;\n}\n\n/**\n * Combined fixtures type that merges the base transaction fixture with extended context.\n */\nexport type ExtendedDatabaseFixtures<\n\tTransaction,\n\tExtended = object,\n> = DatabaseFixtures<Transaction> & Extended;\n\n/**\n * Function type for extending test context with additional properties.\n * Receives the transaction and returns additional context to be merged with { trx }.\n *\n * @template Transaction - The transaction type\n * @template Extended - The type of additional context to provide\n *\n * @example\n * ```typescript\n * const extendContext: ExtendContextFn<Transaction<DB>, { factory: KyselyFactory }> =\n *   (trx) => ({ factory: new KyselyFactory(builders, seeds, trx) });\n * ```\n */\nexport type ExtendContextFn<Transaction, Extended> = (\n\ttrx: Transaction,\n) => Extended | Promise<Extended>;\n\n/**\n * PostgreSQL transaction isolation levels.\n * Controls the visibility of concurrent transactions.\n *\n * @see https://www.postgresql.org/docs/current/transaction-iso.html\n */\nexport enum IsolationLevel {\n\t/**\n\t * Lowest isolation level. Allows dirty reads.\n\t * Not recommended for testing.\n\t */\n\tREAD_UNCOMMITTED = 'READ UNCOMMITTED',\n\t/**\n\t * Default PostgreSQL isolation level.\n\t * Prevents dirty reads but allows non-repeatable reads.\n\t */\n\tREAD_COMMITTED = 'READ COMMITTED',\n\t/**\n\t * Prevents dirty reads and non-repeatable reads.\n\t * Recommended for most test scenarios.\n\t */\n\tREPEATABLE_READ = 'REPEATABLE READ',\n\t/**\n\t * Highest isolation level. Prevents all phenomena.\n\t * May cause performance overhead in tests.\n\t */\n\tSERIALIZABLE = 'SERIALIZABLE',\n}\n\n/**\n * Abstract base class for implementing database transaction isolation in Vitest tests.\n * Provides automatic transaction rollback after each test to maintain test isolation.\n * Subclasses must implement the transact() method for their specific database driver.\n *\n * @template TConn - The database connection type\n * @template Transaction - The transaction type\n *\n * @example\n * ```typescript\n * // Implement for your database driver\n * class MyDatabaseIsolator extends VitestPostgresTransactionIsolator<MyDB, MyTx> {\n *   async transact(conn: MyDB, level: IsolationLevel, fn: (tx: MyTx) => Promise<void>) {\n *     await conn.transaction(level, fn);\n *   }\n * }\n *\n * // Use in tests\n * const isolator = new MyDatabaseIsolator(test);\n * const isolatedTest = isolator.wrapVitestWithTransaction(db);\n *\n * isolatedTest('should create user', async ({ trx }) => {\n *   await trx.insert('users', { name: 'Test' });\n *   // Data is automatically rolled back after test\n * });\n * ```\n */\nexport abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {\n\t/**\n\t * Abstract method to create a transaction with the specified isolation level.\n\t * Must be implemented by subclasses for specific database drivers.\n\t *\n\t * @param conn - The database connection\n\t * @param isolationLevel - The transaction isolation level\n\t * @param fn - The function to execute within the transaction\n\t * @returns Promise that resolves when the transaction completes\n\t */\n\tabstract transact(\n\t\tconn: TConn,\n\t\tisolationLevel: IsolationLevel,\n\t\tfn: (trx: Transaction) => Promise<void>,\n\t): Promise<void>;\n\n\tabstract destroy(conn: TConn): Promise<void>;\n\t/**\n\t * Creates a new VitestPostgresTransactionIsolator instance.\n\t *\n\t * @param api - The Vitest test API (usually the `test` export from vitest)\n\t */\n\tconstructor(private readonly api: TestAPI) {}\n\n\t/**\n\t * Creates a wrapped version of Vitest's test API that provides transaction isolation.\n\t * Each test will run within a database transaction that is automatically rolled back.\n\t *\n\t * @param options - Configuration options for transaction wrapping\n\t * @returns A wrapped test API with transaction support\n\t *\n\t * @example\n\t * ```typescript\n\t * const isolatedTest = isolator.wrapVitestWithTransaction({\n\t *   connection: db,\n\t *   setup: async (trx) => {\n\t *     await trx.insert('settings', { key: 'test', value: 'true' });\n\t *   },\n\t *   fixtures: {\n\t *     factory: (trx) => new Factory(trx),\n\t *   },\n\t * });\n\t *\n\t * isolatedTest('test with transaction', async ({ trx, factory }) => {\n\t *   const user = await factory.insert('user', { name: 'Test' });\n\t *   expect(user).toBeDefined();\n\t * });\n\t * ```\n\t */\n\twrapVitestWithTransaction<Extended extends Record<string, unknown> = {}>(\n\t\toptions: TransactionWrapperOptions<TConn, Transaction, Extended>,\n\t) {\n\t\tconst {\n\t\t\tconnection,\n\t\t\tsetup,\n\t\t\tisolationLevel = IsolationLevel.REPEATABLE_READ,\n\t\t\tfixtures,\n\t\t} = options;\n\n\t\t// Resolved once per file, not once per test. The fixture below runs for\n\t\t// every test, and opening a pool each time leaves one connection per test\n\t\t// alive — a file of fifty tests exhausts the server.\n\t\tlet resolved: TConn | undefined;\n\t\tconst resolveConnection = async (): Promise<TConn> => {\n\t\t\tif (resolved === undefined) {\n\t\t\t\tresolved = await (isConstruct(connection)\n\t\t\t\t\t? connection.service.register({\n\t\t\t\t\t\t\t// Spread: `process.env` is a ProcessEnv, not a plain object.\n\t\t\t\t\t\t\tenvParser: new EnvironmentParser({ ...process.env }),\n\t\t\t\t\t\t\tcontext: serviceContext,\n\t\t\t\t\t\t})\n\t\t\t\t\t: connection());\n\t\t\t}\n\t\t\treturn resolved;\n\t\t};\n\n\t\t// Build fixture definitions for additional fixtures that depend on trx\n\t\tconst additionalFixtures: Record<string, unknown> = {};\n\t\tif (fixtures) {\n\t\t\tfor (const [key, creator] of Object.entries(fixtures)) {\n\t\t\t\tadditionalFixtures[key] = async (\n\t\t\t\t\t{ trx }: { trx: Transaction },\n\t\t\t\t\tuse: (value: unknown) => Promise<void>,\n\t\t\t\t) => {\n\t\t\t\t\tconst value = await (creator as (trx: Transaction) => unknown)(trx);\n\t\t\t\t\tawait use(value);\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\ttype CombinedFixtures = DatabaseFixtures<Transaction> & Extended;\n\n\t\t// Cast to bypass Vitest's strict fixture typing which can't infer\n\t\t// dynamically built fixture objects\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst api = this.api as TestAPI & {\n\t\t\textend: <T>(fixtures: any) => TestAPI<T>;\n\t\t};\n\n\t\treturn api.extend<CombinedFixtures>({\n\t\t\t// This fixture automatically provides a transaction to each test\n\t\t\t// biome-ignore lint/correctness/noEmptyPattern: this has to be like this to satisfy Biome\n\t\t\ttrx: async ({}: {}, use: (value: Transaction) => Promise<void>) => {\n\t\t\t\t// Create a custom error class for rollback\n\t\t\t\tclass TestRollback extends Error {\n\t\t\t\t\tconstructor() {\n\t\t\t\t\t\tsuper('Test rollback');\n\t\t\t\t\t\tthis.name = 'TestRollback';\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tlet testError: Error | undefined;\n\t\t\t\tconst conn = await resolveConnection();\n\t\t\t\ttry {\n\t\t\t\t\tawait this.transact(conn, isolationLevel, async (transaction) => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t// Provide the transaction to the test\n\t\t\t\t\t\t\tawait setup?.(transaction);\n\t\t\t\t\t\t\tawait use(transaction);\n\t\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\t\t// Capture any test errors\n\t\t\t\t\t\t\ttestError = error as Error;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Always throw to trigger rollback\n\t\t\t\t\t\tthrow new TestRollback();\n\t\t\t\t\t});\n\t\t\t\t} catch (error) {\n\t\t\t\t\t// Only rethrow if it's not our rollback error\n\t\t\t\t\tif (!(error instanceof TestRollback)) {\n\t\t\t\t\t\tthrow error;\n\t\t\t\t\t}\n\n\t\t\t\t\t// If the test had an error, throw it now\n\t\t\t\t\tif (testError) {\n\t\t\t\t\t\tthrow testError;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t},\n\t\t\t...additionalFixtures,\n\t\t});\n\t}\n}\n\nexport type DatabaseConnectionFn<Conn> = () => Conn | Promise<Conn>;\n\n/**\n * Where a connection comes from: a construct, or a function returning one.\n *\n * A construct is preferred, because it builds the client through the same\n * `connect()` production uses. A hand-rolled client missing `CamelCasePlugin`\n * writes `createdAt` where the app writes `created_at`, and the test passes\n * while production does not. The URL is read from `process.env`.\n */\nexport type DatabaseConnection<Conn> =\n\t| DatabaseConnectionFn<Conn>\n\t| ConnectableConstruct<Conn>;\n\n/** A construct is distinguished from a factory by owning a service. */\nfunction isConstruct<Conn>(\n\tconnection: DatabaseConnection<Conn>,\n): connection is ConnectableConstruct<Conn> {\n\treturn typeof connection !== 'function';\n}\n\n/**\n * Options for wrapping Vitest tests with database transaction isolation.\n */\n/**\n * Anything that owns a service handing back a connection — a database\n * construct, structurally, so testkit depends on no construct package.\n */\nexport interface ConnectableConstruct<TConn> {\n\treadonly service: Service<string, TConn>;\n}\n\nexport interface TransactionWrapperOptions<\n\tTConn,\n\tTransaction,\n\tExtended extends Record<string, unknown> = {},\n> {\n\t/** Where the connection comes from — a construct, or a function returning one */\n\tconnection: DatabaseConnection<TConn>;\n\t/** Optional setup function to run within the transaction before each test */\n\tsetup?: (trx: Transaction) => Promise<void>;\n\t/** Transaction isolation level (defaults to REPEATABLE_READ) */\n\tisolationLevel?: IsolationLevel;\n\t/** Additional fixtures that depend on the transaction */\n\tfixtures?: FixtureCreators<Transaction, Extended>;\n}\n\n/**\n * Type for fixture creator functions that depend on the transaction.\n * Each function receives the transaction and returns the fixture value.\n */\nexport type FixtureCreators<\n\tTransaction,\n\tExtended extends Record<string, unknown>,\n> = {\n\t[K in keyof Extended]: (\n\t\ttrx: Transaction,\n\t) => Extended[K] | Promise<Extended[K]>;\n};\n\n/**\n * The test API returned by extendWithFixtures.\n * Provides access to both the transaction (trx) and all extended fixtures.\n *\n * @template Transaction - The transaction type\n * @template Extended - The type of additional fixtures provided\n * @template BaseTest - The base wrapped test type\n */\nexport type TestWithExtendedFixtures<\n\tTransaction,\n\tExtended extends Record<string, unknown>,\n\tBaseTest extends ReturnType<TestAPI['extend']> = ReturnType<\n\t\tTestAPI['extend']\n\t>,\n> = BaseTest & {\n\t<C extends object>(\n\t\tname: string,\n\t\tfn: (\n\t\t\tcontext: DatabaseFixtures<Transaction> & Extended & C,\n\t\t) => Promise<void>,\n\t): void;\n\t<C extends object>(\n\t\tname: string,\n\t\toptions: object,\n\t\tfn: (\n\t\t\tcontext: DatabaseFixtures<Transaction> & Extended & C,\n\t\t) => Promise<void>,\n\t): void;\n};\n\n/**\n * Extends a wrapped test API with additional fixtures that depend on the transaction.\n * This allows composing test context with factories, repositories, or other helpers.\n *\n * @template Transaction - The transaction type\n * @template Extended - The type of additional context to provide\n * @param wrappedTest - The base wrapped test from wrapVitestWithTransaction\n * @param fixtures - Object mapping fixture names to creator functions\n * @returns An extended test API with both trx and the additional fixtures\n *\n * @example\n * ```typescript\n * import { wrapVitestKyselyTransaction, extendWithFixtures } from '@geekmidas/testkit/kysely';\n *\n * // Create base wrapped test\n * const baseTest = wrapVitestKyselyTransaction(test, {\n *   connection: db,\n *   setup: createTestTables,\n * });\n *\n * // Extend with fixtures\n * const it = extendWithFixtures(baseTest, {\n *   factory: (trx) => new KyselyFactory(builders, seeds, trx),\n *   userRepo: (trx) => new UserRepository(trx),\n * });\n *\n * // Use in tests - trx and all fixtures are available\n * it('should create user with factory', async ({ trx, factory, userRepo }) => {\n *   const user = await factory.insert('user', { name: 'Test' });\n *   expect(user).toBeDefined();\n * });\n * ```\n */\nexport function extendWithFixtures<\n\tTransaction,\n\tExtended extends Record<string, unknown>,\n\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\tT extends ReturnType<TestAPI['extend']> = any,\n>(\n\twrappedTest: T,\n\tfixtures: FixtureCreators<Transaction, Extended>,\n): TestWithExtendedFixtures<Transaction, Extended, T> {\n\t// Build fixture definitions for Vitest's extend API\n\tconst fixtureDefinitions: Record<string, any> = {};\n\n\tfor (const [key, creator] of Object.entries(fixtures)) {\n\t\tfixtureDefinitions[key] = async (\n\t\t\t{ trx }: { trx: Transaction },\n\t\t\tuse: (value: unknown) => Promise<void>,\n\t\t) => {\n\t\t\tconst value = await (creator as (trx: Transaction) => unknown)(trx);\n\t\t\tawait use(value);\n\t\t};\n\t}\n\n\treturn (wrappedTest as any).extend(fixtureDefinitions);\n}\n"],"mappings":";;;;;;;;;;AAkDA,IAAY,iBAAL,yBAAA,gBAAA;;;;;CAKN,eAAA,sBAAA;;;;;CAKA,eAAA,oBAAA;;;;;CAKA,eAAA,qBAAA;;;;;CAKA,eAAA,kBAAA;;AACD,EAAA,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAsB,oCAAtB,MAA4E;CAsB9C;;;;;;CAA7B,YAAY,KAA+B;EAAd,KAAA,MAAA;CAAe;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B5C,0BACC,SACC;EACD,MAAM,EACL,YACA,OACA,iBAAA,mBACA,aACG;EAKJ,IAAI;EACJ,MAAM,oBAAoB,YAA4B;GACrD,IAAI,aAAa,KAAA,GAChB,WAAW,OAAO,YAAY,UAAU,IACrC,WAAW,QAAQ,SAAS;IAE5B,WAAW,IAAIA,kBAAAA,kBAAkB,EAAE,GAAG,QAAQ,IAAI,CAAC;IACnD,SAASC,oBAAAA;GACV,CAAC,IACA,WAAW;GAEf,OAAO;EACR;EAGA,MAAM,qBAA8C,CAAC;EACrD,IAAI,UACH,KAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,QAAQ,GACnD,mBAAmB,OAAO,OACzB,EAAE,OACF,QACI;GAEJ,MAAM,IAAI,MADW,QAA0C,GAAG,CACnD;EAChB;EAaF,OAJY,KAAK,IAIN,OAAyB;GAGnC,KAAK,OAAO,IAAQ,QAA+C;IAElE,MAAM,qBAAqB,MAAM;KAChC,cAAc;MACb,MAAM,eAAe;MACrB,KAAK,OAAO;KACb;IACD;IAEA,IAAI;IACJ,MAAM,OAAO,MAAM,kBAAkB;IACrC,IAAI;KACH,MAAM,KAAK,SAAS,MAAM,gBAAgB,OAAO,gBAAgB;MAChE,IAAI;OAEH,MAAM,QAAQ,WAAW;OACzB,MAAM,IAAI,WAAW;MACtB,SAAS,OAAO;OAEf,YAAY;MACb;MAGA,MAAM,IAAI,aAAa;KACxB,CAAC;IACF,SAAS,OAAO;KAEf,IAAI,EAAE,iBAAiB,eACtB,MAAM;KAIP,IAAI,WACH,MAAM;IAER;GACD;GACA,GAAG;EACJ,CAAC;CACF;AACD;;AAiBA,SAAS,YACR,YAC2C;CAC3C,OAAO,OAAO,eAAe;AAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwGA,SAAgB,mBAMf,aACA,UACqD;CAErD,MAAM,qBAA0C,CAAC;CAEjD,KAAK,MAAM,CAAC,KAAK,YAAY,OAAO,QAAQ,QAAQ,GACnD,mBAAmB,OAAO,OACzB,EAAE,OACF,QACI;EAEJ,MAAM,IAAI,MADW,QAA0C,GAAG,CACnD;CAChB;CAGD,OAAQ,YAAoB,OAAO,kBAAkB;AACtD"}

package/dist/VitestTransactionIsolator.d.cts

@@ -1,2 +1,219 @@
-import { ConnectableConstruct, DatabaseConnection, DatabaseConnectionFn, DatabaseFixtures, ExtendContextFn, ExtendedDatabaseFixtures, FixtureCreators, IsolationLevel, TestWithExtendedFixtures, TransactionWrapperOptions, VitestPostgresTransactionIsolator, extendWithFixtures } from "./VitestTransactionIsolator-glcxyS_R.cjs";
-export { ConnectableConstruct, DatabaseConnection, DatabaseConnectionFn, DatabaseFixtures, ExtendContextFn, ExtendedDatabaseFixtures, FixtureCreators, IsolationLevel, TestWithExtendedFixtures, TransactionWrapperOptions, VitestPostgresTransactionIsolator, extendWithFixtures };
+import { Service } from "@geekmidas/services";
+import { TestAPI } from "vitest";
+//#region src/VitestTransactionIsolator.d.ts
+/**
+ * Type definition for test fixtures that provide transaction access.
+ * Used with Vitest's test.extend() API to inject transactions into tests.
+ *
+ * @template Transaction - The transaction type specific to the database driver
+ * @template Extended - Additional context properties provided by the extend function
+ */
+export interface DatabaseFixtures<Transaction, _Extended = object> {
+  /**
+   * The database transaction available to the test.
+   * All database operations should use this transaction to ensure proper rollback.
+   */
+  trx: Transaction;
+}
+/**
+ * Combined fixtures type that merges the base transaction fixture with extended context.
+ */
+export type ExtendedDatabaseFixtures<Transaction, Extended = object> = DatabaseFixtures<Transaction> & Extended;
+/**
+ * Function type for extending test context with additional properties.
+ * Receives the transaction and returns additional context to be merged with { trx }.
+ *
+ * @template Transaction - The transaction type
+ * @template Extended - The type of additional context to provide
+ *
+ * @example
+ * ```typescript
+ * const extendContext: ExtendContextFn<Transaction<DB>, { factory: KyselyFactory }> =
+ *   (trx) => ({ factory: new KyselyFactory(builders, seeds, trx) });
+ * ```
+ */
+export type ExtendContextFn<Transaction, Extended> = (trx: Transaction) => Extended | Promise<Extended>;
+/**
+ * PostgreSQL transaction isolation levels.
+ * Controls the visibility of concurrent transactions.
+ *
+ * @see https://www.postgresql.org/docs/current/transaction-iso.html
+ */
+export declare enum IsolationLevel {
+  /**
+   * Lowest isolation level. Allows dirty reads.
+   * Not recommended for testing.
+   */
+  READ_UNCOMMITTED = "READ UNCOMMITTED",
+  /**
+   * Default PostgreSQL isolation level.
+   * Prevents dirty reads but allows non-repeatable reads.
+   */
+  READ_COMMITTED = "READ COMMITTED",
+  /**
+   * Prevents dirty reads and non-repeatable reads.
+   * Recommended for most test scenarios.
+   */
+  REPEATABLE_READ = "REPEATABLE READ",
+  /**
+   * Highest isolation level. Prevents all phenomena.
+   * May cause performance overhead in tests.
+   */
+  SERIALIZABLE = "SERIALIZABLE"
+}
+/**
+ * Abstract base class for implementing database transaction isolation in Vitest tests.
+ * Provides automatic transaction rollback after each test to maintain test isolation.
+ * Subclasses must implement the transact() method for their specific database driver.
+ *
+ * @template TConn - The database connection type
+ * @template Transaction - The transaction type
+ *
+ * @example
+ * ```typescript
+ * // Implement for your database driver
+ * class MyDatabaseIsolator extends VitestPostgresTransactionIsolator<MyDB, MyTx> {
+ *   async transact(conn: MyDB, level: IsolationLevel, fn: (tx: MyTx) => Promise<void>) {
+ *     await conn.transaction(level, fn);
+ *   }
+ * }
+ *
+ * // Use in tests
+ * const isolator = new MyDatabaseIsolator(test);
+ * const isolatedTest = isolator.wrapVitestWithTransaction(db);
+ *
+ * isolatedTest('should create user', async ({ trx }) => {
+ *   await trx.insert('users', { name: 'Test' });
+ *   // Data is automatically rolled back after test
+ * });
+ * ```
+ */
+export declare abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
+  private readonly api;
+  /**
+   * Abstract method to create a transaction with the specified isolation level.
+   * Must be implemented by subclasses for specific database drivers.
+   *
+   * @param conn - The database connection
+   * @param isolationLevel - The transaction isolation level
+   * @param fn - The function to execute within the transaction
+   * @returns Promise that resolves when the transaction completes
+   */
+  abstract transact(conn: TConn, isolationLevel: IsolationLevel, fn: (trx: Transaction) => Promise<void>): Promise<void>;
+  abstract destroy(conn: TConn): Promise<void>;
+  /**
+   * Creates a new VitestPostgresTransactionIsolator instance.
+   *
+   * @param api - The Vitest test API (usually the `test` export from vitest)
+   */
+  constructor(api: TestAPI);
+  /**
+   * Creates a wrapped version of Vitest's test API that provides transaction isolation.
+   * Each test will run within a database transaction that is automatically rolled back.
+   *
+   * @param options - Configuration options for transaction wrapping
+   * @returns A wrapped test API with transaction support
+   *
+   * @example
+   * ```typescript
+   * const isolatedTest = isolator.wrapVitestWithTransaction({
+   *   connection: db,
+   *   setup: async (trx) => {
+   *     await trx.insert('settings', { key: 'test', value: 'true' });
+   *   },
+   *   fixtures: {
+   *     factory: (trx) => new Factory(trx),
+   *   },
+   * });
+   *
+   * isolatedTest('test with transaction', async ({ trx, factory }) => {
+   *   const user = await factory.insert('user', { name: 'Test' });
+   *   expect(user).toBeDefined();
+   * });
+   * ```
+   */
+  wrapVitestWithTransaction<Extended extends Record<string, unknown> = {}>(options: TransactionWrapperOptions<TConn, Transaction, Extended>): TestAPI<DatabaseFixtures<Transaction, object> & Extended>;
+}
+export type DatabaseConnectionFn<Conn> = () => Conn | Promise<Conn>;
+/**
+ * Where a connection comes from: a construct, or a function returning one.
+ *
+ * A construct is preferred, because it builds the client through the same
+ * `connect()` production uses. A hand-rolled client missing `CamelCasePlugin`
+ * writes `createdAt` where the app writes `created_at`, and the test passes
+ * while production does not. The URL is read from `process.env`.
+ */
+export type DatabaseConnection<Conn> = DatabaseConnectionFn<Conn> | ConnectableConstruct<Conn>;
+/**
+ * Options for wrapping Vitest tests with database transaction isolation.
+ */
+/**
+ * Anything that owns a service handing back a connection — a database
+ * construct, structurally, so testkit depends on no construct package.
+ */
+export interface ConnectableConstruct<TConn> {
+  readonly service: Service<string, TConn>;
+}
+export interface TransactionWrapperOptions<TConn, Transaction, Extended extends Record<string, unknown> = {}> {
+  /** Where the connection comes from — a construct, or a function returning one */
+  connection: DatabaseConnection<TConn>;
+  /** Optional setup function to run within the transaction before each test */
+  setup?: (trx: Transaction) => Promise<void>;
+  /** Transaction isolation level (defaults to REPEATABLE_READ) */
+  isolationLevel?: IsolationLevel;
+  /** Additional fixtures that depend on the transaction */
+  fixtures?: FixtureCreators<Transaction, Extended>;
+}
+/**
+ * Type for fixture creator functions that depend on the transaction.
+ * Each function receives the transaction and returns the fixture value.
+ */
+export type FixtureCreators<Transaction, Extended extends Record<string, unknown>> = { [K in keyof Extended]: (trx: Transaction) => Extended[K] | Promise<Extended[K]>; };
+/**
+ * The test API returned by extendWithFixtures.
+ * Provides access to both the transaction (trx) and all extended fixtures.
+ *
+ * @template Transaction - The transaction type
+ * @template Extended - The type of additional fixtures provided
+ * @template BaseTest - The base wrapped test type
+ */
+export type TestWithExtendedFixtures<Transaction, Extended extends Record<string, unknown>, BaseTest extends ReturnType<TestAPI['extend']> = ReturnType<TestAPI['extend']>> = BaseTest & {
+  <C extends object>(name: string, fn: (context: DatabaseFixtures<Transaction> & Extended & C) => Promise<void>): void;
+  <C extends object>(name: string, options: object, fn: (context: DatabaseFixtures<Transaction> & Extended & C) => Promise<void>): void;
+};
+/**
+ * Extends a wrapped test API with additional fixtures that depend on the transaction.
+ * This allows composing test context with factories, repositories, or other helpers.
+ *
+ * @template Transaction - The transaction type
+ * @template Extended - The type of additional context to provide
+ * @param wrappedTest - The base wrapped test from wrapVitestWithTransaction
+ * @param fixtures - Object mapping fixture names to creator functions
+ * @returns An extended test API with both trx and the additional fixtures
+ *
+ * @example
+ * ```typescript
+ * import { wrapVitestKyselyTransaction, extendWithFixtures } from '@geekmidas/testkit/kysely';
+ *
+ * // Create base wrapped test
+ * const baseTest = wrapVitestKyselyTransaction(test, {
+ *   connection: db,
+ *   setup: createTestTables,
+ * });
+ *
+ * // Extend with fixtures
+ * const it = extendWithFixtures(baseTest, {
+ *   factory: (trx) => new KyselyFactory(builders, seeds, trx),
+ *   userRepo: (trx) => new UserRepository(trx),
+ * });
+ *
+ * // Use in tests - trx and all fixtures are available
+ * it('should create user with factory', async ({ trx, factory, userRepo }) => {
+ *   const user = await factory.insert('user', { name: 'Test' });
+ *   expect(user).toBeDefined();
+ * });
+ * ```
+ */
+export declare function extendWithFixtures<Transaction, Extended extends Record<string, unknown>, T extends ReturnType<TestAPI['extend']> = any>(wrappedTest: T, fixtures: FixtureCreators<Transaction, Extended>): TestWithExtendedFixtures<Transaction, Extended, T>;
+//#endregion
+//# sourceMappingURL=VitestTransactionIsolator.d.cts.map

package/dist/VitestTransactionIsolator.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VitestTransactionIsolator.d.cts","names":[],"sources":["../src/VitestTransactionIsolator.ts"],"mappings":";;;;;;;;;;iBAWiB,iBAAiB,aAAa;;;;;EAK9C,KAAK;;;;;YAMM,yBACX,aACA,qBACG,iBAAiB,eAAe;;;;;;;;;;;;;;YAexB,gBAAgB,aAAa,aACxC,KAAK,gBACD,WAAW,QAAQ;;;;;;;oBAQZ;;;;;EAKX;;;;;EAKA;;;;;EAKA;;;;;EAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BA8BqB,kCAAkC,OAAO;mBAsBjC;;;;;;;;;;WAZpB,SACR,MAAM,OACN,gBAAgB,gBAChB,KAAK,KAAK,gBAAgB,gBACxB;WAEM,QAAQ,MAAM,QAAQ;;;;;;EAM/B,YAA6B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BlC,0BAA0B,iBAAiB,8BAC1C,SAAS,0BAA0B,OAAO,aAAa,YAAS,QAAA,iBAAA,uBAAA;;YA8FtD,qBAAqB,cAAc,OAAO,QAAQ;;;;;;;;;YAUlD,mBAAmB,QAC5B,qBAAqB,QACrB,qBAAqB;;;;;;;;iBAgBP,qBAAqB;WAC5B,SAAS,gBAAgB;;iBAGlB,0BAChB,OACA,aACA,iBAAiB;;EAGjB,YAAY,mBAAmB;;EAE/B,SAAS,KAAK,gBAAgB;;EAE9B,iBAAiB;;EAEjB,WAAW,gBAAgB,aAAa;;;;;;YAO7B,gBACX,aACA,iBAAiB,8BAEhB,WAAW,YACX,KAAK,gBACD,SAAS,KAAK,QAAQ,SAAS;;;;;;;;;YAWzB,yBACX,aACA,iBAAiB,yBACjB,iBAAiB,WAAW,qBAAqB,WAChD,sBAEE;GACF,kBACA,cACA,KACC,SAAS,iBAAiB,eAAe,WAAW,MAChD;GAEL,kBACA,cACA,iBACA,KACC,SAAS,iBAAiB,eAAe,WAAW,MAChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAqCS,mBACf,aACA,iBAAiB,yBAEjB,UAAU,WAAW,0BAErB,aAAa,GACb,UAAU,gBAAgB,aAAa,YACrC,yBAAyB,aAAa,UAAU"}

package/dist/VitestTransactionIsolator.d.mts

@@ -1,2 +1,219 @@
-import { ConnectableConstruct, DatabaseConnection, DatabaseConnectionFn, DatabaseFixtures, ExtendContextFn, ExtendedDatabaseFixtures, FixtureCreators, IsolationLevel, TestWithExtendedFixtures, TransactionWrapperOptions, VitestPostgresTransactionIsolator, extendWithFixtures } from "./VitestTransactionIsolator-BLaw80cx.mjs";
-export { ConnectableConstruct, DatabaseConnection, DatabaseConnectionFn, DatabaseFixtures, ExtendContextFn, ExtendedDatabaseFixtures, FixtureCreators, IsolationLevel, TestWithExtendedFixtures, TransactionWrapperOptions, VitestPostgresTransactionIsolator, extendWithFixtures };
+import { Service } from "@geekmidas/services";
+import { TestAPI } from "vitest";
+//#region src/VitestTransactionIsolator.d.ts
+/**
+ * Type definition for test fixtures that provide transaction access.
+ * Used with Vitest's test.extend() API to inject transactions into tests.
+ *
+ * @template Transaction - The transaction type specific to the database driver
+ * @template Extended - Additional context properties provided by the extend function
+ */
+export interface DatabaseFixtures<Transaction, _Extended = object> {
+  /**
+   * The database transaction available to the test.
+   * All database operations should use this transaction to ensure proper rollback.
+   */
+  trx: Transaction;
+}
+/**
+ * Combined fixtures type that merges the base transaction fixture with extended context.
+ */
+export type ExtendedDatabaseFixtures<Transaction, Extended = object> = DatabaseFixtures<Transaction> & Extended;
+/**
+ * Function type for extending test context with additional properties.
+ * Receives the transaction and returns additional context to be merged with { trx }.
+ *
+ * @template Transaction - The transaction type
+ * @template Extended - The type of additional context to provide
+ *
+ * @example
+ * ```typescript
+ * const extendContext: ExtendContextFn<Transaction<DB>, { factory: KyselyFactory }> =
+ *   (trx) => ({ factory: new KyselyFactory(builders, seeds, trx) });
+ * ```
+ */
+export type ExtendContextFn<Transaction, Extended> = (trx: Transaction) => Extended | Promise<Extended>;
+/**
+ * PostgreSQL transaction isolation levels.
+ * Controls the visibility of concurrent transactions.
+ *
+ * @see https://www.postgresql.org/docs/current/transaction-iso.html
+ */
+export declare enum IsolationLevel {
+  /**
+   * Lowest isolation level. Allows dirty reads.
+   * Not recommended for testing.
+   */
+  READ_UNCOMMITTED = "READ UNCOMMITTED",
+  /**
+   * Default PostgreSQL isolation level.
+   * Prevents dirty reads but allows non-repeatable reads.
+   */
+  READ_COMMITTED = "READ COMMITTED",
+  /**
+   * Prevents dirty reads and non-repeatable reads.
+   * Recommended for most test scenarios.
+   */
+  REPEATABLE_READ = "REPEATABLE READ",
+  /**
+   * Highest isolation level. Prevents all phenomena.
+   * May cause performance overhead in tests.
+   */
+  SERIALIZABLE = "SERIALIZABLE"
+}
+/**
+ * Abstract base class for implementing database transaction isolation in Vitest tests.
+ * Provides automatic transaction rollback after each test to maintain test isolation.
+ * Subclasses must implement the transact() method for their specific database driver.
+ *
+ * @template TConn - The database connection type
+ * @template Transaction - The transaction type
+ *
+ * @example
+ * ```typescript
+ * // Implement for your database driver
+ * class MyDatabaseIsolator extends VitestPostgresTransactionIsolator<MyDB, MyTx> {
+ *   async transact(conn: MyDB, level: IsolationLevel, fn: (tx: MyTx) => Promise<void>) {
+ *     await conn.transaction(level, fn);
+ *   }
+ * }
+ *
+ * // Use in tests
+ * const isolator = new MyDatabaseIsolator(test);
+ * const isolatedTest = isolator.wrapVitestWithTransaction(db);
+ *
+ * isolatedTest('should create user', async ({ trx }) => {
+ *   await trx.insert('users', { name: 'Test' });
+ *   // Data is automatically rolled back after test
+ * });
+ * ```
+ */
+export declare abstract class VitestPostgresTransactionIsolator<TConn, Transaction> {
+  private readonly api;
+  /**
+   * Abstract method to create a transaction with the specified isolation level.
+   * Must be implemented by subclasses for specific database drivers.
+   *
+   * @param conn - The database connection
+   * @param isolationLevel - The transaction isolation level
+   * @param fn - The function to execute within the transaction
+   * @returns Promise that resolves when the transaction completes
+   */
+  abstract transact(conn: TConn, isolationLevel: IsolationLevel, fn: (trx: Transaction) => Promise<void>): Promise<void>;
+  abstract destroy(conn: TConn): Promise<void>;
+  /**
+   * Creates a new VitestPostgresTransactionIsolator instance.
+   *
+   * @param api - The Vitest test API (usually the `test` export from vitest)
+   */
+  constructor(api: TestAPI);
+  /**
+   * Creates a wrapped version of Vitest's test API that provides transaction isolation.
+   * Each test will run within a database transaction that is automatically rolled back.
+   *
+   * @param options - Configuration options for transaction wrapping
+   * @returns A wrapped test API with transaction support
+   *
+   * @example
+   * ```typescript
+   * const isolatedTest = isolator.wrapVitestWithTransaction({
+   *   connection: db,
+   *   setup: async (trx) => {
+   *     await trx.insert('settings', { key: 'test', value: 'true' });
+   *   },
+   *   fixtures: {
+   *     factory: (trx) => new Factory(trx),
+   *   },
+   * });
+   *
+   * isolatedTest('test with transaction', async ({ trx, factory }) => {
+   *   const user = await factory.insert('user', { name: 'Test' });
+   *   expect(user).toBeDefined();
+   * });
+   * ```
+   */
+  wrapVitestWithTransaction<Extended extends Record<string, unknown> = {}>(options: TransactionWrapperOptions<TConn, Transaction, Extended>): TestAPI<DatabaseFixtures<Transaction, object> & Extended>;
+}
+export type DatabaseConnectionFn<Conn> = () => Conn | Promise<Conn>;
+/**
+ * Where a connection comes from: a construct, or a function returning one.
+ *
+ * A construct is preferred, because it builds the client through the same
+ * `connect()` production uses. A hand-rolled client missing `CamelCasePlugin`
+ * writes `createdAt` where the app writes `created_at`, and the test passes
+ * while production does not. The URL is read from `process.env`.
+ */
+export type DatabaseConnection<Conn> = DatabaseConnectionFn<Conn> | ConnectableConstruct<Conn>;
+/**
+ * Options for wrapping Vitest tests with database transaction isolation.
+ */
+/**
+ * Anything that owns a service handing back a connection — a database
+ * construct, structurally, so testkit depends on no construct package.
+ */
+export interface ConnectableConstruct<TConn> {
+  readonly service: Service<string, TConn>;
+}
+export interface TransactionWrapperOptions<TConn, Transaction, Extended extends Record<string, unknown> = {}> {
+  /** Where the connection comes from — a construct, or a function returning one */
+  connection: DatabaseConnection<TConn>;
+  /** Optional setup function to run within the transaction before each test */
+  setup?: (trx: Transaction) => Promise<void>;
+  /** Transaction isolation level (defaults to REPEATABLE_READ) */
+  isolationLevel?: IsolationLevel;
+  /** Additional fixtures that depend on the transaction */
+  fixtures?: FixtureCreators<Transaction, Extended>;
+}
+/**
+ * Type for fixture creator functions that depend on the transaction.
+ * Each function receives the transaction and returns the fixture value.
+ */
+export type FixtureCreators<Transaction, Extended extends Record<string, unknown>> = { [K in keyof Extended]: (trx: Transaction) => Extended[K] | Promise<Extended[K]>; };
+/**
+ * The test API returned by extendWithFixtures.
+ * Provides access to both the transaction (trx) and all extended fixtures.
+ *
+ * @template Transaction - The transaction type
+ * @template Extended - The type of additional fixtures provided
+ * @template BaseTest - The base wrapped test type
+ */
+export type TestWithExtendedFixtures<Transaction, Extended extends Record<string, unknown>, BaseTest extends ReturnType<TestAPI['extend']> = ReturnType<TestAPI['extend']>> = BaseTest & {
+  <C extends object>(name: string, fn: (context: DatabaseFixtures<Transaction> & Extended & C) => Promise<void>): void;
+  <C extends object>(name: string, options: object, fn: (context: DatabaseFixtures<Transaction> & Extended & C) => Promise<void>): void;
+};
+/**
+ * Extends a wrapped test API with additional fixtures that depend on the transaction.
+ * This allows composing test context with factories, repositories, or other helpers.
+ *
+ * @template Transaction - The transaction type
+ * @template Extended - The type of additional context to provide
+ * @param wrappedTest - The base wrapped test from wrapVitestWithTransaction
+ * @param fixtures - Object mapping fixture names to creator functions
+ * @returns An extended test API with both trx and the additional fixtures
+ *
+ * @example
+ * ```typescript
+ * import { wrapVitestKyselyTransaction, extendWithFixtures } from '@geekmidas/testkit/kysely';
+ *
+ * // Create base wrapped test
+ * const baseTest = wrapVitestKyselyTransaction(test, {
+ *   connection: db,
+ *   setup: createTestTables,
+ * });
+ *
+ * // Extend with fixtures
+ * const it = extendWithFixtures(baseTest, {
+ *   factory: (trx) => new KyselyFactory(builders, seeds, trx),
+ *   userRepo: (trx) => new UserRepository(trx),
+ * });
+ *
+ * // Use in tests - trx and all fixtures are available
+ * it('should create user with factory', async ({ trx, factory, userRepo }) => {
+ *   const user = await factory.insert('user', { name: 'Test' });
+ *   expect(user).toBeDefined();
+ * });
+ * ```
+ */
+export declare function extendWithFixtures<Transaction, Extended extends Record<string, unknown>, T extends ReturnType<TestAPI['extend']> = any>(wrappedTest: T, fixtures: FixtureCreators<Transaction, Extended>): TestWithExtendedFixtures<Transaction, Extended, T>;
+//#endregion
+//# sourceMappingURL=VitestTransactionIsolator.d.mts.map