refactor: setupTesting (#15)

Author: fahchen

README.md

@@ -1,35 +1,58 @@
 # kysely-deno-postgres-dialect
 
 [![ci](https://github.com/Byzanteam/kysely_deno_postgres_dialect/actions/workflows/ci.yml/badge.svg)](https://github.com/Byzanteam/kysely_deno_postgres_dialect/actions/workflows/ci.yml)
-[![Latest version](https://deno.land/badge/kysely_deno_postgres_dialect/version)](https://deno.land/x/kysely_deno_postgres_dialect)
+[![JSR](https://jsr.io/badges/@byzanteam/kysely-deno-postgres-dialect)](https://jsr.io/@byzanteam/kysely-deno-postgres-dialect)
 
 [Kysely](https://github.com/kysely-org/kysely) dialect for PostgreSQL using the
 [postgresjs](https://github.com/porsager/postgres) client.
 
 ## 🚀 Getting started
 
-Import using `imports` in `deno.json`
+### Install dependencies
+
+```
+deno add @byzanteam/kysely-deno-postgres-dialect
+```
+
+Optional: Import using `imports` in `deno.json`, if you dont want to use `npm`
+registry.
 
 ```json
 {
   "imports": {
-    "kysely-deno-postgres-dialect/": "https://deno.land/x/kysely_postgrs_js_dialect/",
+    "kysely-deno-postgres-dialect": "jsr:@byzanteam/kysely-deno-postgres-dialect",
     "postgresjs": "https://deno.land/x/postgresjs@v3.4.4/mod.js",
     "kysely": "https://esm.sh/kysely@0.27.3"
   }
 }
 ```
 
-use kysely-deno-postgres-dialect
+### Use kysely-deno-postgres-dialect
+
+1. Define your database schema
 
 ```typescript
+import postgres from "postgresjs/mod.js";
+import { type Generated, Kysely } from "kysely";
 import {
   PostgresJSDialect,
   setup,
   wrapTransaction as wrapTransactionFn,
-} from "kysely-deno-postgres-dialect/mod.ts";
-import postgres from "postgresjs/mod.js";
+} from "kysely-deno-postgres-dialect";
+
+interface UserTable {
+  id: Generated<number>;
+  name: string;
+}
+
+interface Database {
+  users: UserTable;
+}
+```
+
+2. Setup the kysely instance before using it
 
+```typescript
 setup(() => {
   const dialect = new PostgresJSDialect({
     postgres: postgres(
@@ -44,81 +67,90 @@ setup(() => {
     ),
   });
 
-  return new Kysely<Database>({ // Database is defined by Kysely orm
+  return new Kysely<Database>({
     dialect,
   });
 });
+```
 
+3. Make your own `wrapTransaction` function that incorporates a database context
+
+```typescript
 async function wrapTransaction<T>(
   callback: Parameters<typeof wrapTransactionFn<Database, T>>[0],
 ): Promise<T> {
   return await wrapTransactionFn<Database, T>(callback);
 }
+```
 
-const data = await wrapTransaction(async (trx) => {
-  return trx.selectFrom("hello").selectAll().execute();
+4. Use the `wrapTransaction` function to execute queries
+
+```typescript
+const users = await wrapTransaction(async (trx) => {
+  return await trx.selectFrom("users").selectAll().execute();
 });
 ```
 
 ## 🩺 Testing
 
-See detail at `./tests/testing/utils_test.ts`.
+> [!TIP]\
+> See examples at `./tests/testing/utils_test.ts`.
 
-> [!IMPORTANT]\
-> To fix `leaking resources` error, you should end all connections between
-> cases.
+`setupTesting` function is provided to set up the testing environment. It stubs
+transaction functions, and each test runs in a transaction that is rolled back
+after the test. Theoretically, tests are isolated from each other, and can be
+run in parallel.
 
-```typescript
-import {
-  PostgresJSDialect,
-  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";
+1. Add a helper function to setup the testing database
 
-setup(() => {
-  const dialect = new PostgresJSDialect({
-    postgres: postgres(
-      {
-        database: "postgres",
-        hostname: "localhost",
-        password: "postgres",
-        port: 5432,
-        user: "postgres",
-        max: 10,
-      },
-    ),
+```typescript
+// test_helper.ts
+
+import { PostgresJSDialect, setup } from "kysely-deno-postgres-dialect";
+import { Kysely } from "kysely";
+import postgres from "postgresjs";
+
+export function setupTestingDB() {
+  setup(() => {
+    const dialect = new PostgresJSDialect({
+      postgres: postgres(
+        {
+          database: "postgres",
+          hostname: "localhost",
+          password: "postgres",
+          port: 5432,
+          user: "postgres",
+          max: 10,
+        },
+      ),
+    });
+
+    return new Kysely<Database>({
+      dialect,
+    });
   });
+}
+```
 
-  return new Kysely<Database>({
-    dialect,
-  });
-});
+2. Setup the testing environment in the test files, and write tests
 
+```typescript
 // test files
 
-const {
-  beforeAllFn,
-  beforeEachFn,
-  afterEachFn,
-  afterAllFn,
-} = setupTesting(stub);
+import { setupTesting } from "kysely-deno-postgres-dialect/testing";
+import { stub } from "jsr:@std/testing/mock";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  it,
+} from "jsr:@std/testing/bdd";
 
-describe("tests", () => {
-  beforeAll(async () => {
-    await beforeAllFn();
-  });
-  afterAll(async () => {
-    await afterAllFn();
-  });
-  beforeEach(async () => {
-    await beforeEachFn();
-  });
-  afterEach(async () => {
-    // note: fix Leaking resources error
-    await afterEachFn();
-  });
+setupTesting({ stub, beforeEach, afterEach, beforeAll, afterAll });
 
+describe("this is a description", () => {
   it("works", async () => {
     // snip
   });

deno.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://deno.land/x/deno/cli/schemas/config-file.v1.json",
   "name": "@byzanteam/kysely-deno-postgres-dialect",
-  "version": "0.27.6",
+  "version": "0.27.7",
   "exports": {
     ".": "./mod.ts",
     "./testing": "./testing.ts"

mod.ts

@@ -1,4 +1,3 @@
-export { type DatabaseConnection, sql } from "kysely";
 export {
   PostgresJSConnection,
   PostgresJSDialect,

src/connection.ts

@@ -7,6 +7,9 @@ import {
 import type postgres from "postgresjs";
 import { PostgresJSDialectError } from "./errors.ts";
 
+/**
+ * A database connection that uses the `postgresjs` library.
+ */
 export class PostgresJSConnection implements DatabaseConnection {
   #reservedConnection: postgres.ReservedSql;
 

src/dialect.ts

@@ -13,6 +13,9 @@ import { PostgresJSDriver } from "./driver.ts";
 import type { PostgresJSDialectConfig } from "./types.ts";
 import { freeze } from "./postgres-utils.ts";
 
+/**
+ * A kysely dialect for PostgreSQL using the `postgres` library.
+ */
 export class PostgresJSDialect implements Dialect {
   readonly #config: PostgresJSDialectConfig;
 

src/errors.ts

@@ -1,3 +1,6 @@
+/**
+ * Custom error class for PostgresJSDialect
+ */
 export class PostgresJSDialectError extends Error {
   constructor(message: string) {
     super(message);

src/testing/utils.ts

@@ -21,34 +21,47 @@ async function doWrapTransactionStub<T, U>(
 }
 
 type Stub = { restore: () => unknown };
+type beforeAll<T> = (fn: (this: T) => void | Promise<void>) => void;
+type afterAll<T> = (fn: (this: T) => void | Promise<void>) => void;
+type beforeEach<T> = (fn: (this: T) => void | Promise<void>) => void;
+type afterEach<T> = (fn: (this: T) => void | Promise<void>) => void;
+
+interface setupTestingOptions {
+  stub: (...args: unknown[]) => Stub;
+  beforeAll: beforeAll<unknown>;
+  beforeEach: beforeEach<unknown>;
+  afterEach: afterEach<unknown>;
+  afterAll: afterAll<unknown>;
+}
 
 /**
- * Setup a database for testing.
+ * Setup the database for testing.
+ * It will create a transaction for each test case and rollback the transaction after each test case.
  *
  * @param stub - The stub to use for wrapping the transaction.
- * @returns The `beforeAllFn`, `beforeEachFn`, `afterEachFn` and `afterAllFn` functions to use in your test suite.
+ * @param beforeAll - The `beforeAll` function from the test suite.
+ * @param beforeEach - The `beforeEach` function from the test suite.
+ * @param afterEach - The `afterEach` function from the test suite.
+ * @param afterAll - The `afterAll` function from the test suite.
+ * @returns void
+ *
  * @example
  * ```ts
- * import { stub } from "https://deno.land/std@0.210.0/testing/mock.ts";
- * const { beforeEachFn, afterEachFn } = setupTesting(stub)
+ * import { stub } from "jsr:@std/testing/mock";
+ * import bdd from "jsr:@std/testing/bdd";
+ * setupTesting({stub, ...bdd})
  * ```
  */
 export function setupTesting<T>(
-  stub: (...args: unknown[]) => Stub,
-): {
-  beforeAllFn: () => Promise<void>;
-  beforeEachFn: () => Promise<void>;
-  afterEachFn: () => Promise<void>;
-  afterAllFn: () => Promise<void>;
-} {
+  { stub, beforeAll, beforeEach, afterEach, afterAll }: setupTestingOptions,
+): void {
   let transactionStub: Maybe<Stub>;
 
-  // deno-lint-ignore require-await
-  const beforeAllFn = async () => {
+  beforeAll(() => {
     getDB<T>();
-  };
+  });
 
-  const beforeEachFn = async () => {
+  beforeEach(async () => {
     const db = getDB<T>();
 
     const { trx, rollback } = await begin(db);
@@ -60,20 +73,19 @@ export function setupTesting<T>(
       "doWrapTransaction",
       doWrapTransactionStub,
     );
-  };
+  });
 
-  const afterEachFn = async () => {
+  afterEach(async () => {
     if (transaction) {
       await rollbackFn?.();
       transaction = undefined;
     }
 
     transactionStub?.restore();
-  };
+  });
 
-  const afterAllFn = async () => {
+  afterAll(async () => {
+    // To fix `leaking resources` error, close the database connection
     await closeDB();
-  };
-
-  return { beforeAllFn, beforeEachFn, afterEachFn, afterAllFn };
+  });
 }

src/utils.ts

@@ -10,6 +10,11 @@ type SetupFn<T> = () => DB<T>;
 // deno-lint-ignore no-explicit-any
 let setupFn: Maybe<SetupFn<any>>;
 
+/**
+ * Sets up the database instance using the provided setup function.
+ * This function must be called before any database operations are performed.
+ * @param setup - A function that returns a configured Kysely database instance.
+ */
 export function setup<T>(setup: SetupFn<T>): void {
   setupFn = setup;
 }
@@ -23,10 +28,18 @@ function newDB<T>(): DB<T> {
   throw new Error("Please call setup() before using the database");
 }
 
+/**
+ * Get the database instance. Ensure you call `setup` before calling this function.
+ * @returns The database instance.
+ * @throws Will throw an error if `setup` has not been called.
+ */
 export function getDB<T>(): Kysely<T> {
   return db || newDB<T>();
 }
 
+/**
+ * Closes the database connection.
+ */
 export async function closeDB() {
   if (db) {
     await db.destroy();
@@ -40,6 +53,18 @@ async function doWrapTransaction<T, U>(callback: Callback<T, U>): Promise<U> {
   return await getDB<T>().transaction().execute(callback);
 }
 
+/**
+ * Wraps a callback in a transaction.
+ * @param callback - The callback to wrap.
+ * @returns The result of the callback.
+ *
+ * @example
+ * ```ts
+ * const users = await wrapTransaction(async (trx) => {
+ *   return await trx.selectFrom("user").selectAll().execute();
+ * });
+ *  ```
+ */
 export async function wrapTransaction<T, U>(
   callback: Callback<T, U>,
 ): Promise<U> {

tests/deps.ts

@@ -0,0 +1,3 @@
+export * from "jsr:@std/testing/bdd";
+export * from "jsr:@std/testing/mock";
+export * from "jsr:@std/assert";