neon-testing 2.7.0 → 3.0.0-beta.1

package/README.md

@@ -5,7 +5,9 @@
 [![GitHub release](https://img.shields.io/github/v/release/starmode-base/neon-testing)](https://github.com/starmode-base/neon-testing/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-A [Vitest](https://vitest.dev/) utility for seamless integration tests with [Neon Postgres](https://neon.com/). <!-- A [STΛR MODΞ](https://starmode.dev) open-source project. -->
+A testing utility for seamless integration tests with [Neon Postgres](https://neon.com/), for [Vitest](https://vitest.dev/) and [Bun Test](https://bun.com/docs/cli/test).
+
+<!-- A [STΛR MODΞ](https://starmode.dev) open-source project. -->
 
 Each test file runs against its own isolated PostgreSQL database (Neon branch), ensuring clean, parallel, and reproducible testing of code that interacts with a database. Because it uses a real, isolated clone of your production database, you can test code logic that depends on database features, such as transaction rollbacks, unique constraints, and more.
 
@@ -29,7 +31,7 @@ Each test file runs against its own isolated PostgreSQL database (Neon branch),
 - 🔄 **Isolated test environments** - Each test file runs against its own Postgres database with your actual schema and constraints
 - 🧹 **Automatic cleanup** - Neon test branches are created and destroyed automatically
 - 🐛 **Debug friendly** - Option to preserve test branches for debugging failed tests
-- 🛡️ **TypeScript native** - With JavaScript support
+- 🛡️ **TypeScript native** - Ships compiled JavaScript with type declarations and source maps too
 - 🎯 **ESM only** - No CommonJS support
 
 ## How it works
@@ -41,7 +43,9 @@ Each test file runs against its own isolated PostgreSQL database (Neon branch),
 
 ### Test isolation
 
-Tests in the same file share a single database instance (Neon branch). This means test files are fully isolated from each other, but individual tests within a file are intentionally not isolated. This works because Vitest runs test files in [parallel](https://vitest.dev/guide/parallelism.html), while tests within each file run sequentially.
+Each test file runs against its own database instance (Neon branch), so test files are fully isolated from each other. Tests within a single file share that branch and run sequentially — individual tests within a file are intentionally not isolated.
+
+Vitest and Bun differ in how they execute files. Vitest runs each file in its own process, [in parallel](https://vitest.dev/guide/parallelism.html), while Bun runs every file in [a single shared process](https://bun.com/docs/test), one after another by default. File-level isolation is the same on both — each file gets its own branch — but Vitest creates those branches concurrently whereas Bun creates them one at a time.
 
 If you prefer individual tests to be isolated, you can [reset the database](examples/isolated.test.ts) in a `beforeEach` lifecycle hook.
 
@@ -59,7 +63,11 @@ Test branches are automatically deleted after your tests complete. As a safety n
 ### Install
 
 ```sh
+# Vitest
 bun add -d neon-testing vitest
+
+# Bun Test
+bun add -d neon-testing
 ```
 
 ### Minimal example
@@ -67,7 +75,7 @@ bun add -d neon-testing vitest
 ```ts
 // minimal.test.ts
 import { expect, test } from "vitest";
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest";
 import { Pool } from "@neondatabase/serverless";
 
 // Enable Neon test branch for this test file
@@ -75,6 +83,7 @@ makeNeonTesting({
   apiKey: process.env.NEON_API_KEY!,
   projectId: process.env.NEON_PROJECT_ID!,
   // Recommended for Neon WebSocket drivers to automatically close connections
+  // (Vitest only)
   autoCloseWebSockets: true,
 })();
 
@@ -93,21 +102,29 @@ Source: [`examples/minimal.test.ts`](examples/minimal.test.ts)
 
 ### Recommended usage
 
-#### 1. Plugin setup
+#### 1. Setup
 
-First, add the Vite plugin to clear any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
+Register `neon-testing/setup` so any existing `DATABASE_URL` is cleared before tests run. A test file that forgets to enable branching then fails loudly instead of silently writing to a real database.
 
 ```ts
 // vitest.config.ts
 import { defineConfig } from "vitest/config";
-import { neonTesting } from "neon-testing/vite";
 
 export default defineConfig({
-  plugins: [neonTesting()],
+  test: {
+    setupFiles: ["neon-testing/setup"],
+  },
 });
 ```
 
-This plugin is recommended but not required. Without it, tests might accidentally use your existing `DATABASE_URL` (from `.env` files or environment variables) instead of the isolated test databases that Neon Testing creates. This can happen if you forget to call `neonTesting()` in a test file where database writes happen.
+For Bun, add it to `bunfig.toml` instead:
+
+```toml
+[test]
+preload = ["neon-testing/setup"]
+```
+
+Recommended but not required. Without it, a test file that forgets to call `neonTesting()` could fall back to your real `DATABASE_URL` (from `.env` or the environment) instead of an isolated test branch.
 
 #### 2. Configuration
 
@@ -115,7 +132,7 @@ Use the `makeNeonTesting` factory to generate a lifecycle function for your test
 
 ```ts
 // neon-testing.ts
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest"; // or "neon-testing/bun"
 
 // Export a configured lifecycle function to use in test files
 export const neonTesting = makeNeonTesting({
@@ -139,6 +156,7 @@ import { Pool } from "@neondatabase/serverless";
 // Enable Neon test branch for this test file
 neonTesting({
   // Recommended for Neon WebSocket drivers to automatically close connections
+  // (Vitest only)
   autoCloseWebSockets: true,
 });
 
@@ -157,20 +175,28 @@ Source: [`examples/recommended.test.ts`](examples/recommended.test.ts)
 
 ## Drivers
 
-This library works with any database driver that supports Neon Postgres and Vitest. The examples below demonstrate connection management, transaction support, and test isolation patterns for some popular drivers.
+This library works with any database driver that supports Neon Postgres.
+
+### Closing connections
+
+Some drivers keep a connection open after a test finishes — [Neon's WebSocket driver](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-websockets) and [node-postgres](https://www.npmjs.com/package/pg). If the test branch is deleted while a connection is still open, the driver errors. Avoid it in one of three ways:
 
-**IMPORTANT:** For [Neon WebSocket drivers](https://neon.com/docs/serverless/serverless-driver), enable `autoCloseWebSockets` in your `makeNeonTesting()` or `neonTesting()` configuration. This automatically closes WebSocket connections when deleting test branches, preventing connection termination errors.
+- close the connection yourself (e.g. `await pool.end()`)
+- enable `autoCloseWebSockets` (WebSocket driver only, Vitest only)
+- keep the branch with `deleteBranch: false`
+
+[Neon's HTTP driver](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-http) and [Postgres.js](https://www.npmjs.com/package/postgres) close their own connections, so they need none of this.
 
 ### Examples
 
-- [Neon serverless WebSocket](examples/drivers/ws-neon.test.ts)
-- [Neon serverless WebSocket + Drizzle](examples/drivers/ws-neon-drizzle.test.ts)
-- [Neon serverless HTTP](examples/drivers/http-neon.test.ts)
-- [Neon serverless HTTP + Drizzle](examples/drivers/http-neon-drizzle.test.ts)
-- [node-postgres](examples/drivers/tcp-pg.test.ts)
-- [node-postgres + Drizzle](examples/drivers/tcp-pg-drizzle.test.ts)
-- [Postgres.js](examples/drivers/tcp-postgres.test.ts)
-- [Postgres.js + Drizzle](examples/drivers/tcp-postgres-drizzle.test.ts)
+- [Neon serverless WebSocket](tests-vitest/drivers/ws-neon.test.ts)
+- [Neon serverless WebSocket + Drizzle](tests-vitest/drivers/ws-neon-drizzle.test.ts)
+- [Neon serverless HTTP](tests-vitest/drivers/http-neon.test.ts)
+- [Neon serverless HTTP + Drizzle](tests-vitest/drivers/http-neon-drizzle.test.ts)
+- [node-postgres](tests-vitest/drivers/tcp-pg.test.ts)
+- [node-postgres + Drizzle](tests-vitest/drivers/tcp-pg-drizzle.test.ts)
+- [Postgres.js](tests-vitest/drivers/tcp-postgres.test.ts)
+- [Postgres.js + Drizzle](tests-vitest/drivers/tcp-postgres-drizzle.test.ts)
 
 ## Configuration
 
@@ -179,10 +205,10 @@ You configure Neon Testing in two places:
 - **Base settings** in `makeNeonTesting()`
 - **Optional overrides** when calling the returned function (e.g., `neonTesting()`)
 
-Configure these in `makeNeonTesting()` and optionally override per test file when calling the returned function.
+Configure these in `makeNeonTesting()`; every option except `apiKey` can also be overridden per test file when calling the returned function.
 
 ```ts
-export interface NeonTestingOptions {
+export interface MakeNeonTestingOptions {
   /**
    * The Neon API key, this is used to create and teardown test branches (required)
    *
@@ -224,6 +250,8 @@ export interface NeonTestingOptions {
    * Suppresses the specific Neon WebSocket "Connection terminated unexpectedly"
    * error that may surface when deleting a branch with open WebSocket
    * connections
+   *
+   * Vitest only.
    */
   autoCloseWebSockets?: boolean;
   /**
@@ -273,7 +301,7 @@ Configure the base settings in `makeNeonTesting()`:
 
 ```ts
 // neon-testing.ts
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest";
 
 export const neonTesting = makeNeonTesting({
   apiKey: process.env.NEON_API_KEY!,
@@ -373,7 +401,9 @@ It's easy to run Neon integration tests in CI/CD pipelines:
 
 ## API Reference
 
-### Main exports (`neon-testing`)
+### Runner entry (`neon-testing/vitest` or `neon-testing/bun`)
+
+Both entries export the same `makeNeonTesting`; they differ only in which runner's `beforeAll`/`afterAll` hooks they wire up. (For other runners, `neon-testing/core` takes the hooks directly.)
 
 #### makeNeonTesting(options)
 
@@ -381,7 +411,7 @@ The factory function that creates a configured lifecycle function for your tests
 
 ```ts
 // neon-testing.ts
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest";
 
 export const neonTesting = makeNeonTesting({
   apiKey: process.env.NEON_API_KEY!,
@@ -434,24 +464,11 @@ test("access branch information", () => {
 
 See the [Neon Branch API documentation](https://api-docs.neon.tech/reference/getprojectbranch) for all available properties.
 
-### Vite plugin (`neon-testing/vite`)
-
-The Vite plugin clears any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
-
-```ts
-import { defineConfig } from "vitest/config";
-import { neonTesting } from "neon-testing/vite";
-
-export default defineConfig({
-  plugins: [neonTesting()],
-});
-```
-
-**Options:**
+### Setup (`neon-testing/setup`)
 
-- `debug` (boolean, default: `false`) - Enable debug logging
+A zero-config preload that clears `DATABASE_URL` before tests run, so a file that forgets to call `neonTesting()` can't reach a real database. Register it with your runner — Vitest `setupFiles` or Bun `bunfig` `preload` (see [Recommended usage](#recommended-usage)).
 
-This plugin is recommended but not required. Without it, tests might accidentally use your existing `DATABASE_URL` instead of isolated test databases.
+Set `NEON_TESTING_DEBUG=true` to log when it clears a value.
 
 ### Utilities (`neon-testing/utils`)
 

package/dist/bun.d.ts

@@ -0,0 +1,11 @@
+import type { MakeNeonTestingOptions } from "./core.js";
+export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core.js";
+/**
+ * Create a Neon test-branch factory wired to Bun's lifecycle hooks.
+ */
+export declare function makeNeonTesting(options: MakeNeonTestingOptions): {
+    (overrides?: import("./core.js").NeonTestingOptions): () => import("@neondatabase/api-client").Branch | undefined;
+    deleteAllTestBranches: () => Promise<void>;
+    api: import("@neondatabase/api-client").Api<unknown>;
+};
+//# sourceMappingURL=bun.d.ts.map

package/dist/bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,YAAY,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE5E;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB;;;;EAE9D"}

package/dist/bun.js

@@ -0,0 +1,10 @@
+/// <reference types="bun" />
+import { beforeAll, afterAll } from "bun:test";
+import { makeNeonTestingCore } from "./core.js";
+/**
+ * Create a Neon test-branch factory wired to Bun's lifecycle hooks.
+ */
+export function makeNeonTesting(options) {
+    return makeNeonTestingCore({ ...options, hooks: { beforeAll, afterAll } });
+}
+//# sourceMappingURL=bun.js.map

package/dist/bun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.js","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAKhD;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,OAAO,mBAAmB,CAAC,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC7E,CAAC"}

package/dist/{index.d.ts → core.d.ts}

@@ -2,7 +2,30 @@
  * https://neon.com/docs/reference/typescript-sdk
  */
 import { type Branch } from "@neondatabase/api-client";
-export interface NeonTestingOptions {
+/**
+ * Test-runner lifecycle hooks
+ *
+ * Injected so the core stays runner-agnostic. Most users don't build these by
+ * hand — import the pre-wired factory from `neon-testing/vitest` or
+ * `neon-testing/bun`, which supply them automatically.
+ */
+export interface NeonTestingHooks {
+    beforeAll: (fn: () => void | Promise<void>) => void;
+    afterAll: (fn: () => void | Promise<void>) => void;
+}
+/**
+ * Configuration for the Neon test-branch factory.
+ *
+ * `hooks` are injected by the per-runner entry (`neon-testing/vitest` or
+ * `neon-testing/bun`); the remaining fields control how each test branch is
+ * created and torn down.
+ */
+export interface MakeNeonTestingCoreOptions {
+    /**
+     * Test-runner lifecycle hooks (supplied by `neon-testing/vitest` or
+     * `neon-testing/bun`)
+     */
+    hooks: NeonTestingHooks;
     /**
      * The Neon API key, this is used to create and teardown test branches (required)
      *
@@ -44,6 +67,9 @@ export interface NeonTestingOptions {
      * Suppresses the specific Neon WebSocket "Connection terminated unexpectedly"
      * error that may surface when deleting a branch with open WebSocket
      * connections
+     *
+     * Vitest only — under Bun the uncaughtException suppression does not
+     * intercept, so close connections explicitly there instead.
      */
     autoCloseWebSockets?: boolean;
     /**
@@ -85,44 +111,38 @@ export interface NeonTestingOptions {
      */
     sslMode?: "verify-full" | "require";
 }
-/** Options for overriding test database setup (excludes apiKey) */
-export type NeonTestingOverrides = Omit<Partial<NeonTestingOptions>, "apiKey">;
+/** Options for the `makeNeonTesting` factories — core options minus the injected hooks */
+export type MakeNeonTestingOptions = Omit<MakeNeonTestingCoreOptions, "hooks">;
+/** Per-file overrides accepted by the returned `neonTesting()` function */
+export type NeonTestingOptions = Partial<Omit<MakeNeonTestingOptions, "apiKey">>;
 /**
- * Factory function that creates a Neon test database setup/teardown function
- * for Vitest test suites.
- *
- * @param factoryOptions - Configuration options (see {@link NeonTestingOptions})
- * @returns A setup/teardown function with attached utilities:
- *  - `deleteAllTestBranches()` - Cleanup method to delete all test branches
- *  - `api` - Direct access to the Neon API client
+ * Low-level factory that creates a Neon test-branch setup/teardown function.
+ * Runner-agnostic — you inject the lifecycle hooks via `options.hooks`.
  *
- * @example
- * ```ts
- * // neon-testing.ts
- * import { makeNeonTesting } from "neon-testing";
+ * Most users want a pre-wired entry instead: `neon-testing/vitest` or
+ * `neon-testing/bun`. Reach for this core factory only for other runners
+ * (jest, node:test, …).
  *
- * export const neonTesting = makeNeonTesting({
- *   apiKey: "apiKey",
- *   projectId: "projectId",
- * });
- * ```
+ * @param factoryOptions - see {@link MakeNeonTestingCoreOptions}
+ * @returns A setup/teardown function with attached utilities:
+ *  - `deleteAllTestBranches()` - delete all test branches
+ *  - `api` - the Neon API client
  *
  * @example
  * ```ts
- * // my-test.test.ts
- * import { neonTesting } from "./neon-testing";
- *
- * const getBranch = neonTesting();
+ * import { beforeAll, afterAll } from "vitest"; // or any runner
+ * import { makeNeonTestingCore } from "neon-testing/core";
  *
- * test("my test", () => {
- *   const branch = getBranch();
- *   console.log(branch.id);
+ * export const neonTesting = makeNeonTestingCore({
+ *   apiKey: process.env.NEON_API_KEY!,
+ *   projectId: process.env.NEON_PROJECT_ID!,
+ *   hooks: { beforeAll, afterAll },
  * });
  * ```
  */
-export declare function makeNeonTesting(factoryOptions: NeonTestingOptions): {
-    (overrides?: NeonTestingOverrides): () => Branch | undefined;
+export declare function makeNeonTestingCore(factoryOptions: MakeNeonTestingCoreOptions): {
+    (overrides?: NeonTestingOptions): () => Branch | undefined;
     deleteAllTestBranches: () => Promise<void>;
     api: import("@neondatabase/api-client").Api<unknown>;
 };
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,0BAA0B,CAAC;AAOlC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACpD,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACrC;AAED,0FAA0F;AAC1F,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,0BAA0B,EAAE,OAAO,CAAC,CAAC;AAE/E,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,0BAA0B;iBA0C5B,kBAAkB;;;EA6KjC"}

package/dist/{index.js → core.js}

@@ -2,77 +2,37 @@
  * https://neon.com/docs/reference/typescript-sdk
  */
 import { createApiClient, EndpointType, } from "@neondatabase/api-client";
-import { afterAll, beforeAll } from "vitest";
+import { applySslMode } from "./lib/ssl.js";
+import { validateExpiresIn } from "./lib/expires-in.js";
+import { neonWsErrorHandler } from "./lib/ws-error.js";
+import { withRetry } from "./lib/with-retry.js";
+import { CLEARED_DATABASE_URL } from "./lib/cleared-database-url.js";
 /**
- * Rewrite the `sslmode` (and related) query params on a Neon connection URI.
+ * Low-level factory that creates a Neon test-branch setup/teardown function.
+ * Runner-agnostic — you inject the lifecycle hooks via `options.hooks`.
  *
- * Neon's API returns URIs with `sslmode=require`. In pg v9 /
- * pg-connection-string v3 this mode will adopt libpq semantics (encrypt
- * without CA verification) instead of today's effective `verify-full`.
- */
-function applySslMode(uri, mode) {
-    if (mode === undefined)
-        return uri;
-    const url = new URL(uri);
-    url.searchParams.set("sslmode", mode);
-    if (mode === "require") {
-        url.searchParams.set("uselibpqcompat", "true");
-    }
-    else {
-        url.searchParams.delete("uselibpqcompat");
-    }
-    return url.toString();
-}
-/**
- * Validates the expiresIn option
- */
-function validateExpiresIn(expiresIn) {
-    if (expiresIn !== null && expiresIn !== undefined) {
-        if (!Number.isInteger(expiresIn)) {
-            throw new Error("expiresIn must be an integer");
-        }
-        if (expiresIn <= 0) {
-            throw new Error("expiresIn must be a positive integer");
-        }
-        if (expiresIn > 2592000) {
-            throw new Error("expiresIn must not exceed 30 days (2,592,000 seconds)");
-        }
-    }
-}
-/**
- * Factory function that creates a Neon test database setup/teardown function
- * for Vitest test suites.
+ * Most users want a pre-wired entry instead: `neon-testing/vitest` or
+ * `neon-testing/bun`. Reach for this core factory only for other runners
+ * (jest, node:test, …).
  *
- * @param factoryOptions - Configuration options (see {@link NeonTestingOptions})
+ * @param factoryOptions - see {@link MakeNeonTestingCoreOptions}
  * @returns A setup/teardown function with attached utilities:
- *  - `deleteAllTestBranches()` - Cleanup method to delete all test branches
- *  - `api` - Direct access to the Neon API client
+ *  - `deleteAllTestBranches()` - delete all test branches
+ *  - `api` - the Neon API client
  *
  * @example
  * ```ts
- * // neon-testing.ts
- * import { makeNeonTesting } from "neon-testing";
+ * import { beforeAll, afterAll } from "vitest"; // or any runner
+ * import { makeNeonTestingCore } from "neon-testing/core";
  *
- * export const neonTesting = makeNeonTesting({
- *   apiKey: "apiKey",
- *   projectId: "projectId",
- * });
- * ```
- *
- * @example
- * ```ts
- * // my-test.test.ts
- * import { neonTesting } from "./neon-testing";
- *
- * const getBranch = neonTesting();
- *
- * test("my test", () => {
- *   const branch = getBranch();
- *   console.log(branch.id);
+ * export const neonTesting = makeNeonTestingCore({
+ *   apiKey: process.env.NEON_API_KEY!,
+ *   projectId: process.env.NEON_PROJECT_ID!,
+ *   hooks: { beforeAll, afterAll },
  * });
  * ```
  */
-export function makeNeonTesting(factoryOptions) {
+export function makeNeonTestingCore(factoryOptions) {
     // Validate factory options
     validateExpiresIn(factoryOptions.expiresIn);
     const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });
@@ -91,15 +51,15 @@ export function makeNeonTesting(factoryOptions) {
         }
     }
     /**
-     * Setup/teardown function for Vitest test suites
+     * Setup/teardown function for a test file.
      *
-     * Registers Vitest lifecycle hooks that:
+     * Registers lifecycle hooks (via the injected `hooks`) that:
      * - Create an isolated test branch from your parent branch
      * - Set `DATABASE_URL` environment variable to the test branch connection URI
      * - Automatically delete the test branch after tests complete (unless `deleteBranch: false`)
      * - Automatically expire branches after 10 minutes for cleanup (unless `expiresIn: null`)
      *
-     * @param overrides - Optional overrides for the factory options
+     * @param overrides - Optional per-file overrides for the factory options
      * @returns A function that provides access to the current Neon branch object
      */
     const neonTesting = (
@@ -131,9 +91,11 @@ export function makeNeonTesting(factoryOptions) {
             const { data } = await apiClient.createProjectBranch(options.projectId, {
                 branch: {
                     name: `test/${crypto.randomUUID()}`,
-                    parent_id: options.parentBranchId,
-                    init_source: options.schemaOnly ? "schema-only" : undefined,
-                    expires_at: expiresAt,
+                    ...(options.parentBranchId
+                        ? { parent_id: options.parentBranchId }
+                        : {}),
+                    ...(options.schemaOnly ? { init_source: "schema-only" } : {}),
+                    ...(expiresAt ? { expires_at: expiresAt } : {}),
                 },
                 endpoints: [{ type: EndpointType.ReadWrite }],
                 annotation_value: {
@@ -184,7 +146,7 @@ export function makeNeonTesting(factoryOptions) {
             await apiClient.deleteProjectBranch(options.projectId, branch.id);
             branch = undefined;
         }
-        beforeAll(async () => {
+        factoryOptions.hooks.beforeAll(async () => {
             process.env.DATABASE_URL = await withRetry(createBranch, {
                 maxRetries: 8,
                 baseDelayMs: 1000,
@@ -212,8 +174,10 @@ export function makeNeonTesting(factoryOptions) {
                 }
             }
         });
-        afterAll(async () => {
-            process.env.DATABASE_URL = undefined;
+        factoryOptions.hooks.afterAll(async () => {
+            // Overwrite (not `delete`) so DATABASE_URL no longer points at the test
+            // branch; see CLEARED_DATABASE_URL for why a sentinel rather than delete.
+            process.env.DATABASE_URL = CLEARED_DATABASE_URL;
             // Close all tracked Neon WebSocket connections before deleting the branch
             if (options.autoCloseWebSockets && neonSockets) {
                 // Suppress Neon WebSocket "Connection terminated unexpectedly" error
@@ -237,56 +201,4 @@ export function makeNeonTesting(factoryOptions) {
     neonTesting.api = apiClient;
     return neonTesting;
 }
-/**
- * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
- * error
- */
-const neonWsErrorHandler = (error) => {
-    const isNeonWsClose = error.message.includes("Connection terminated unexpectedly") &&
-        error.stack?.includes("@neondatabase/serverless");
-    if (isNeonWsClose) {
-        // Swallow this specific Neon WS termination error
-        return;
-    }
-    // For any other error, detach and rethrow
-    throw error;
-};
-/**
- * Reusable API call wrapper with automatic retry on 423 errors with exponential
- * backoff
- *
- * https://neon.com/docs/reference/typescript-sdk#error-handling
- * https://neon.com/docs/changelog/2022-07-20
- */
-async function withRetry(fn, options) {
-    if (!Number.isInteger(options.maxRetries) || options.maxRetries <= 0) {
-        throw new Error("maxRetries must be a positive integer");
-    }
-    if (!Number.isInteger(options.baseDelayMs) || options.baseDelayMs <= 0) {
-        throw new Error("baseDelayMs must be a positive integer");
-    }
-    for (let attempt = 1; attempt <= options.maxRetries; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            const status = error?.response?.status;
-            // Retry on 423 (resource locked) with exponential backoff
-            if (status === 423 && attempt < options.maxRetries) {
-                const delay = options.baseDelayMs * Math.pow(2, attempt - 1);
-                console.log(`API call failed with 423, retrying in ${delay}ms (attempt ${attempt}/${options.maxRetries})`);
-                await new Promise((resolve) => setTimeout(resolve, delay));
-                continue;
-            }
-            // Surface Neon API error details that are otherwise buried in the Axios error
-            if (error?.response?.data?.code) {
-                const { code, message } = error.response.data;
-                throw new Error(`Neon API error - HTTP ${status} - ${code} - ${message}`, { cause: error });
-            }
-            // Non-API errors (network, timeouts, etc.) pass through as-is
-            throw error;
-        }
-    }
-    throw new Error("apiCallWithRetry reached unexpected end");
-}
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/lib/barrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barrier.d.ts","sourceRoot":"","sources":["../../src/lib/barrier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,uBAiB1C"}

package/dist/lib/barrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"barrier.js","sourceRoot":"","sources":["../../src/lib/barrier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAmB,CAAC;IAExB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,IAAI,EAAE;QAChB,OAAO,EAAE,CAAC;QAEV,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;YACtB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,OAAO,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/cleared-database-url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sentinel written to `DATABASE_URL` to clear it, instead of `delete`.
+ *
+ * Keeps the value a string for consumers that type `DATABASE_URL` as required
+ * (so the library never has to fight their env typing), and is an invalid
+ * connection string so a test that forgot `neonTesting()` fails loudly rather
+ * than silently reaching a real database.
+ */
+export declare const CLEARED_DATABASE_URL = "neon-testing: DATABASE_URL cleared, call neonTesting()";
+//# sourceMappingURL=cleared-database-url.d.ts.map

package/dist/lib/cleared-database-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleared-database-url.d.ts","sourceRoot":"","sources":["../../src/lib/cleared-database-url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,2DAA2D,CAAC"}

package/dist/lib/cleared-database-url.js

@@ -0,0 +1,10 @@
+/**
+ * Sentinel written to `DATABASE_URL` to clear it, instead of `delete`.
+ *
+ * Keeps the value a string for consumers that type `DATABASE_URL` as required
+ * (so the library never has to fight their env typing), and is an invalid
+ * connection string so a test that forgot `neonTesting()` fails loudly rather
+ * than silently reaching a real database.
+ */
+export const CLEARED_DATABASE_URL = `neon-testing: DATABASE_URL cleared, call neonTesting()`;
+//# sourceMappingURL=cleared-database-url.js.map

package/dist/lib/cleared-database-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleared-database-url.js","sourceRoot":"","sources":["../../src/lib/cleared-database-url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,wDAAwD,CAAC"}

package/dist/lib/expires-in.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Validates the expiresIn option
+ */
+export declare function validateExpiresIn(expiresIn: number | null | undefined): void;
+//# sourceMappingURL=expires-in.d.ts.map

package/dist/lib/expires-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expires-in.d.ts","sourceRoot":"","sources":["../../src/lib/expires-in.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,QAoBrE"}