neon-testing 3.0.0-beta.0 → 3.0.0-beta.1

package/README.md

@@ -31,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 only** - Ships TypeScript source files
+- 🛡️ **TypeScript native** - Ships compiled JavaScript with type declarations and source maps too
 - 🎯 **ESM only** - No CommonJS support
 
 ## How it works

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/core.d.ts

@@ -0,0 +1,148 @@
+/**
+ * https://neon.com/docs/reference/typescript-sdk
+ */
+import { type Branch } from "@neondatabase/api-client";
+/**
+ * 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)
+     *
+     * https://neon.com/docs/manage/api-keys#creating-api-keys
+     */
+    apiKey: string;
+    /**
+     * The Neon project ID to operate on (required)
+     *
+     * https://console.neon.tech/app/projects
+     */
+    projectId: string;
+    /**
+     * The parent branch ID for the new branch (default: undefined)
+     *
+     * If omitted or undefined, test branches 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 (default: "pooler")
+     */
+    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
+     *
+     * Vitest only — under Bun the uncaughtException suppression does not
+     * intercept, so close connections explicitly there instead.
+     */
+    autoCloseWebSockets?: boolean;
+    /**
+     * Time in seconds until the branch expires and is automatically deleted
+     * (default: 600 = 10 minutes)
+     *
+     * This provides automatic cleanup for dangling branches from interrupted or
+     * failed test runs. Set to `null` to disable automatic expiration.
+     *
+     * Must be a positive integer. Maximum 30 days (2,592,000 seconds).
+     *
+     * https://neon.com/docs/guides/branch-expiration
+     */
+    expiresIn?: number | null;
+    /**
+     * The database role to connect as (default: project owner role)
+     *
+     * The role must exist in the parent branch. Roles are automatically
+     * copied to test branches when branching.
+     */
+    roleName?: string;
+    /**
+     * The database to connect to (default: project default database)
+     */
+    databaseName?: string;
+    /**
+     * Override the `sslmode` query param on the connection URI (default:
+     * undefined — URI is passed through unchanged)
+     *
+     * Neon's API returns URIs with `sslmode=require`. In pg v9 the meaning of
+     * `require` changes to libpq semantics (encrypt, but don't verify the CA).
+     *
+     * - `"verify-full"` — strict CA verification (silences the pg v9 warning)
+     * - `"require"` — preserves today's effective behavior under pg v9 by also
+     *   setting `uselibpqcompat=true`
+     *
+     * Only affects drivers that parse `sslmode` (e.g. `pg`). The Neon
+     * serverless driver ignores it.
+     */
+    sslMode?: "verify-full" | "require";
+}
+/** 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">>;
+/**
+ * Low-level factory that creates a Neon test-branch setup/teardown function.
+ * Runner-agnostic — you inject the lifecycle hooks via `options.hooks`.
+ *
+ * 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 - see {@link MakeNeonTestingCoreOptions}
+ * @returns A setup/teardown function with attached utilities:
+ *  - `deleteAllTestBranches()` - delete all test branches
+ *  - `api` - the Neon API client
+ *
+ * @example
+ * ```ts
+ * import { beforeAll, afterAll } from "vitest"; // or any runner
+ * import { makeNeonTestingCore } from "neon-testing/core";
+ *
+ * export const neonTesting = makeNeonTestingCore({
+ *   apiKey: process.env.NEON_API_KEY!,
+ *   projectId: process.env.NEON_PROJECT_ID!,
+ *   hooks: { beforeAll, afterAll },
+ * });
+ * ```
+ */
+export declare function makeNeonTestingCore(factoryOptions: MakeNeonTestingCoreOptions): {
+    (overrides?: NeonTestingOptions): () => Branch | undefined;
+    deleteAllTestBranches: () => Promise<void>;
+    api: import("@neondatabase/api-client").Api<unknown>;
+};
+//# 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/core.js

