neon-testing 2.1.0 → 2.1.2-beta.0

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.
 
@@ -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";
@@ -77,8 +79,8 @@ test("database operations", async () => {
 
 First, add the Vite plugin to clear any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
 
-```typescript
-// vitest.config.ts or vite.config.ts
+```ts
+// vitest.config.ts
 import { defineConfig } from "vitest/config";
 import { neonTesting } from "neon-testing/utils";
 
@@ -87,13 +89,13 @@ export default defineConfig({
 });
 ```
 
-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.
+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";
 
@@ -108,7 +110,7 @@ export const withNeonTestBranch = makeNeonTesting({
 
 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";
@@ -150,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({
@@ -174,26 +224,20 @@ 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" });
 ```
 
-## CI/CD
-
-It is easy to run Neon integration in CI/CD
-
-### GitHub Actions
+## Continuous integration
 
-[Example](.github/workflows/test.yml)
+It's easy to run Neon integration tests in CI/CD pipelines:
 
-### Vercel
-
-Two options:
-
-- Add `vitest run` to the `build` script in [package.json](https://github.com/starmode-base/template-tanstack-start/blob/83c784e164b55fd8d59c5b57b907251e5eb03de1/app/package.json#L11l)
-- Add `vitest run` to the _Build Command_ in the Vercel dashboard
+- **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
 
@@ -201,20 +245,20 @@ Two options:
 
 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";
 
@@ -250,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/browser-empty.d.ts

@@ -0,0 +1,2 @@
+export declare function neonTesting(): void;
+//# sourceMappingURL=browser-empty.d.ts.map

package/dist/browser-empty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-empty.d.ts","sourceRoot":"","sources":["../browser-empty.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,SAE1B"}

package/dist/browser-empty.js

@@ -0,0 +1,4 @@
+export function neonTesting() {
+    throw new Error("neon-testing/vite is Node-only (Vite/Vitest context).");
+}
+//# sourceMappingURL=browser-empty.js.map

package/dist/browser-empty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-empty.js","sourceRoot":"","sources":["../browser-empty.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;AAC3E,CAAC"}

package/dist/index.js

@@ -104,7 +104,7 @@ export function makeNeonTesting(factoryOptions) {
         }
         beforeAll(async () => {
             process.env.DATABASE_URL = await withRetry(createBranch, {
-                maxRetries: 5,
+                maxRetries: 8,
                 baseDelayMs: 1000,
             });
             if (options.autoCloseWebSockets) {

package/dist/utils.d.ts

@@ -1,3 +1,7 @@
+import { neonTesting as neonTestingVite } from "./vite-plugin.js";
 export { lazySingleton } from "./singleton.js";
-export { neonTesting } from "./vite-plugin.js";
+/**
+ * @deprecated Import the Vite plugin from "neon-testing/vite" instead.
+ */
+export declare const neonTesting: typeof neonTestingVite;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,WAAW,wBAAkB,CAAC"}

package/dist/utils.js

@@ -1,3 +1,7 @@
+import { neonTesting as neonTestingVite } from "./vite-plugin.js";
 export { lazySingleton } from "./singleton.js";
-export { neonTesting } from "./vite-plugin.js";
+/**
+ * @deprecated Import the Vite plugin from "neon-testing/vite" instead.
+ */
+export const neonTesting = neonTestingVite;
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC"}

package/dist/vite-plugin.d.ts

@@ -1,4 +1,7 @@
 import type { Plugin } from "vite";
+/**
+ * Neon Testing Vite plugin
+ */
 export declare function neonTesting(options?: {
     /**
      * Enable debug logging.

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

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

package/dist/vite-plugin.js

@@ -1,4 +1,7 @@
 import { fileURLToPath } from "node:url";
+/**
+ * Neon Testing Vite plugin
+ */
 export function neonTesting(options = {}) {
     return {
         name: "neon-testing-plugin",

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,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"}
+{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC;;GAEG;AACH,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon-testing",
-  "version": "2.1.0",
+  "version": "2.1.2-beta.0",
   "description": "A Vitest utility for seamless integration tests with Neon Postgres",
   "keywords": [
     "neon",
@@ -22,12 +22,17 @@
     "./utils": {
       "types": "./dist/utils.d.ts",
       "import": "./dist/utils.js"
+    },
+    "./vite": {
+      "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
+    "dev": "tsc --watch",
     "build": "rm -rf dist && tsc",
     "test": "vitest",
     "format": "prettier --write .",
@@ -46,7 +51,7 @@
   },
   "devDependencies": {
     "@neondatabase/serverless": "^1.0.1",
-    "dotenv": "^17.2.1",
+    "dotenv": "^17.2.2",
     "drizzle-orm": "^0.44.5",
     "pg": "^8.16.3",
     "postgres": "^3.4.7",
@@ -54,5 +59,8 @@
     "typescript": "^5.9.2",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4"
+  },
+  "browser": {
+    "./dist/vite-plugin.js": "./dist/browser-empty.js"
   }
 }