neon-testing 2.0.1-beta.6 → 2.0.1-beta.8

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+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;
+}
+/** Options for overriding test database setup (excludes apiKey) */
+export type NeonTestingOverrides = Omit<Partial<NeonTestingOptions>, "apiKey">;
+/**
+ * Factory function that creates a Neon test database setup/teardown function
+ * for Vitest test suites.
+ *
+ * @param apiKey - The Neon API key, this is used to create and teardown test branches
+ * @param projectId - The Neon project ID to operate on
+ * @param parentBranchId - The parent branch ID for the new branch. If omitted or empty, the branch will be created from the project's default branch.
+ * @param schemaOnly - Whether to create a schema-only branch (default: false)
+ * @param endpoint - The type of connection to create (pooler is recommended)
+ * @param deleteBranch - Delete the test branch in afterAll (default: true). Disabling this will leave each test branch in the Neon project after the test suite runs
+ * @returns A setup/teardown function for Vitest test suites
+ *
+ * Side effects:
+ * - Sets the `DATABASE_URL` environment variable to the connection URI for the
+ *   new branch
+ * - Deletes the test branch after the test suite runs
+ */
+export declare function makeNeonTesting(factoryOptions: NeonTestingOptions): {
+    (overrides?: NeonTestingOverrides): void;
+    deleteAllTestBranches: () => Promise<void>;
+};

package/dist/index.js

@@ -0,0 +1,179 @@
+/**
+ * https://neon.com/docs/reference/typescript-sdk
+ */
+import { createApiClient, EndpointType, } from "@neondatabase/api-client";
+import { afterAll, beforeAll } from "vitest";
+import { neonConfig } from "@neondatabase/serverless";
+/**
+ * Creates a PostgreSQL connection URI from connection parameters
+ *
+ * @param connectionParameters - The connection parameters object
+ * @param type - The type of connection to create (pooler or direct)
+ * @returns A PostgreSQL connection URI string
+ */
+function createConnectionUri(connectionParameters, type) {
+    const { role, password, host, pooler_host, database } = connectionParameters.connection_parameters;
+    const hostname = type === "pooler" ? pooler_host : host;
+    return `postgresql://${role}:${password}@${hostname}/${database}?sslmode=require`;
+}
+/**
+ * Factory function that creates a Neon test database setup/teardown function
+ * for Vitest test suites.
+ *
+ * @param apiKey - The Neon API key, this is used to create and teardown test branches
+ * @param projectId - The Neon project ID to operate on
+ * @param parentBranchId - The parent branch ID for the new branch. If omitted or empty, the branch will be created from the project's default branch.
+ * @param schemaOnly - Whether to create a schema-only branch (default: false)
+ * @param endpoint - The type of connection to create (pooler is recommended)
+ * @param deleteBranch - Delete the test branch in afterAll (default: true). Disabling this will leave each test branch in the Neon project after the test suite runs
+ * @returns A setup/teardown function for Vitest test suites
+ *
+ * Side effects:
+ * - Sets the `DATABASE_URL` environment variable to the connection URI for the
+ *   new branch
+ * - Deletes the test branch after the test suite runs
+ */
+export function makeNeonTesting(factoryOptions) {
+    const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });
+    /**
+     * Delete all test branches
+     */
+    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);
+            }
+        }
+    }
+    const testDbSetup = (
+    /** Override any factory options except apiKey */
+    overrides) => {
+        // Merge factory options with overrides
+        const options = { ...factoryOptions, ...overrides };
+        // Each test file gets its own branch ID and database client
+        let branchId;
+        // List of tracked Neon WebSocket connections
+        const 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);
+            }
+        }
+        /**
+         * Create a new test branch
+         *
+         * @returns The connection URI for the new branch
+         */
+        async function createBranch() {
+            const { data } = await apiClient.createProjectBranch(options.projectId, {
+                branch: {
+                    name: `test/${crypto.randomUUID()}`,
+                    parent_id: options.parentBranchId,
+                    init_source: options.schemaOnly ? "schema-only" : undefined,
+                },
+                endpoints: [{ type: EndpointType.ReadWrite }],
+                annotation_value: {
+                    "integration-test": "true",
+                },
+            });
+            branchId = data.branch.id;
+            const [connectionUri] = data.connection_uris ?? [];
+            if (!connectionUri) {
+                throw new Error("No connection URI found");
+            }
+            return createConnectionUri(connectionUri, options.endpoint ?? "pooler");
+        }
+        /**
+         * Delete the test branch
+         */
+        async function deleteBranch() {
+            if (!branchId) {
+                throw new Error("No branch to delete");
+            }
+            await apiClient.deleteProjectBranch(options.projectId, branchId);
+            branchId = undefined;
+        }
+        beforeAll(async () => {
+            process.env.DATABASE_URL = await withRetry(createBranch, {
+                maxRetries: 5,
+                baseDelayMs: 1000,
+            });
+            if (options.autoCloseWebSockets) {
+                // Install a custom WebSocket constructor that tracks Neon WebSocket
+                // connections and closes them before deleting the branch
+                neonConfig.webSocketConstructor = TrackingWebSocket;
+            }
+        });
+        afterAll(async () => {
+            process.env.DATABASE_URL = undefined;
+            // Close all tracked Neon WebSocket connections before deleting the branch
+            if (options.autoCloseWebSockets) {
+                // 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();
+            }
+        });
+    };
+    // Attach the utility
+    testDbSetup.deleteAllTestBranches = deleteAllTestBranches;
+    return testDbSetup;
+}
+/**
+ * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
+ * error
+ */
+const neonWsErrorHandler = (error) => {
+    const isNeonWsClose = error.message.includes("Connection terminated unexpectedly") &&
+        error.stack?.includes("@neondatabase/serverless");
+    if (isNeonWsClose) {
+        // Swallow this specific Neon WS termination error
+        return;
+    }
+    // For any other error, detach and rethrow
+    throw error;
+};
+/**
+ * Reusable API call wrapper with automatic retry on 423 errors with exponential
+ * backoff
+ *
+ * https://neon.com/docs/reference/typescript-sdk#error-handling
+ * https://neon.com/docs/changelog/2022-07-20
+ */
+async function withRetry(fn, options) {
+    if (!Number.isInteger(options.maxRetries) || options.maxRetries <= 0) {
+        throw new Error("maxRetries must be a positive integer");
+    }
+    if (!Number.isInteger(options.baseDelayMs) || options.baseDelayMs <= 0) {
+        throw new Error("baseDelayMs must be a positive integer");
+    }
+    for (let attempt = 1; attempt <= options.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const status = error?.response?.status;
+            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;
+            }
+            throw error;
+        }
+    }
+    throw new Error("apiCallWithRetry reached unexpected end");
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/singleton.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Create a lazy singleton from a factory function
+ */
+export declare function lazySingleton<T>(factory: () => T): () => T;