@@ -0,0 +1,204 @@
+/**
+ * https://neon.com/docs/reference/typescript-sdk
+ */
+import { createApiClient, EndpointType, } from "@neondatabase/api-client";
+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";
+/**
+ * Low-level factory that creates a Neon test-branch setup/teardown function.
+ * Runner-agnostic — you inject the lifecycle hooks via `options.hooks`.
+ *
+ * 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 - see {@link MakeNeonTestingCoreOptions}
+ * @returns A setup/teardown function with attached utilities:
+ *  - `deleteAllTestBranches()` - delete all test branches
+ *  - `api` - the Neon API client
+ *
+ * @example
+ * ```ts
+ * import { beforeAll, afterAll } from "vitest"; // or any runner
+ * import { makeNeonTestingCore } from "neon-testing/core";
+ *
+ * export const neonTesting = makeNeonTestingCore({
+ *   apiKey: process.env.NEON_API_KEY!,
+ *   projectId: process.env.NEON_PROJECT_ID!,
+ *   hooks: { beforeAll, afterAll },
+ * });
+ * ```
+ */
+export function makeNeonTestingCore(factoryOptions) {
+    // Validate factory options
+    validateExpiresIn(factoryOptions.expiresIn);
+    const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });
+    /**
+     * Delete all test branches (branches with the "integration-test: true" annotation)
+     */
+    async function deleteAllTestBranches() {
+        const { data } = await apiClient.listProjectBranches({
+            projectId: factoryOptions.projectId,
+        });
+        for (const branch of data.branches) {
+            const isTestBranch = data.annotations[branch.id]?.value["integration-test"] === "true";
+            if (isTestBranch) {
+                await apiClient.deleteProjectBranch(factoryOptions.projectId, branch.id);
+            }
+        }
+    }
+    /**
+     * Setup/teardown function for a test file.
+     *
+     * 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 per-file overrides for the factory options
+     * @returns A function that provides access to the current Neon branch object
+     */
+    const neonTesting = (
+    /** Override any factory options except apiKey */
+    overrides) => {
+        // Validate overrides
+        if (overrides?.expiresIn !== undefined) {
+            validateExpiresIn(overrides.expiresIn);
+        }
+        // Merge factory options with overrides
+        const options = { ...factoryOptions, ...overrides };
+        // Each test file gets its own branch and database client
+        let branch;
+        // List of tracked Neon WebSocket connections
+        // Lazily initialized when autoCloseWebSockets is enabled (avoids
+        // referencing the WebSocket global on runtimes that lack it, e.g. Node 20)
+        let neonSockets;
+        /**
+         * Create a new test branch
+         *
+         * @returns The connection URI for the new branch
+         */
+        async function createBranch() {
+            // Calculate expiration timestamp if expiresIn is set
+            const expiresIn = options.expiresIn === undefined ? 600 : options.expiresIn; // Default: 10 minutes
+            const expiresAt = expiresIn !== null
+                ? new Date(Date.now() + expiresIn * 1000).toISOString()
+                : undefined;
+            const { data } = await apiClient.createProjectBranch(options.projectId, {
+                branch: {
+                    name: `test/${crypto.randomUUID()}`,
+                    ...(options.parentBranchId
+                        ? { parent_id: options.parentBranchId }
+                        : {}),
+                    ...(options.schemaOnly ? { init_source: "schema-only" } : {}),
+                    ...(expiresAt ? { expires_at: expiresAt } : {}),
+                },
+                endpoints: [{ type: EndpointType.ReadWrite }],
+                annotation_value: {
+                    "integration-test": "true",
+                },
+            });
+            branch = data.branch;
+            // Determine role and database (handles multi-role/database projects)
+            const targetRole = options.roleName ??
+                data.roles?.find((r) => r.name === "neondb_owner")?.name ??
+                data.roles?.[0]?.name;
+            const targetDatabase = options.databaseName ??
+                data.databases?.find((d) => d.name === "neondb")?.name ??
+                data.databases?.[0]?.name;
+            if (!targetRole) {
+                throw new Error("No role available in branch");
+            }
+            if (!targetDatabase) {
+                throw new Error("No database available in branch");
+            }
+            // Validate specified role exists
+            if (options.roleName &&
+                !data.roles?.some((r) => r.name === options.roleName)) {
+                throw new Error(`Role not found: ${options.roleName}`);
+            }
+            // Validate specified database exists
+            if (options.databaseName &&
+                !data.databases?.some((d) => d.name === options.databaseName)) {
+                throw new Error(`Database not found: ${options.databaseName}`);
+            }
+            // Use getConnectionUri API (works for all cases, including multi-role projects)
+            const { data: uriData } = await apiClient.getConnectionUri({
+                projectId: options.projectId,
+                branch_id: branch.id,
+                role_name: targetRole,
+                database_name: targetDatabase,
+                pooled: options.endpoint !== "direct",
+            });
+            return applySslMode(uriData.uri, options.sslMode);
+        }
+        /**
+         * Delete the test branch
+         */
+        async function deleteBranch() {
+            if (!branch?.id) {
+                throw new Error("No branch to delete");
+            }
+            await apiClient.deleteProjectBranch(options.projectId, branch.id);
+            branch = undefined;
+        }
+        factoryOptions.hooks.beforeAll(async () => {
+            process.env.DATABASE_URL = await withRetry(createBranch, {
+                maxRetries: 8,
+                baseDelayMs: 1000,
+            });
+            if (options.autoCloseWebSockets) {
+                neonSockets = new Set();
+                // Custom WebSocket constructor that tracks Neon WebSocket connections
+                class TrackingWebSocket extends WebSocket {
+                    constructor(url) {
+                        super(url);
+                        // Only track Neon WebSocket connections
+                        if (!url.includes(".neon.tech/"))
+                            return;
+                        neonSockets.add(this);
+                    }
+                }
+                // Install a custom WebSocket constructor that tracks Neon WebSocket
+                // connections and closes them before deleting the branch
+                try {
+                    const { neonConfig } = await import("@neondatabase/serverless");
+                    neonConfig.webSocketConstructor = TrackingWebSocket;
+                }
+                catch {
+                    throw new Error("autoCloseWebSockets requires @neondatabase/serverless to be installed. Run: npm install @neondatabase/serverless");
+                }
+            }
+        });
+        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
+                process.prependListener("uncaughtException", neonWsErrorHandler);
+                // Close tracked Neon WebSocket connections before deleting the branch
+                neonSockets.forEach((ws) => ws.close());
+            }
+            if (options.deleteBranch !== false) {
+                await deleteBranch();
+            }
+        });
+        /**
+         * Return the Neon branch object
+         *
+         * @returns The Neon branch object
+         */
+        return () => branch;
+    };
+    // Attach utilities
+    neonTesting.deleteAllTestBranches = deleteAllTestBranches;
+    neonTesting.api = apiClient;
+    return neonTesting;
+}
+//# 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

