neon-testing 2.7.0 → 3.0.0-beta.1

package/src/core.ts

@@ -0,0 +1,375 @@
+/**
+ * https://neon.com/docs/reference/typescript-sdk
+ */
+import {
+  createApiClient,
+  EndpointType,
+  type Branch,
+} 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";
+
+/**
+ * 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 function makeNeonTestingCore(
+  factoryOptions: MakeNeonTestingCoreOptions,
+) {
+  // 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?: NeonTestingOptions,
+  ) => {
+    // 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: Branch | undefined;
+
+    // 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: Set<WebSocket> | undefined;
+
+    /**
+     * 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<WebSocket>();
+
+        // Custom WebSocket constructor that tracks Neon WebSocket connections
+        class TrackingWebSocket extends WebSocket {
+          constructor(url: string) {
+            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;
+}

package/src/lib/barrier.ts

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

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/lib/expires-in.ts

@@ -0,0 +1,24 @@
+/**
+ * Validates the expiresIn option
+ */
+export function validateExpiresIn(expiresIn: number | null | undefined) {
+  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)");
+  }
+}

package/src/lib/singleton.ts

@@ -0,0 +1,10 @@
+/**
+ * Create a lazy singleton from a factory function
+ */
+export function lazySingleton<T>(factory: () => T): () => T {
+  let instance: T | undefined;
+  return () => {
+    instance ??= factory();
+    return instance;
+  };
+}

package/src/lib/ssl.ts

@@ -0,0 +1,24 @@
+/**
+ * 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: string,
+  mode: "verify-full" | "require" | undefined,
+): string {
+  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();
+}

package/src/lib/with-retry.ts

@@ -0,0 +1,55 @@
+/**
+ * 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<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxRetries: number;
+    baseDelayMs: number;
+  },
+): Promise<T> {
+  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: any) {
+      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");
+}

package/src/lib/ws-error.ts

@@ -0,0 +1,17 @@
+/**
+ * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
+ * error
+ */
+export const neonWsErrorHandler = (error: 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;
+};

package/src/setup.ts

@@ -0,0 +1,10 @@
+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;

package/src/utils.ts

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

package/src/vitest.ts

@@ -0,0 +1,12 @@
+import { beforeAll, afterAll } from "vitest";
+import { makeNeonTestingCore } from "./core.js";
+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 function makeNeonTesting(options: MakeNeonTestingOptions) {
+  return makeNeonTestingCore({ ...options, hooks: { beforeAll, afterAll } });
+}

package/dist/barrier.d.ts.map

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

package/dist/barrier.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"barrier.js","sourceRoot":"","sources":["../src/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","sourcesContent":["/**\n * Creates a synchronization barrier that blocks until `count` callers have\n * arrived, then releases all of them simultaneously\n */\nexport function createBarrier(count: number) {\n  let arrived = 0;\n  let release: () => void;\n\n  const barrier = new Promise<void>((resolve) => {\n    release = resolve;\n  });\n\n  return async () => {\n    arrived++;\n\n    if (arrived === count) {\n      release();\n    }\n\n    await barrier;\n  };\n}\n"]}

package/dist/browser-empty.d.ts

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

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

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

package/dist/browser-empty.js

@@ -1,4 +0,0 @@
-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

