neon-testing 2.0.1-beta.9 → 2.1.1

package/README.md

@@ -1,8 +1,10 @@
-# Neon testing
+# Neon Testing
 
 [![Integration tests](https://github.com/starmode-base/neon-testing/actions/workflows/test.yml/badge.svg)](https://github.com/starmode-base/neon-testing/actions/workflows/test.yml)
+[![npm version](https://img.shields.io/npm/v/neon-testing)](https://www.npmjs.com/package/neon-testing)
+[![GitHub release](https://img.shields.io/github/v/release/starmode-base/neon-testing)](https://github.com/starmode-base/neon-testing/releases)
 
-A [Vitest](https://vitest.dev/) utility for seamless integration tests with [Neon Postgres](https://neon.com/).
+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. -->
 
 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.
 
@@ -13,7 +15,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** - No JavaScript support
+- 🛡️ **TypeScript native** - With JavaScript support
 - 🎯 **ESM only** - No CommonJS support
 
 ## How it works
@@ -41,12 +43,12 @@ If you prefer individual tests to be isolated, you can [reset the database](exam
 ### Install
 
 ```sh
-bun add -d neon-testing
+bun add -d neon-testing vitest
 ```
 
 ### Minimal example
 
-```typescript
+```ts
 // minimal.test.ts
 import { expect, test } from "vitest";
 import { makeNeonTesting } from "neon-testing";
@@ -73,11 +75,27 @@ test("database operations", async () => {
 
 ### Recommended usage
 
-#### 1. Configuration
+#### 1. Plugin setup
+
+First, add the Vite plugin to clear any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
+
+```ts
+// vitest.config.ts or vite.config.ts
+import { defineConfig } from "vitest/config";
+import { neonTesting } from "neon-testing/utils";
+
+export default defineConfig({
+  plugins: [neonTesting()],
+});
+```
+
+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 `withNeonTestBranch()` in a test file where database writes happen.
+
+#### 2. Configuration
 
 Use the `makeNeonTesting` factory to generate a lifecycle function for your tests.
 
-```typescript
+```ts
 // test-setup.ts
 import { makeNeonTesting } from "neon-testing";
 
@@ -88,11 +106,11 @@ export const withNeonTestBranch = makeNeonTesting({
 });
 ```
 
-#### 2. Enable database testing
+#### 3. Enable database testing
 
 Then call the exported test lifecycle function in the test files where you need database access.
 
-```typescript
+```ts
 // recommended.test.ts
 import { expect, test } from "vitest";
 import { withNeonTestBranch } from "./test-setup";
@@ -134,18 +152,66 @@ This library works with any database driver that supports Neon Postgres and Vite
 
 ## Configuration
 
-You configure neon-testing in two places:
+You configure Neon Testing in two places:
 
 - **Base settings** in `makeNeonTesting()`
 - **Optional overrides** in `withNeonTestBranch()`
 
-See all available options in [NeonTestingOptions](https://github.com/starmode-base/neon-testing/blob/main/index.ts#L33-L75).
+Configure these in `makeNeonTesting()` and optionally override per test file via `withNeonTestBranch()`.
+
+```ts
+export interface NeonTestingOptions {
+  /**
+   * The Neon API key, this is used to create and teardown test branches
+   *
+   * https://neon.com/docs/manage/api-keys#creating-api-keys
+   */
+  apiKey: string;
+  /**
+   * The Neon project ID to operate on
+   *
+   * https://console.neon.tech/app/projects
+   */
+  projectId: string;
+  /**
+   * The parent branch ID for the new branch. If omitted or empty, the branch
+   * will be created from the project's default branch.
+   */
+  parentBranchId?: string;
+  /**
+   * Whether to create a schema-only branch (default: false)
+   */
+  schemaOnly?: boolean;
+  /**
+   * The type of connection to create (pooler is recommended)
+   */
+  endpoint?: "pooler" | "direct";
+  /**
+   * Delete the test branch in afterAll (default: true)
+   *
+   * Disabling this will leave each test branch in the Neon project after the
+   * test suite runs
+   */
+  deleteBranch?: boolean;
+  /**
+   * Automatically close Neon WebSocket connections opened during tests before
+   * deleting the branch (default: false)
+   *
+   * Suppresses the specific Neon WebSocket "Connection terminated unexpectedly"
+   * error that may surface when deleting a branch with open WebSocket
+   * connections
+   */
+  autoCloseWebSockets?: boolean;
+}
+```
+
+See all available options in [NeonTestingOptions](index.ts#L31-L73).
 
 ### Base configuration
 
 Configure the base settings in `makeNeonTesting()`:
 
-```typescript
+```ts
 import { makeNeonTesting } from "neon-testing";
 
 export const withNeonTestBranch = makeNeonTesting({
@@ -158,32 +224,41 @@ export const withNeonTestBranch = makeNeonTesting({
 
 Override the base configuration in specific test files with `withNeonTestBranch()`:
 
-```typescript
+```ts
 import { withNeonTestBranch } from "./test-setup";
 
 withNeonTestBranch({ parentBranchId: "br-staging-123" });
 ```
 
+## Continuous integration
+
+It's easy to run Neon integration tests in CI/CD pipelines:
+
+- **GitHub Actions** — see the [example workflow](.github/workflows/test.yml)
+- **Vercel** — either
+  - add `vitest run` to the `build` script in [package.json](https://github.com/starmode-base/template-tanstack-start/blob/83c784e164b55fd8d59c5b57b907251e5eb03de1/app/package.json#L11), or
+  - add `vitest run` to the _Build Command_ in the Vercel dashboard
+
 ## Utilities
 
 ### deleteAllTestBranches()
 
 The `deleteAllTestBranches()` function is a utility that deletes all test branches from your Neon project. This is useful for cleanup when tests fail unexpectedly and leave orphaned test branches.
 
-```typescript
+```ts
 import { withNeonTestBranch } from "./test-setup";
 
 // Access the cleanup utility
 await withNeonTestBranch.deleteAllTestBranches();
 ```
 
-The function identifies test branches by looking for the `integration-test: true` annotation that neon-testing automatically adds to all test branches it creates.
+The function identifies test branches by looking for the `integration-test: true` annotation that Neon Testing automatically adds to all test branches it creates.
 
 ### lazySingleton()
 
 The `lazySingleton()` function creates a lazy singleton from a factory function. This is useful for managing database connections efficiently:
 
-```typescript
+```ts
 import { lazySingleton } from "neon-testing/utils";
 import { neon } from "@neondatabase/serverless";
 
@@ -219,12 +294,8 @@ bun run release
 
 The command will abort if there are uncommitted changes in the working tree, or if the `version` in [package.json](package.json) has not been incremented.
 
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Need help?
+## Author
 
-Hi, I’m [Mikael Lirbank](https://www.lirbank.com/). I help teams build reliable AI systems. I care about quality—AI evals, robust test suites, clean data models, and clean architecture. Sometimes I draw user interfaces.
+Hi, I'm [Mikael Lirbank](https://www.lirbank.com/). I build robust, reliable, high-quality AI systems. I care deeply about quality—AI evals, robust test suites, clean data models, and clean architecture.
 
-Want to ship faster without breaking things? Let’s talk.
+Need help building elegant systems? [I'm happy to help](https://www.lirbank.com/).

package/dist/index.d.ts

@@ -64,3 +64,4 @@ export declare function makeNeonTesting(factoryOptions: NeonTestingOptions): {
     (overrides?: NeonTestingOverrides): void;
     deleteAllTestBranches: () => Promise<void>;
 };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;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;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,kBAAkB;iBA0BlD,oBAAoB;;EAmGnC"}

package/dist/singleton.d.ts

@@ -2,3 +2,4 @@
  * Create a lazy singleton from a factory function
  */
 export declare function lazySingleton<T>(factory: () => T): () => T;
+//# sourceMappingURL=singleton.d.ts.map

package/dist/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../singleton.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,CAM1D"}

package/dist/utils.d.ts

@@ -1,2 +1,3 @@
 export { lazySingleton } from "./singleton.js";
 export { neonTesting } from "./vite-plugin.js";
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/vite-plugin.d.ts

@@ -1,2 +1,10 @@
 import type { Plugin } from "vite";
-export declare function neonTesting(): Plugin;
+export declare function neonTesting(options?: {
+    /**
+     * Enable debug logging.
+     *
+     * @default false
+     */
+    debug?: boolean;
+}): Plugin;
+//# sourceMappingURL=vite-plugin.d.ts.map

package/dist/vite-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../vite-plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,wBAAgB,WAAW,CACzB,OAAO,GAAE;IACP;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACZ,GACL,MAAM,CAyBR"}

package/dist/vite-plugin.js

@@ -1,14 +1,20 @@
 import { fileURLToPath } from "node:url";
-export function neonTesting() {
+export function neonTesting(options = {}) {
     return {
         name: "neon-testing-plugin",
-        enforce: "pre",
+        // Run as late as possible to reduce the risk of other plugins restoring
+        // DATABASE_URL after we clear it
+        enforce: "post",
         config(user) {
             const setupPath = fileURLToPath(new URL("./vitest-setup.js", import.meta.url));
-            const setup = new Set([...(user.test?.setupFiles ?? []), setupPath]);
             return {
                 test: {
-                    setupFiles: Array.from(setup),
+                    // Register the vitest-setup.js file to run after other setup files
+                    setupFiles: Array.from(new Set([...(user.test?.setupFiles ?? []), setupPath])),
+                    env: {
+                        ...user.test?.env,
+                        NEON_TESTING_DEBUG: options.debug ? "true" : "false",
+                    },
                 },
             };
         },

package/dist/vite-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,KAAK;QACd,MAAM,CAAC,IAAI;YACT,MAAM,SAAS,GAAG,aAAa,CAC7B,IAAI,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAC9C,CAAC;YAEF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;YAErE,OAAO;gBACL,IAAI,EAAE;oBACJ,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;iBAC9B;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,UAAU,WAAW,CACzB,UAOI,EAAE;IAEN,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,wEAAwE;QACxE,iCAAiC;QACjC,OAAO,EAAE,MAAM;QACf,MAAM,CAAC,IAAI;YACT,MAAM,SAAS,GAAG,aAAa,CAC7B,IAAI,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAC9C,CAAC;YAEF,OAAO;gBACL,IAAI,EAAE;oBACJ,mEAAmE;oBACnE,UAAU,EAAE,KAAK,CAAC,IAAI,CACpB,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CACvD;oBACD,GAAG,EAAE;wBACH,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG;wBACjB,kBAAkB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO;qBACrD;iBACF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/vitest-setup.d.ts

@@ -0,0 +1,3 @@
+declare const isVitest: string | undefined;
+declare const isDebug: boolean;
+//# sourceMappingURL=vitest-setup.d.ts.map

package/dist/vitest-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-setup.d.ts","sourceRoot":"","sources":["../vitest-setup.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,QAAQ,oBAAqB,CAAC;AACpC,QAAA,MAAM,OAAO,SAA4C,CAAC"}

package/dist/vitest-setup.js

@@ -1,11 +1,10 @@
+"use strict";
 const isVitest = process.env.VITEST;
-
+const isDebug = process.env.NEON_TESTING_DEBUG === "true";
 if (isVitest) {
-  if (process.env.DATABASE_URL) {
-    console.warn(
-      "[neon-testing] Clearing existing DATABASE_URL in test environment",
-    );
-  }
-
-  delete process.env.DATABASE_URL;
+    if (process.env.DATABASE_URL && isDebug) {
+        console.debug("[neon-testing] Clearing existing DATABASE_URL in test environment");
+    }
+    delete process.env.DATABASE_URL;
 }
+//# sourceMappingURL=vitest-setup.js.map

package/dist/vitest-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-setup.js","sourceRoot":"","sources":["../vitest-setup.ts"],"names":[],"mappings":";AAAA,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;AACpC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM,CAAC;AAE1D,IAAI,QAAQ,EAAE,CAAC;IACb,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,EAAE,CAAC;QACxC,OAAO,CAAC,KAAK,CACX,mEAAmE,CACpE,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon-testing",
-  "version": "2.0.1-beta.9",
+  "version": "2.1.1",
   "description": "A Vitest utility for seamless integration tests with Neon Postgres",
   "keywords": [
     "neon",
@@ -22,26 +22,20 @@
     "./utils": {
       "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js"
-    },
-    "./vite-plugin": {
-      "types": "./dist/vite-plugin.d.ts",
-      "import": "./dist/vite-plugin.js"
     }
   },
-  "types": "./dist/index.d.ts",
   "files": [
-    "dist",
-    "vitest-setup.js"
+    "dist"
   ],
   "scripts": {
+    "build": "rm -rf dist && tsc",
     "test": "vitest",
     "format": "prettier --write .",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp vitest-setup.js dist/",
-    "release:patch": "bun pm version patch && bun publish --tag latest",
-    "release:minor": "bun pm version minor && bun publish --tag latest",
-    "release:major": "bun pm version major && bun publish --tag latest",
-    "release:beta": "bun pm version prerelease --preid=beta && bun publish --tag beta",
-    "prepublishOnly": "bun run build && vitest run && prettier --check .",
+    "check": "bun run build && bunx vitest run && bunx prettier --check .",
+    "release:patch": "bun run check && bun pm version patch && bun publish --tag latest",
+    "release:minor": "bun run check && bun pm version minor && bun publish --tag latest",
+    "release:major": "bun run check && bun pm version major && bun publish --tag latest",
+    "release:beta": "bun run check && bun pm version prerelease --preid=beta && bun publish --tag beta",
     "postpublish": "git push --follow-tags"
   },
   "dependencies": {

package/vitest-setup.js

@@ -1,11 +0,0 @@
-const isVitest = process.env.VITEST;
-
-if (isVitest) {
-  if (process.env.DATABASE_URL) {
-    console.warn(
-      "[neon-testing] Clearing existing DATABASE_URL in test environment",
-    );
-  }
-
-  delete process.env.DATABASE_URL;
-}