@@ -0,0 +1,6 @@
+/**
+ * Creates a synchronization barrier that blocks until `count` callers have
+ * arrived, then releases all of them simultaneously
+ */
+export declare function createBarrier(count: number): () => Promise<void>;
+//# sourceMappingURL=barrier.d.ts.map

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

@@ -0,0 +1,19 @@
+/**
+ * Creates a synchronization barrier that blocks until `count` callers have
+ * arrived, then releases all of them simultaneously
+ */
+export function createBarrier(count) {
+    let arrived = 0;
+    let release;
+    const barrier = new Promise((resolve) => {
+        release = resolve;
+    });
+    return async () => {
+        arrived++;
+        if (arrived === count) {
+            release();
+        }
+        await barrier;
+    };
+}
+//# sourceMappingURL=barrier.js.map

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"}

package/dist/lib/expires-in.js

@@ -0,0 +1,21 @@
+/**
+ * Validates the expiresIn option
+ */
+export function validateExpiresIn(expiresIn) {
+    if (expiresIn === null) {
+        return;
+    }
+    if (expiresIn === undefined) {
+        return;
+    }
+    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)");
+    }
+}
+//# sourceMappingURL=expires-in.js.map

package/dist/lib/expires-in.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expires-in.js","sourceRoot":"","sources":["../../src/lib/expires-in.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAoC;IACpE,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,SAAS,GAAG,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC"}

package/dist/lib/singleton.d.ts

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

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

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

package/dist/lib/singleton.js

@@ -0,0 +1,11 @@
+/**
+ * Create a lazy singleton from a factory function
+ */
+export function lazySingleton(factory) {
+    let instance;
+    return () => {
+        instance ??= factory();
+        return instance;
+    };
+}
+//# sourceMappingURL=singleton.js.map

package/dist/lib/singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../src/lib/singleton.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,aAAa,CAAI,OAAgB;IAC/C,IAAI,QAAuB,CAAC;IAC5B,OAAO,GAAG,EAAE;QACV,QAAQ,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/ssl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rewrite the `sslmode` (and related) query params on a Neon connection URI.
+ *
+ * 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`.
+ */
+export declare function applySslMode(uri: string, mode: "verify-full" | "require" | undefined): string;
+//# sourceMappingURL=ssl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ssl.d.ts","sourceRoot":"","sources":["../../src/lib/ssl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,GAC1C,MAAM,CAaR"}

package/dist/lib/ssl.js

@@ -0,0 +1,21 @@
+/**
+ * Rewrite the `sslmode` (and related) query params on a Neon connection URI.
+ *
+ * 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`.
+ */
+export 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();
+}
+//# sourceMappingURL=ssl.js.map

