feat: add utils and testing utils (#4)

Author: fahchen

README.md

@@ -9,23 +9,109 @@
 ## 🚀 Getting started
 
 ```typescript
-import { PostgresDialect } from "https://deno.land/x/kysely_deno_postgres_dialect/mod.ts";
-
-const dialect = new KyselyDenoPostgresDialect({
-  pool: new Pool(
-    {
-      database: "postgres",
-      hostname: "localhost",
-      password: "postgres",
-      port: 5432,
-      user: "postgres",
+import {
+  KyselyDenoPostgresDialect,
+  setup,
+} from "https://deno.land/x/kysely_deno_postgres_dialect/mod.ts";
+
+setup(() => {
+  const dialect = new KyselyDenoPostgresDialect({
+    pool: new Pool(
+      {
+        database: "postgres",
+        hostname: "localhost",
+        password: "postgres",
+        port: 5432,
+        user: "postgres",
+      },
+      10,
+      true,
+    ),
+  });
+
+  return new Kysely<Database>({
+    dialect,
+  });
+});
+
+// run queries
+```
+
+## 🩺 Testing
+
+See detail at `./tests/testing/utils_test.ts`.
+
+> [!IMPORTANT]\
+> To fix `leaking resources` error, you should end all connections between
+> cases.
+
+```typescript
+import {
+  KyselyDenoPostgresDialect,
+  PostgresConnection,
+  setup,
+  wrapTransaction,
+} from "https://deno.land/x/kysely_deno_postgres_dialect/mod.ts";
+import { setupTesting } from "https://deno.land/x/kysely_deno_postgres_dialect/testing.ts";
+
+const connections: PostgresConnection[] = [];
+
+setup(() => {
+  const dialect = new KyselyDenoPostgresDialect({
+    pool: new Pool(
+      {
+        database: "postgres",
+        hostname: "localhost",
+        password: "postgres",
+        port: 5432,
+        user: "postgres",
+      },
+      10,
+      true,
+    ),
+    onCreateConnection: (connection: DatabaseConnection) => {
+      connections.push(connection as PostgresConnection);
     },
-    10,
-    true,
-  ),
+  });
+
+  return new Kysely<Database>({
+    dialect,
+  });
 });
 
-export const db = new Kysely<Database>({
-  dialect,
+async function endConnections() {
+  for (const connection of connections) {
+    await connection.end();
+  }
+}
+
+// test files
+
+const {
+  beforeAllFn,
+  beforeEachFn,
+  afterEachFn,
+  afterAllFn,
+} = setupTesting(stub);
+
+describe("tests", () => {
+  beforeAll(async () => {
+    await beforeAllFn();
+  });
+  afterAll(async () => {
+    await afterAllFn();
+  });
+  beforeEach(async () => {
+    await beforeEachFn();
+  });
+  afterEach(async () => {
+    // note: fix Leaking resources error
+    await endConnections();
+    await afterEachFn();
+  });
+
+  it("works", async () => {
+    // snip
+  });
 });
 ```

deps.ts

@@ -11,6 +11,7 @@ export {
   PostgresQueryCompiler,
   type QueryCompiler,
   type QueryResult,
+  Transaction,
   type TransactionSettings,
 } from "https://esm.sh/kysely@0.26.3";
 export { Pool, PoolClient } from "https://deno.land/x/postgres@v0.17.0/mod.ts";

mod.ts

@@ -14,6 +14,7 @@ import { PostgresDriver } from "./src/postgres-driver.ts";
 import { PostgresDialectConfig } from "./src/postgres-dialect-config.ts";
 
 export { type DatabaseConnection, kysely, Pool, postgres } from "./deps.ts";
+export { type PostgresConnection } from "./src/postgres-connection.ts";
 
 export class KyselyDenoPostgresDialect implements Dialect {
   readonly #config: PostgresDialectConfig;
@@ -39,3 +40,5 @@ export class KyselyDenoPostgresDialect implements Dialect {
     return new PostgresIntrospector(db);
   }
 }
+
+export { getDB, setup, wrapTransaction } from "./src/utils.ts";

src/postgres-connection.ts

@@ -49,4 +49,8 @@ export class PostgresConnection implements DatabaseConnection {
   [PRIVATE_RELEASE_METHOD](): void {
     this.#client.release();
   }
+
+  async end(): Promise<void> {
+    await this.#client.end();
+  }
 }

src/postgres-dialect-config.ts

@@ -11,10 +11,10 @@ export interface PostgresDialectConfig {
    *
    * https://deno-postgres.com/#/?id=connection-pools
    */
-  pool: Pool | (() => Promise<Pool>);
+  pool: Pool | (() => Promise<Pool> | Pool);
 
   /**
    * Called once for each created connection.
    */
-  onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+  onCreateConnection?: (connection: DatabaseConnection) => Promise<void> | void;
 }

src/testing/begin.ts

@@ -0,0 +1,51 @@
+// deno-lint-ignore-file
+// https://github.com/kysely-org/kysely/issues/257#issuecomment-1676079354
+
+import { Kysely, Transaction } from "../../deps.ts";
+
+class Deferred<T> {
+  readonly #promise: Promise<T>;
+  #resolve?: (value: T | PromiseLike<T>) => void;
+  #reject?: (reason?: any) => void;
+
+  constructor() {
+    this.#promise = new Promise<T>((resolve, reject) => {
+      this.#resolve = resolve;
+      this.#reject = reject;
+    });
+  }
+
+  get promise(): Promise<T> {
+    return this.#promise;
+  }
+
+  resolve(value: T | PromiseLike<T>): void {
+    this.#resolve?.(value);
+  }
+
+  reject(reason?: any): void {
+    this.#reject?.(reason);
+  }
+}
+
+export default async function begin<T>(db: Kysely<T>) {
+  const connection = new Deferred<Transaction<T>>();
+  const result = new Deferred<any>();
+
+  const execution = db.transaction().execute(async (trx) => {
+    connection.resolve(trx);
+    await result.promise;
+  }).catch((_err) => {
+    // Swallow the exception here
+  });
+
+  const trx = await connection.promise;
+
+  return {
+    trx,
+    async rollback() {
+      result.reject(new Error("rollback"));
+      await execution;
+    },
+  };
+}

