@geekmidas/testkit 0.0.16 → 0.1.0

package/dist/VitestTransactionIsolator-CskiiJbW.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"VitestTransactionIsolator-CskiiJbW.mjs","names":["api: TestAPI","createConnection: DatabaseConnection<TConn>","setup?: (trx: Transaction) => Promise<void>","level: IsolationLevel","testError: Error | undefined"],"sources":["../src/VitestTransactionIsolator.ts"],"sourcesContent":["import 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 */\nexport interface DatabaseFixtures<Transaction> {\n  /**\n   * The database transaction available to the test.\n   * All database operations should use this transaction to ensure proper rollback.\n   */\n  trx: Transaction;\n}\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  /**\n   * Lowest isolation level. Allows dirty reads.\n   * Not recommended for testing.\n   */\n  READ_UNCOMMITTED = 'READ UNCOMMITTED',\n  /**\n   * Default PostgreSQL isolation level.\n   * Prevents dirty reads but allows non-repeatable reads.\n   */\n  READ_COMMITTED = 'READ COMMITTED',\n  /**\n   * Prevents dirty reads and non-repeatable reads.\n   * Recommended for most test scenarios.\n   */\n  REPEATABLE_READ = 'REPEATABLE READ',\n  /**\n   * Highest isolation level. Prevents all phenomena.\n   * May cause performance overhead in tests.\n   */\n  SERIALIZABLE = '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  /**\n   * Abstract method to create a transaction with the specified isolation level.\n   * Must be implemented by subclasses for specific database drivers.\n   *\n   * @param conn - The database connection\n   * @param isolationLevel - The transaction isolation level\n   * @param fn - The function to execute within the transaction\n   * @returns Promise that resolves when the transaction completes\n   */\n  abstract transact(\n    conn: TConn,\n    isolationLevel: IsolationLevel,\n    fn: (trx: Transaction) => Promise<void>,\n  ): Promise<void>;\n\n  abstract destroy(conn: TConn): Promise<void>;\n  /**\n   * Creates a new VitestPostgresTransactionIsolator instance.\n   *\n   * @param api - The Vitest test API (usually the `test` export from vitest)\n   */\n  constructor(private readonly api: TestAPI) {}\n\n  /**\n   * Creates a wrapped version of Vitest's test API that provides transaction isolation.\n   * Each test will run within a database transaction that is automatically rolled back.\n   *\n   * @param conn - The database connection to use\n   * @param setup - Optional setup function to run within the transaction before each test\n   * @param level - The transaction isolation level (defaults to REPEATABLE_READ)\n   * @returns A wrapped test API with transaction support\n   *\n   * @example\n   * ```typescript\n   * const isolatedTest = isolator.wrapVitestWithTransaction(db, async (trx) => {\n   *   // Optional setup: create common test data\n   *   await trx.insert('settings', { key: 'test', value: 'true' });\n   * });\n   *\n   * isolatedTest('test with transaction', async ({ trx }) => {\n   *   const user = await trx.insert('users', { name: 'Test' });\n   *   expect(user).toBeDefined();\n   * });\n   * ```\n   */\n  wrapVitestWithTransaction(\n    createConnection: DatabaseConnection<TConn>,\n    setup?: (trx: Transaction) => Promise<void>,\n    level: IsolationLevel = IsolationLevel.REPEATABLE_READ,\n  ) {\n    return this.api.extend<DatabaseFixtures<Transaction>>({\n      // This fixture automatically provides a transaction to each test\n      trx: async ({}, use) => {\n        // Create a custom error class for rollback\n        class TestRollback extends Error {\n          constructor() {\n            super('Test rollback');\n            this.name = 'TestRollback';\n          }\n        }\n\n        let testError: Error | undefined;\n        const conn = await createConnection();\n        try {\n          await this.transact(conn, level, async (transaction) => {\n            try {\n              // Provide the transaction to the test\n              await setup?.(transaction);\n              await use(transaction);\n            } catch (error) {\n              // Capture any test errors\n              testError = error as Error;\n            }\n\n            // Always throw to trigger rollback\n            throw new TestRollback();\n          });\n        } catch (error) {\n          // Only rethrow if it's not our rollback error\n          if (!(error instanceof TestRollback)) {\n            throw error;\n          }\n\n          // If the test had an error, throw it now\n          if (testError) {\n            throw testError;\n          }\n        } finally {\n          await this.destroy(conn);\n        }\n      },\n    });\n  }\n}\n\nexport type DatabaseConnectionFn<Conn> = () => Conn | Promise<Conn>;\nexport type DatabaseConnection<Conn> = DatabaseConnectionFn<Conn>;\n"],"mappings":";;;;;;;AAsBA,IAAY,4DAAL;;;;;AAKL;;;;;AAKA;;;;;AAKA;;;;;AAKA;;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BD,IAAsB,oCAAtB,MAA4E;;;;;;CAsB1E,YAA6BA,KAAc;EAAd;CAAgB;;;;;;;;;;;;;;;;;;;;;;;CAwB7C,0BACEC,kBACAC,OACAC,QAAwB,eAAe,iBACvC;AACA,SAAO,KAAK,IAAI,OAAsC,EAEpD,KAAK,OAAO,EAAE,EAAE,QAAQ;GAEtB,MAAM,qBAAqB,MAAM;IAC/B,cAAc;AACZ,WAAM,gBAAgB;AACtB,UAAK,OAAO;IACb;GACF;GAED,IAAIC;GACJ,MAAM,OAAO,MAAM,kBAAkB;AACrC,OAAI;AACF,UAAM,KAAK,SAAS,MAAM,OAAO,OAAO,gBAAgB;AACtD,SAAI;AAEF,YAAM,QAAQ,YAAY;AAC1B,YAAM,IAAI,YAAY;KACvB,SAAQ,OAAO;AAEd,kBAAY;KACb;AAGD,WAAM,IAAI;IACX,EAAC;GACH,SAAQ,OAAO;AAEd,UAAM,iBAAiB,cACrB,OAAM;AAIR,QAAI,UACF,OAAM;GAET,UAAS;AACR,UAAM,KAAK,QAAQ,KAAK;GACzB;EACF,EACF,EAAC;CACH;AACF"}