@@ -1 +0,0 @@
-{"version":3,"file":"browser-empty.js","sourceRoot":"","sources":["../src/browser-empty.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["export function neonTesting() {\n  throw new Error(\"neon-testing/vite is Node-only (Vite/Vitest context).\");\n}\n"]}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,0BAA0B,CAAC;AA6ClC,MAAM,WAAW,kBAAkB;IACjC;;;;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;;;;;;;OAOG;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,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,kBAAkB;iBAyClD,oBAAoB;;;EAyKnC"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * https://neon.com/docs/reference/typescript-sdk\n */\nimport {\n  createApiClient,\n  EndpointType,\n  type Branch,\n} from \"@neondatabase/api-client\";\nimport { afterAll, beforeAll } from \"vitest\";\n\n/**\n * Rewrite the `sslmode` (and related) query params on a Neon connection URI.\n *\n * Neon's API returns URIs with `sslmode=require`. In pg v9 /\n * pg-connection-string v3 this mode will adopt libpq semantics (encrypt\n * without CA verification) instead of today's effective `verify-full`.\n */\nfunction applySslMode(\n  uri: string,\n  mode: \"verify-full\" | \"require\" | undefined,\n): string {\n  if (mode === undefined) return uri;\n\n  const url = new URL(uri);\n  url.searchParams.set(\"sslmode\", mode);\n  if (mode === \"require\") {\n    url.searchParams.set(\"uselibpqcompat\", \"true\");\n  } else {\n    url.searchParams.delete(\"uselibpqcompat\");\n  }\n  return url.toString();\n}\n\n/**\n * Validates the expiresIn option\n */\nfunction validateExpiresIn(expiresIn: number | null | undefined) {\n  if (expiresIn !== null && expiresIn !== undefined) {\n    if (!Number.isInteger(expiresIn)) {\n      throw new Error(\"expiresIn must be an integer\");\n    }\n\n    if (expiresIn <= 0) {\n      throw new Error(\"expiresIn must be a positive integer\");\n    }\n\n    if (expiresIn > 2592000) {\n      throw new Error(\"expiresIn must not exceed 30 days (2,592,000 seconds)\");\n    }\n  }\n}\n\nexport interface NeonTestingOptions {\n  /**\n   * The Neon API key, this is used to create and teardown test branches (required)\n   *\n   * https://neon.com/docs/manage/api-keys#creating-api-keys\n   */\n  apiKey: string;\n  /**\n   * The Neon project ID to operate on (required)\n   *\n   * https://console.neon.tech/app/projects\n   */\n  projectId: string;\n  /**\n   * The parent branch ID for the new branch (default: undefined)\n   *\n   * If omitted or undefined, test branches will be created from the project's\n   * default branch.\n   */\n  parentBranchId?: string;\n  /**\n   * Whether to create a schema-only branch (default: false)\n   */\n  schemaOnly?: boolean;\n  /**\n   * The type of connection to create (default: \"pooler\")\n   */\n  endpoint?: \"pooler\" | \"direct\";\n  /**\n   * Delete the test branch in afterAll (default: true)\n   *\n   * Disabling this will leave each test branch in the Neon project after the\n   * test suite runs\n   */\n  deleteBranch?: boolean;\n  /**\n   * Automatically close Neon WebSocket connections opened during tests before\n   * deleting the branch (default: false)\n   *\n   * Suppresses the specific Neon WebSocket \"Connection terminated unexpectedly\"\n   * error that may surface when deleting a branch with open WebSocket\n   * connections\n   */\n  autoCloseWebSockets?: boolean;\n  /**\n   * Time in seconds until the branch expires and is automatically deleted\n   * (default: 600 = 10 minutes)\n   *\n   * This provides automatic cleanup for dangling branches from interrupted or\n   * failed test runs. Set to `null` to disable automatic expiration.\n   *\n   * Must be a positive integer. Maximum 30 days (2,592,000 seconds).\n   *\n   * https://neon.com/docs/guides/branch-expiration\n   */\n  expiresIn?: number | null;\n  /**\n   * The database role to connect as (default: project owner role)\n   *\n   * The role must exist in the parent branch. Roles are automatically\n   * copied to test branches when branching.\n   */\n  roleName?: string;\n  /**\n   * The database to connect to (default: project default database)\n   */\n  databaseName?: string;\n  /**\n   * Override the `sslmode` query param on the connection URI (default:\n   * undefined — URI is passed through unchanged)\n   *\n   * Neon's API returns URIs with `sslmode=require`. In pg v9 the meaning of\n   * `require` changes to libpq semantics (encrypt, but don't verify the CA).\n   *\n   * - `\"verify-full\"` — strict CA verification (silences the pg v9 warning)\n   * - `\"require\"` — preserves today's effective behavior under pg v9 by also\n   *   setting `uselibpqcompat=true`\n   *\n   * Only affects drivers that parse `sslmode` (e.g. `pg`). The Neon\n   * serverless driver ignores it.\n   */\n  sslMode?: \"verify-full\" | \"require\";\n}\n\n/** Options for overriding test database setup (excludes apiKey) */\nexport type NeonTestingOverrides = Omit<Partial<NeonTestingOptions>, \"apiKey\">;\n\n/**\n * Factory function that creates a Neon test database setup/teardown function\n * for Vitest test suites.\n *\n * @param factoryOptions - Configuration options (see {@link NeonTestingOptions})\n * @returns A setup/teardown function with attached utilities:\n *  - `deleteAllTestBranches()` - Cleanup method to delete all test branches\n *  - `api` - Direct access to the Neon API client\n *\n * @example\n * ```ts\n * // neon-testing.ts\n * import { makeNeonTesting } from \"neon-testing\";\n *\n * export const neonTesting = makeNeonTesting({\n *   apiKey: \"apiKey\",\n *   projectId: \"projectId\",\n * });\n * ```\n *\n * @example\n * ```ts\n * // my-test.test.ts\n * import { neonTesting } from \"./neon-testing\";\n *\n * const getBranch = neonTesting();\n *\n * test(\"my test\", () => {\n *   const branch = getBranch();\n *   console.log(branch.id);\n * });\n * ```\n */\nexport function makeNeonTesting(factoryOptions: NeonTestingOptions) {\n  // Validate factory options\n  validateExpiresIn(factoryOptions.expiresIn);\n\n  const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });\n\n  /**\n   * Delete all test branches (branches with the \"integration-test: true\" annotation)\n   */\n  async function deleteAllTestBranches() {\n    const { data } = await apiClient.listProjectBranches({\n      projectId: factoryOptions.projectId,\n    });\n\n    for (const branch of data.branches) {\n      const isTestBranch =\n        data.annotations[branch.id]?.value[\"integration-test\"] === \"true\";\n\n      if (isTestBranch) {\n        await apiClient.deleteProjectBranch(\n          factoryOptions.projectId,\n          branch.id,\n        );\n      }\n    }\n  }\n\n  /**\n   * Setup/teardown function for Vitest test suites\n   *\n   * Registers Vitest lifecycle hooks that:\n   * - Create an isolated test branch from your parent branch\n   * - Set `DATABASE_URL` environment variable to the test branch connection URI\n   * - Automatically delete the test branch after tests complete (unless `deleteBranch: false`)\n   * - Automatically expire branches after 10 minutes for cleanup (unless `expiresIn: null`)\n   *\n   * @param overrides - Optional overrides for the factory options\n   * @returns A function that provides access to the current Neon branch object\n   */\n  const neonTesting = (\n    /** Override any factory options except apiKey */\n    overrides?: NeonTestingOverrides,\n  ) => {\n    // Validate overrides\n    if (overrides?.expiresIn !== undefined) {\n      validateExpiresIn(overrides.expiresIn);\n    }\n\n    // Merge factory options with overrides\n    const options = { ...factoryOptions, ...overrides };\n\n    // Each test file gets its own branch and database client\n    let branch: Branch | undefined;\n\n    // List of tracked Neon WebSocket connections\n    // Lazily initialized when autoCloseWebSockets is enabled (avoids\n    // referencing the WebSocket global on runtimes that lack it, e.g. Node 20)\n    let neonSockets: Set<WebSocket> | undefined;\n\n    /**\n     * Create a new test branch\n     *\n     * @returns The connection URI for the new branch\n     */\n    async function createBranch() {\n      // Calculate expiration timestamp if expiresIn is set\n      const expiresIn =\n        options.expiresIn === undefined ? 600 : options.expiresIn; // Default: 10 minutes\n\n      const expiresAt =\n        expiresIn !== null\n          ? new Date(Date.now() + expiresIn * 1000).toISOString()\n          : undefined;\n\n      const { data } = await apiClient.createProjectBranch(options.projectId, {\n        branch: {\n          name: `test/${crypto.randomUUID()}`,\n          parent_id: options.parentBranchId,\n          init_source: options.schemaOnly ? \"schema-only\" : undefined,\n          expires_at: expiresAt,\n        },\n        endpoints: [{ type: EndpointType.ReadWrite }],\n        annotation_value: {\n          \"integration-test\": \"true\",\n        },\n      });\n\n      branch = data.branch;\n\n      // Determine role and database (handles multi-role/database projects)\n      const targetRole =\n        options.roleName ??\n        data.roles?.find((r) => r.name === \"neondb_owner\")?.name ??\n        data.roles?.[0]?.name;\n      const targetDatabase =\n        options.databaseName ??\n        data.databases?.find((d) => d.name === \"neondb\")?.name ??\n        data.databases?.[0]?.name;\n\n      if (!targetRole) {\n        throw new Error(\"No role available in branch\");\n      }\n      if (!targetDatabase) {\n        throw new Error(\"No database available in branch\");\n      }\n\n      // Validate specified role exists\n      if (\n        options.roleName &&\n        !data.roles?.some((r) => r.name === options.roleName)\n      ) {\n        throw new Error(`Role not found: ${options.roleName}`);\n      }\n\n      // Validate specified database exists\n      if (\n        options.databaseName &&\n        !data.databases?.some((d) => d.name === options.databaseName)\n      ) {\n        throw new Error(`Database not found: ${options.databaseName}`);\n      }\n\n      // Use getConnectionUri API (works for all cases, including multi-role projects)\n      const { data: uriData } = await apiClient.getConnectionUri({\n        projectId: options.projectId,\n        branch_id: branch.id,\n        role_name: targetRole,\n        database_name: targetDatabase,\n        pooled: options.endpoint !== \"direct\",\n      });\n\n      return applySslMode(uriData.uri, options.sslMode);\n    }\n\n    /**\n     * Delete the test branch\n     */\n    async function deleteBranch() {\n      if (!branch?.id) {\n        throw new Error(\"No branch to delete\");\n      }\n\n      await apiClient.deleteProjectBranch(options.projectId, branch.id);\n      branch = undefined;\n    }\n\n    beforeAll(async () => {\n      process.env.DATABASE_URL = await withRetry(createBranch, {\n        maxRetries: 8,\n        baseDelayMs: 1000,\n      });\n\n      if (options.autoCloseWebSockets) {\n        neonSockets = new Set<WebSocket>();\n\n        // Custom WebSocket constructor that tracks Neon WebSocket connections\n        class TrackingWebSocket extends WebSocket {\n          constructor(url: string) {\n            super(url);\n\n            // Only track Neon WebSocket connections\n            if (!url.includes(\".neon.tech/\")) return;\n\n            neonSockets!.add(this);\n          }\n        }\n\n        // Install a custom WebSocket constructor that tracks Neon WebSocket\n        // connections and closes them before deleting the branch\n        try {\n          const { neonConfig } = await import(\"@neondatabase/serverless\");\n          neonConfig.webSocketConstructor = TrackingWebSocket;\n        } catch {\n          throw new Error(\n            \"autoCloseWebSockets requires @neondatabase/serverless to be installed. Run: npm install @neondatabase/serverless\",\n          );\n        }\n      }\n    });\n\n    afterAll(async () => {\n      process.env.DATABASE_URL = undefined;\n\n      // Close all tracked Neon WebSocket connections before deleting the branch\n      if (options.autoCloseWebSockets && neonSockets) {\n        // Suppress Neon WebSocket \"Connection terminated unexpectedly\" error\n        process.prependListener(\"uncaughtException\", neonWsErrorHandler);\n\n        // Close tracked Neon WebSocket connections before deleting the branch\n        neonSockets.forEach((ws) => ws.close());\n      }\n\n      if (options.deleteBranch !== false) {\n        await deleteBranch();\n      }\n    });\n\n    /**\n     * Return the Neon branch object\n     *\n     * @returns The Neon branch object\n     */\n    return () => branch;\n  };\n\n  // Attach utilities\n  neonTesting.deleteAllTestBranches = deleteAllTestBranches;\n  neonTesting.api = apiClient;\n\n  return neonTesting;\n}\n\n/**\n * Error handler: Suppress Neon WebSocket \"Connection terminated unexpectedly\"\n * error\n */\nconst neonWsErrorHandler = (error: Error) => {\n  const isNeonWsClose =\n    error.message.includes(\"Connection terminated unexpectedly\") &&\n    error.stack?.includes(\"@neondatabase/serverless\");\n\n  if (isNeonWsClose) {\n    // Swallow this specific Neon WS termination error\n    return;\n  }\n\n  // For any other error, detach and rethrow\n  throw error;\n};\n\n/**\n * Reusable API call wrapper with automatic retry on 423 errors with exponential\n * backoff\n *\n * https://neon.com/docs/reference/typescript-sdk#error-handling\n * https://neon.com/docs/changelog/2022-07-20\n */\nasync function withRetry<T>(\n  fn: () => Promise<T>,\n  options: {\n    maxRetries: number;\n    baseDelayMs: number;\n  },\n): Promise<T> {\n  if (!Number.isInteger(options.maxRetries) || options.maxRetries <= 0) {\n    throw new Error(\"maxRetries must be a positive integer\");\n  }\n\n  if (!Number.isInteger(options.baseDelayMs) || options.baseDelayMs <= 0) {\n    throw new Error(\"baseDelayMs must be a positive integer\");\n  }\n\n  for (let attempt = 1; attempt <= options.maxRetries; attempt++) {\n    try {\n      return await fn();\n    } catch (error: any) {\n      const status = error?.response?.status;\n\n      // Retry on 423 (resource locked) with exponential backoff\n      if (status === 423 && attempt < options.maxRetries) {\n        const delay = options.baseDelayMs * Math.pow(2, attempt - 1);\n\n        console.log(\n          `API call failed with 423, retrying in ${delay}ms (attempt ${attempt}/${options.maxRetries})`,\n        );\n        await new Promise((resolve) => setTimeout(resolve, delay));\n\n        continue;\n      }\n\n      // Surface Neon API error details that are otherwise buried in the Axios error\n      if (error?.response?.data?.code) {\n        const { code, message } = error.response.data;\n        throw new Error(\n          `Neon API error - HTTP ${status} - ${code} - ${message}`,\n          { cause: error },\n        );\n      }\n\n      // Non-API errors (network, timeouts, etc.) pass through as-is\n      throw error;\n    }\n  }\n  throw new Error(\"apiCallWithRetry reached unexpected end\");\n}\n"]}

package/dist/singleton.d.ts.map

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

package/dist/singleton.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../src/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","sourcesContent":["/**\n * Create a lazy singleton from a factory function\n */\nexport function lazySingleton<T>(factory: () => T): () => T {\n  let instance: T | undefined;\n  return () => {\n    instance ??= factory();\n    return instance;\n  };\n}\n"]}