package/dist/lib/ssl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssl.js","sourceRoot":"","sources":["../../src/lib/ssl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,IAA2C;IAE3C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAEnC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAEtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC"}

package/dist/lib/with-retry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options: {
+    maxRetries: number;
+    baseDelayMs: number;
+}): Promise<T>;
+//# sourceMappingURL=with-retry.d.ts.map

package/dist/lib/with-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-retry.d.ts","sourceRoot":"","sources":["../../src/lib/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,GACA,OAAO,CAAC,CAAC,CAAC,CAyCZ"}

package/dist/lib/with-retry.js

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+export 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=with-retry.js.map

package/dist/lib/with-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-retry.js","sourceRoot":"","sources":["../../src/lib/with-retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,OAGC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC;YAEvC,0DAA0D;YAC1D,IAAI,MAAM,KAAK,GAAG,IAAI,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;gBACnD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;gBAE7D,OAAO,CAAC,GAAG,CACT,yCAAyC,KAAK,eAAe,OAAO,IAAI,OAAO,CAAC,UAAU,GAAG,CAC9F,CAAC;gBACF,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;gBAE3D,SAAS;YACX,CAAC;YAED,8EAA8E;YAC9E,IAAI,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;gBAChC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAC9C,MAAM,IAAI,KAAK,CACb,yBAAyB,MAAM,MAAM,IAAI,MAAM,OAAO,EAAE,EACxD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;YACJ,CAAC;YAED,8DAA8D;YAC9D,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/lib/ws-error.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
+ * error
+ */
+export declare const neonWsErrorHandler: (error: Error) => void;
+//# sourceMappingURL=ws-error.d.ts.map

package/dist/lib/ws-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-error.d.ts","sourceRoot":"","sources":["../../src/lib/ws-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,KAAK,SAY9C,CAAC"}

package/dist/lib/ws-error.js

@@ -0,0 +1,15 @@
+/**
+ * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
+ * error
+ */
+export 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;
+};
+//# sourceMappingURL=ws-error.js.map

package/dist/lib/ws-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-error.js","sourceRoot":"","sources":["../../src/lib/ws-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAY,EAAE,EAAE;IACjD,MAAM,aAAa,GACjB,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC5D,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,0BAA0B,CAAC,CAAC;IAEpD,IAAI,aAAa,EAAE,CAAC;QAClB,kDAAkD;QAClD,OAAO;IACT,CAAC;IAED,0CAA0C;IAC1C,MAAM,KAAK,CAAC;AACd,CAAC,CAAC"}

package/dist/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":""}

package/dist/setup.js

@@ -0,0 +1,9 @@
+import { CLEARED_DATABASE_URL } from "./lib/cleared-database-url.js";
+// Overwrites any existing DATABASE_URL so a test file that forgot to call
+// `neonTesting()` can't reach the pre-configured database. Loaded as a
+// test-runner preload (Vitest `setupFiles` / Bun `bunfig` `preload`).
+if (process.env.DATABASE_URL && process.env.NEON_TESTING_DEBUG === "true") {
+    console.debug("[neon-testing] Overwriting existing DATABASE_URL");
+}
+process.env.DATABASE_URL = CLEARED_DATABASE_URL;
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAErE,0EAA0E;AAC1E,uEAAuE;AACvE,sEAAsE;AACtE,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM,EAAE,CAAC;IAC1E,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;AACpE,CAAC;AAED,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,oBAAoB,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export { lazySingleton } from "./lib/singleton.js";
+export { createBarrier } from "./lib/barrier.js";
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

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

package/dist/utils.js

@@ -0,0 +1,3 @@
+export { lazySingleton } from "./lib/singleton.js";
+export { createBarrier } from "./lib/barrier.js";
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/vitest.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 Vitest'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=vitest.d.ts.map

package/dist/vitest.d.ts.map

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

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

package/dist/vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../src/vitest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC7C,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon-testing",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.1",
   "description": "A testing utility for seamless integration tests with Neon Postgres, for Vitest and Bun Test.",
   "keywords": [
     "neon",
@@ -17,13 +17,29 @@
   "bugs": "https://github.com/starmode-base/neon-testing/issues",
   "type": "module",
   "exports": {
-    "./core": "./src/core.ts",
-    "./vitest": "./src/vitest.ts",
-    "./bun": "./src/bun.ts",
-    "./utils": "./src/utils.ts",
-    "./setup": "./src/setup.ts"
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "import": "./dist/vitest.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.js"
+    }
   },
   "files": [
+    "dist",
     "src",
     "!src/**/*.test.ts"
   ],