package/dist/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/singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../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/utils.js

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

package/dist/utils.js.map

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

package/dist/vite-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from "vite";
+export declare function neonTesting(): Plugin;

package/dist/vite-plugin.js

@@ -0,0 +1,17 @@
+import { fileURLToPath } from "node:url";
+export function neonTesting() {
+    return {
+        name: "neon-testing-plugin",
+        enforce: "pre",
+        config(user) {
+            const setupPath = fileURLToPath(new URL("./vitest-setup.js", import.meta.url));
+            const setup = new Set([...(user.test?.setupFiles ?? []), setupPath]);
+            return {
+                test: {
+                    setupFiles: Array.from(setup),
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=vite-plugin.js.map

package/dist/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,KAAK;QACd,MAAM,CAAC,IAAI;YACT,MAAM,SAAS,GAAG,aAAa,CAC7B,IAAI,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAC9C,CAAC;YAEF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;YAErE,OAAO;gBACL,IAAI,EAAE;oBACJ,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;iBAC9B;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/vitest-setup.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon-testing",
-  "version": "2.0.1-beta.6",
+  "version": "2.0.1-beta.8",
   "description": "A Vitest utility for seamless integration tests with Neon Postgres",
   "keywords": [
     "neon",
@@ -15,24 +15,33 @@
   "bugs": "https://github.com/starmode-base/neon-testing/issues",
   "type": "module",
   "exports": {
-    ".": "./index.ts",
-    "./utils": "./utils.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    },
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js"
+    }
   },
+  "types": "./dist/index.d.ts",
   "files": [
-    "index.ts",
-    "singleton.ts",
-    "utils.ts",
-    "vite-plugin.ts",
+    "dist",
     "vitest-setup.js"
   ],
   "scripts": {
     "test": "vitest",
     "format": "prettier --write .",
-    "release:patch": "bun pm version patch && bun publish --tag latest",
-    "release:minor": "bun pm version minor && bun publish --tag latest",
-    "release:major": "bun pm version major && bun publish --tag latest",
-    "release:beta": "bun pm version prerelease --preid=beta && bun publish --tag beta",
-    "prepublishOnly": "tsc && vitest run && prettier --check .",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp vitest-setup.js dist/",
+    "release:patch": "bun pm version patch && bun run build && bun publish --tag latest",
+    "release:minor": "bun pm version minor && bun run build && bun publish --tag latest",
+    "release:major": "bun pm version major && bun run build && bun publish --tag latest",
+    "release:beta": "bun pm version prerelease --preid=beta && bun run build && bun publish --tag beta",
+    "prepublishOnly": "bun run build && vitest run && prettier --check .",
     "postpublish": "git push --follow-tags"
   },
   "dependencies": {

package/index.ts

@@ -1,283 +0,0 @@
-/**
- * https://neon.com/docs/reference/typescript-sdk
- */
-import {
-  createApiClient,
-  EndpointType,
-  type ConnectionDetails,
-} from "@neondatabase/api-client";
-import { afterAll, beforeAll } from "vitest";
-import { neonConfig } from "@neondatabase/serverless";
-
-/**
- * Creates a PostgreSQL connection URI from connection parameters
- *
- * @param connectionParameters - The connection parameters object
- * @param type - The type of connection to create (pooler or direct)
- * @returns A PostgreSQL connection URI string
- */
-function createConnectionUri(
-  connectionParameters: ConnectionDetails,
-  type: "pooler" | "direct",
-) {
-  const { role, password, host, pooler_host, database } =
-    connectionParameters.connection_parameters;
-
-  const hostname = type === "pooler" ? pooler_host : host;
-
-  return `postgresql://${role}:${password}@${hostname}/${database}?sslmode=require`;
-}
-
-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;
-}
-
-/** Options for overriding test database setup (excludes apiKey) */
-export type NeonTestingOverrides = Omit<Partial<NeonTestingOptions>, "apiKey">;
-
-/**
- * Factory function that creates a Neon test database setup/teardown function
- * for Vitest test suites.
- *
- * @param apiKey - The Neon API key, this is used to create and teardown test branches
- * @param projectId - The Neon project ID to operate on
- * @param parentBranchId - The parent branch ID for the new branch. If omitted or empty, the branch will be created from the project's default branch.
- * @param schemaOnly - Whether to create a schema-only branch (default: false)
- * @param endpoint - The type of connection to create (pooler is recommended)
- * @param deleteBranch - Delete the test branch in afterAll (default: true). Disabling this will leave each test branch in the Neon project after the test suite runs
- * @returns A setup/teardown function for Vitest test suites
- *
- * Side effects:
- * - Sets the `DATABASE_URL` environment variable to the connection URI for the
- *   new branch
- * - Deletes the test branch after the test suite runs
- */
-export function makeNeonTesting(factoryOptions: NeonTestingOptions) {
-  const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });
-
-  /**
-   * Delete all test branches
-   */
-  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,
-        );
-      }
-    }
-  }
-
-  const testDbSetup = (
-    /** Override any factory options except apiKey */
-    overrides?: NeonTestingOverrides,
-  ) => {
-    // Merge factory options with overrides
-    const options = { ...factoryOptions, ...overrides };
-
-    // Each test file gets its own branch ID and database client
-    let branchId: string | undefined;
-
-    // List of tracked Neon WebSocket connections
-    const 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);
-      }
-    }
-
-    /**
-     * Create a new test branch
-     *
-     * @returns The connection URI for the new branch
-     */
-    async function createBranch() {
-      const { data } = await apiClient.createProjectBranch(options.projectId, {
-        branch: {
-          name: `test/${crypto.randomUUID()}`,
-          parent_id: options.parentBranchId,
-          init_source: options.schemaOnly ? "schema-only" : undefined,
-        },
-        endpoints: [{ type: EndpointType.ReadWrite }],
-        annotation_value: {
-          "integration-test": "true",
-        },
-      });
-
-      branchId = data.branch.id;
-
-      const [connectionUri] = data.connection_uris ?? [];
-
-      if (!connectionUri) {
-        throw new Error("No connection URI found");
-      }
-
-      return createConnectionUri(connectionUri, options.endpoint ?? "pooler");
-    }
-
-    /**
-     * Delete the test branch
-     */
-    async function deleteBranch() {
-      if (!branchId) {
-        throw new Error("No branch to delete");
-      }
-
-      await apiClient.deleteProjectBranch(options.projectId, branchId);
-      branchId = undefined;
-    }
-
-    beforeAll(async () => {
-      process.env.DATABASE_URL = await withRetry(createBranch, {
-        maxRetries: 5,
-        baseDelayMs: 1000,
-      });
-
-      if (options.autoCloseWebSockets) {
-        // Install a custom WebSocket constructor that tracks Neon WebSocket
-        // connections and closes them before deleting the branch
-        neonConfig.webSocketConstructor = TrackingWebSocket;
-      }
-    });
-
-    afterAll(async () => {
-      process.env.DATABASE_URL = undefined;
-
-      // Close all tracked Neon WebSocket connections before deleting the branch
-      if (options.autoCloseWebSockets) {
-        // 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();
-      }
-    });
-  };
-
-  // Attach the utility
-  testDbSetup.deleteAllTestBranches = deleteAllTestBranches;
-
-  return testDbSetup;
-}
-
-/**
- * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
- * error
- */
-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;
-};
-
-/**
- * Reusable API call wrapper with automatic retry on 423 errors with exponential
- * backoff
- *
- * https://neon.com/docs/reference/typescript-sdk#error-handling
- * https://neon.com/docs/changelog/2022-07-20
- */
-async function withRetry<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;
-
-      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;
-      }
-
-      throw error;
-    }
-  }
-  throw new Error("apiCallWithRetry reached unexpected end");
-}

package/singleton.ts

@@ -1,10 +0,0 @@
-/**
- * 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/vite-plugin.ts

@@ -1,22 +0,0 @@
-import { fileURLToPath } from "node:url";
-import type { Plugin } from "vite";
-
-export function neonTesting(): Plugin {
-  return {
-    name: "neon-testing-plugin",
-    enforce: "pre",
-    config(user) {
-      const setupPath = fileURLToPath(
-        new URL("./vitest-setup.js", import.meta.url),
-      );
-
-      const setup = new Set([...(user.test?.setupFiles ?? []), setupPath]);
-
-      return {
-        test: {
-          setupFiles: Array.from(setup),
-        },
-      };
-    },
-  };
-}