src/testing/utils.ts

@@ -0,0 +1,81 @@
+import { Transaction as KyselyTransaction } from "../../deps.ts";
+import { _internals, Callback, closeDB, getDB } from "../utils.ts";
+import begin from "./begin.ts";
+
+type Maybe<T> = T | undefined;
+
+// deno-lint-ignore no-explicit-any
+type Transaction = KyselyTransaction<any>;
+let transaction: Maybe<Transaction>;
+
+let rollbackFn: Maybe<() => Promise<void>>;
+
+async function doWrapTransactionStub<T, U>(
+  callback: Callback<T, U>,
+): Promise<U> {
+  if (!transaction) {
+    throw new Error("Transaction not initialized");
+  }
+
+  try {
+    const result = await callback(transaction);
+    return result;
+  } catch (error) {
+    console.error("Transaction failed: ", error);
+
+    throw error;
+  }
+}
+
+type Stub = { restore: () => unknown };
+
+/**
+ * Setup a database for testing.
+ *
+ * @param stub - The stub to use for wrapping the transaction.
+ * @returns The `beforeAllFn`, `beforeEachFn`, `afterEachFn` and `afterAllFn` functions to use in your test suite.
+ * @example
+ * ```ts
+ * import { stub } from "https://deno.land/std@0.210.0/testing/mock.ts";
+ * const { beforeEachFn, afterEachFn } = setupTesting(stub)
+ * ```
+ */
+export function setupTesting<T>(
+  stub: (...args: unknown[]) => Stub,
+) {
+  let transactionStub: Maybe<Stub>;
+
+  // deno-lint-ignore require-await
+  const beforeAllFn = async () => {
+    getDB<T>();
+  };
+
+  const beforeEachFn = async () => {
+    const db = getDB<T>();
+
+    const { trx, rollback } = await begin(db);
+    transaction = trx;
+    rollbackFn = rollback;
+
+    transactionStub = stub(
+      _internals,
+      "doWrapTransaction",
+      doWrapTransactionStub,
+    );
+  };
+
+  const afterEachFn = async () => {
+    if (transaction) {
+      await rollbackFn?.();
+      transaction = undefined;
+    }
+
+    transactionStub?.restore();
+  };
+
+  const afterAllFn = async () => {
+    await closeDB();
+  };
+
+  return { beforeAllFn, beforeEachFn, afterEachFn, afterAllFn };
+}

src/utils.ts

@@ -0,0 +1,53 @@
+import { Kysely, Transaction } from "../deps.ts";
+
+type Maybe<T> = T | undefined;
+
+type DB<T> = Kysely<T>;
+// deno-lint-ignore no-explicit-any
+let db: Maybe<DB<any>>;
+
+type SetupFn<T> = () => DB<T>;
+// deno-lint-ignore no-explicit-any
+let setupFn: Maybe<SetupFn<any>>;
+
+export function setup<T>(setup: SetupFn<T>): void {
+  setupFn = setup;
+}
+
+function newDB<T>(): DB<T> {
+  if (setupFn) {
+    db = setupFn();
+    return db;
+  }
+
+  throw new Error("Please call setup() before using the database");
+}
+
+export function getDB<T>(): Kysely<T> {
+  return db || newDB<T>();
+}
+
+export async function closeDB() {
+  if (db) {
+    await db.destroy();
+    db = undefined;
+  }
+}
+
+export type Callback<T, U> = (trx: Transaction<T>) => Promise<U>;
+
+async function doWrapTransaction<T, U>(callback: Callback<T, U>): Promise<U> {
+  try {
+    return await getDB<T>().transaction().execute(callback);
+  } finally {
+    await closeDB();
+  }
+}
+
+export async function wrapTransaction<T, U>(
+  callback: Callback<T, U>,
+): Promise<U> {
+  return await _internals.doWrapTransaction<T, U>(callback);
+}
+
+export const _internals = { doWrapTransaction };

testing.ts

@@ -0,0 +1 @@
+export { setupTesting } from "./src/testing/utils.ts";

tests/support/database.ts

@@ -1,6 +1,9 @@
-import { Kysely } from "../../deps.ts";
+import { DatabaseConnection, Kysely } from "../../deps.ts";
 import { Database } from "./types.ts"; // this is the Database interface we defined earlier
 import { KyselyDenoPostgresDialect, Pool } from "../../mod.ts";
+import { PostgresConnection } from "../../src/postgres-connection.ts";
+
+const connections: PostgresConnection[] = [];
 
 const dialect = new KyselyDenoPostgresDialect({
   pool: new Pool(
@@ -14,8 +17,17 @@ const dialect = new KyselyDenoPostgresDialect({
     10,
     true,
   ),
+  onCreateConnection: (connection: DatabaseConnection) => {
+    connections.push(connection as PostgresConnection);
+  },
 });
 
 export const db = new Kysely<Database>({
   dialect,
 });
+
+export async function endConnections() {
+  for (const connection of connections) {
+    await connection.end();
+  }
+}