@@ -31,8 +47,10 @@
     "node": ">=22"
   },
   "scripts": {
-    "dev": "tsc --watch",
-    "check": "prettier --check . && tsc && bun run check:drift && bun run test",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "check": "prettier --check . && bun run build && tsc && bun run check:drift && bun run test",
     "check:drift": "diff -r -x neon-testing.ts tests-bun tests-vitest",
     "format": "prettier --write .",
     "test": "vitest run && bun test",
@@ -45,8 +63,8 @@
     "test:bun": "bun test",
     "test:bun:watch": "bun test --watch",
     "skills:update": "bunx skills add neondatabase/agent-skills",
-    "clean:soft": "rm -rf node_modules && bun install",
-    "clean:hard": "rm -rf node_modules bun.lock && bun install",
+    "clean:soft": "rm -rf node_modules dist && bun install",
+    "clean:hard": "rm -rf node_modules dist bun.lock && bun install",
     "release:patch": "bun pm version patch --message 'release: v%s'",
     "release:minor": "bun pm version minor --message 'release: v%s'",
     "release:major": "bun pm version major --message 'release: v%s'",
@@ -61,9 +79,13 @@
     "@neondatabase/api-client": "2.7.1"
   },
   "peerDependencies": {
+    "@neondatabase/serverless": "^1",
     "vitest": "^3 || ^4"
   },
   "peerDependenciesMeta": {
+    "@neondatabase/serverless": {
+      "optional": true
+    },
     "vitest": {
       "optional": true
     }

package/src/bun.ts

@@ -1,9 +1,9 @@
 /// <reference types="bun" />
 import { beforeAll, afterAll } from "bun:test";
-import { makeNeonTestingCore } from "./core";
-import type { MakeNeonTestingOptions } from "./core";
+import { makeNeonTestingCore } from "./core.js";
+import type { MakeNeonTestingOptions } from "./core.js";
 
-export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core";
+export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core.js";
 
 /**
  * Create a Neon test-branch factory wired to Bun's lifecycle hooks.

package/src/core.ts

@@ -6,10 +6,11 @@ import {
   EndpointType,
   type Branch,
 } from "@neondatabase/api-client";
-import { applySslMode } from "./lib/ssl";
-import { validateExpiresIn } from "./lib/expires-in";
-import { neonWsErrorHandler } from "./lib/ws-error";
-import { withRetry } from "./lib/with-retry";
+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";
 
 /**
  * Test-runner lifecycle hooks
@@ -340,7 +341,9 @@ export function makeNeonTestingCore(
     });
 
     factoryOptions.hooks.afterAll(async () => {
-      delete process.env.DATABASE_URL;
+      // 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) {

package/src/lib/cleared-database-url.ts

@@ -0,0 +1,9 @@
+/**
+ * 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()`;

package/src/setup.ts

@@ -1,8 +1,10 @@
-// Removes any existing DATABASE_URL so a test file that forgot to call
+import { CLEARED_DATABASE_URL } from "./lib/cleared-database-url.js";
+
+// Overwrites any existing DATABASE_URL so a test file that forgot to call
 // `neonTesting()` can't reach the pre-configured database. Loaded as a
 // test-runner preload (Vitest `setupFiles` / Bun `bunfig` `preload`).
 if (process.env.DATABASE_URL && process.env.NEON_TESTING_DEBUG === "true") {
-  console.debug("[neon-testing] Clearing existing DATABASE_URL");
+  console.debug("[neon-testing] Overwriting existing DATABASE_URL");
 }
 
-delete process.env.DATABASE_URL;
+process.env.DATABASE_URL = CLEARED_DATABASE_URL;

package/src/utils.ts

@@ -1,2 +1,2 @@
-export { lazySingleton } from "./lib/singleton";
-export { createBarrier } from "./lib/barrier";
+export { lazySingleton } from "./lib/singleton.js";
+export { createBarrier } from "./lib/barrier.js";

package/src/vitest.ts

@@ -1,8 +1,8 @@
 import { beforeAll, afterAll } from "vitest";
-import { makeNeonTestingCore } from "./core";
-import type { MakeNeonTestingOptions } from "./core";
+import { makeNeonTestingCore } from "./core.js";
+import type { MakeNeonTestingOptions } from "./core.js";
 
-export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core";
+export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core.js";
 
 /**
  * Create a Neon test-branch factory wired to Vitest's lifecycle hooks.