vitest-prisma 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Aiji Uejima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,252 @@
+[![CI](https://github.com/aiji42/vitest-prisma/actions/workflows/ci.yml/badge.svg)](https://github.com/aiji42/vitest-prisma/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/vitest-prisma.svg)](https://www.npmjs.com/package/vitest-prisma)
+
 # vitest-prisma
 
-Work in progress: successor of [vitest-environment-vprisma](https://github.com/aiji42/vitest-environment-vprisma).
-This is a placeholder release; do not use it yet.
+Run every Vitest test in a Prisma transaction and roll it back automatically. Tests stay isolated
+without truncating tables or re-seeding between tests.
+
+- **Zero cleanup:** `beforeEach`, the test and `afterEach` share one transaction, which is rolled back afterwards.
+- **Works with real application code:** swap your shared `PrismaClient` for the test client with `vi.mock`. Code that calls `$transaction` still gets real nested-transaction semantics through savepoints.
+- **Any Prisma setup:** Prisma 6+, the `prisma-client` or `prisma-client-js` generator, any output path, any driver adapter, `$extends`.
+- **Clear failures:** every error has a stable code and a [documented fix](./docs/errors.md).
+
+> Formerly `vitest-environment-vprisma`. See the [migration guide](./docs/migration-from-vitest-environment-vprisma.md).
+
+## Requirements
+
+- Vitest **>= 4.1** (uses `aroundEach`)
+- Prisma **>= 6**
+- Node.js **>= 22.12**
+- PostgreSQL, MySQL/MariaDB, SQLite or CockroachDB. SQL Server and MongoDB work with
+  [`savepoints: false`](#options).
+
+## Quick start
+
+```bash
+npm install -D vitest-prisma
+```
+
+**1. Create a setup file** that tells vitest-prisma how to build your client:
+
+```ts
+// vitest.setup.ts
+import { createVPrisma } from "vitest-prisma";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "./src/generated/prisma/client";
+
+export const vPrisma = createVPrisma(
+  () => new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) }),
+);
+```
+
+**2. Register it** in your Vitest config:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"],
+  },
+});
+```
+
+**3. Use `vPrisma.client` in tests.** Everything is rolled back after each test:
+
+```ts
+import { expect, test } from "vitest";
+import { vPrisma } from "../vitest.setup";
+
+const prisma = vPrisma.client;
+
+test("creates a user", async () => {
+  await prisma.user.create({ data: { email: "alice@example.com" } });
+  expect(await prisma.user.count()).toBe(1);
+});
+
+test("starts from a clean database", async () => {
+  expect(await prisma.user.count()).toBe(0);
+});
+```
+
+The test database must already have your schema applied, for example with
+`prisma migrate deploy` or `prisma db push` in Vitest `globalSetup` or in CI.
+
+A complete, runnable project (SQLite, no services needed) is in [`examples/sqlite`](./examples/sqlite).
+
+## Mocking a shared client
+
+Most applications import one shared `PrismaClient`. Point that module at the test client in your
+setup file:
+
+```ts
+// src/client.ts: the factory (NOT mocked)
+export const createClient = () => new PrismaClient({ adapter: /* ... */ });
+
+// src/db.ts: the shared instance used by application code (mocked in tests)
+import { createClient } from "./client";
+export const db = createClient();
+```
+
+```ts
+// vitest.setup.ts
+import { vi } from "vitest";
+import { createVPrisma } from "vitest-prisma";
+import { createClient } from "./src/client";
+
+export const vPrisma = createVPrisma(createClient);
+
+vi.mock("./src/db", () => ({ db: vPrisma.client }));
+```
+
+> [!IMPORTANT]
+> The setup file must not import the module it mocks, directly or indirectly. Otherwise
+> `vi.mock`'s factory runs before `vPrisma` is initialized. That is why the factory and the
+> shared instance live in separate files.
+
+## How it works
+
+1. `createVPrisma()` registers an `aroundEach` hook for the test file. Called from a setup file,
+   that means for every test file.
+2. Before each test, it opens an interactive transaction (`$transaction(async (tx) => ...)`) on
+   the client from your factory. `vPrisma.client` forwards to that transaction's client.
+3. `beforeEach`, the test and `afterEach` run inside the transaction.
+4. When the test finishes (pass, fail or timeout), the transaction is rolled back.
+
+Inside the transaction, `vPrisma.client` behaves like a normal client:
+
+- `$transaction(fn)` and `$transaction([...])` run inside a `SAVEPOINT`, so a failure rolls back
+  only that nested transaction, as it would in production.
+- Each standalone query runs inside its own `SAVEPOINT`, so a failing query (for example, a
+  unique-constraint violation you assert with `rejects`) does not abort the rest of the test.
+  Without this, PostgreSQL fails every later query with "current transaction is aborted".
+- `$connect()` / `$disconnect()` are no-ops.
+
+Savepoints go through Prisma's native nested transactions when the transaction client supports
+them (recent Prisma 7+). Otherwise vitest-prisma issues `SAVEPOINT` statements itself.
+
+It works with every Vitest pool (`forks`, `threads`) and with `isolate: false`.
+
+The client is created lazily on first use in each test file and disconnected after the file finishes.
+
+## API
+
+### `createVPrisma(factory, options?)`
+
+Call it from a `setupFiles` module and export the result.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `factory` | `() => PrismaClient` | Builds the client. Called at most once per test file. Configure adapters, `log` and `$extends` here. |
+| `options` | `VPrismaOptions` | Defaults for all test files (see below). |
+
+Returns a `VPrisma` handle:
+
+| Member | Description |
+|---|---|
+| `client` | Client bound to the current test's transaction. Usable in `test`, `beforeEach`, `afterEach` and in code they call. Throws [`E_OUTSIDE_TEST`](./docs/errors.md#e_outside_test) elsewhere. It is a stable reference you can store or pass to `vi.mock`. |
+| `originalClient` | The underlying client, outside any transaction. **Not rolled back.** For `beforeAll` / `afterAll`. |
+| `configure(options)` | Override `rollback` / `savepoints` for the current test file. Call it once at the top level of the file; calling it inside a test throws [`E_CONFIGURE_IN_TEST`](./docs/errors.md#e_configure_in_test). |
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `rollback` | `true` | `false` commits each test's transaction instead. Useful for inspecting data while debugging. |
+| `savepoints` | `true` | Use `SAVEPOINT`s for nested `$transaction` calls and standalone queries. Set `false` for SQL Server / MongoDB, or to [trade safety for speed](#speed-vs-savepoints). |
+| `transactionOptions.timeout` | `86_400_000` | Max lifetime (ms) of a test transaction. Prisma's 5s default is too short for tests, so in practice Vitest's `testTimeout` is the limit. |
+| `transactionOptions.maxWait` | `5_000` | Max time (ms) to wait for a connection. When set, the `aroundEach` hook timeout becomes `maxWait + 10s`, so it can exceed Vitest's `hookTimeout`. |
+| `transactionOptions.isolationLevel` | DB default | Isolation level of the test transaction. |
+
+## Recipes
+
+### Reference data for a whole file
+
+`beforeAll` runs outside any test transaction. Use `originalClient` there and clean up yourself:
+
+```ts
+beforeAll(async () => {
+  await vPrisma.originalClient.plan.create({ data: { id: "pro", name: "Pro" } });
+});
+afterAll(async () => {
+  await vPrisma.originalClient.plan.delete({ where: { id: "pro" } });
+});
+```
+
+For per-test data, use `beforeEach` with `vPrisma.client`. It is rolled back automatically.
+
+### See the data a test wrote
+
+```ts
+vPrisma.configure({ rollback: false }); // this file only
+```
+
+### Speed vs. savepoints
+
+With `savepoints: true` (the default), each standalone query costs three round trips
+(`SAVEPOINT`, the query, `RELEASE`). On a local PostgreSQL, 1,000 queries took about 550 ms with
+savepoints versus 300 ms without. Over a network the gap grows with latency.
+
+`savepoints: false` gives v1-like speed. The cost is that on PostgreSQL a failing query (for
+example, a unique-constraint violation you assert with `rejects`) aborts the rest of that test,
+and a failing nested `$transaction` no longer rolls back on its own. You can turn savepoints off
+only in DB-heavy files that never expect query errors:
+
+```ts
+vPrisma.configure({ savepoints: false });
+```
+
+### Log SQL
+
+Configure logging in the factory: `new PrismaClient({ adapter, log: ["query"] })`.
+
+### Only some tests use the database
+
+Every test in a file covered by the setup file opens a transaction. To keep pure unit tests free
+of database access, put them in a separate [Vitest project](https://vitest.dev/guide/projects)
+that does not include the setup file.
+
+### Parallel test files and unique values
+
+Test files run in parallel, each in its own transaction. If two files insert the same unique
+value (for example the same email), the second insert waits for the first transaction's lock, and
+MySQL may abort one with a deadlock error. Use values unique to each file or test (for example,
+include a random suffix), or run files sequentially with `fileParallelism: false`.
+
+### SQLite
+
+SQLite allows one writer at a time. Set `fileParallelism: false` or give each worker its own
+database file.
+
+## Limitations
+
+- Tests in the same file cannot run concurrently ([`E_CONCURRENT_TEST`](./docs/errors.md#e_concurrent_test)).
+  Separate files run in parallel.
+- `$extends`, `$on` and `$use` cannot be called on `vPrisma.client`. Apply them in the factory.
+- Prisma's fluent relation API (`prisma.user.findUnique(...).posts()`) works, but the chained
+  query does not get its own savepoint.
+- Code that opens its own `PrismaClient` instead of using the mocked shared one is not isolated.
+
+## For AI coding agents
+
+This package is built to be used by coding agents as well as people:
+
+- **Docs are shipped in the package.** `node_modules/vitest-prisma/README.md` and
+  `node_modules/vitest-prisma/docs/` cover setup, API, migration and every error, with no network needed.
+- **Agent Skill:** `node_modules/vitest-prisma/skills/vitest-prisma/SKILL.md` describes how to set
+  up, write tests and debug failures. Copy it into `.claude/skills/` (or your agent's skills
+  directory) to use it.
+- **Errors are actionable.** Messages look like `[vitest-prisma:E_CODE] what happened + how to fix`
+  and link to [docs/errors.md](./docs/errors.md).
+- [`llms.txt`](./llms.txt) indexes the documentation.
+
+## Acknowledgments
+
+v1 was based on [`@quramy/jest-prisma`](https://github.com/Quramy/jest-prisma). Many thanks to
+[@Quramy](https://github.com/Quramy) and its contributors.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+/**
+ * The minimal shape vitest-prisma needs from a Prisma client.
+ * Any `PrismaClient` (Prisma 6+, any generator, any driver adapter, `$extends`-ed or not) satisfies it.
+ */
+interface PrismaClientLike {
+  $transaction(...args: any[]): Promise<any>;
+  $disconnect(): Promise<void>;
+}
+/** Options accepted by the outer interactive transaction (`PrismaClient.$transaction(fn, options)`). */
+interface TransactionOptions {
+  /** Max time (ms) to wait for a connection from the pool. @default 5_000 */
+  maxWait?: number;
+  /**
+   * Max time (ms) the per-test transaction may stay open.
+   * Prisma's own default (5s) is too short for tests, so vitest-prisma raises it.
+   * @default 86_400_000 (24h, i.e. effectively bounded by Vitest's testTimeout)
+   */
+  timeout?: number;
+  /** Isolation level of the per-test transaction. Uses the database default when omitted. */
+  isolationLevel?: string;
+}
+/** Behavior that can be overridden per test file with {@link VPrisma.configure}. */
+interface FileOptions {
+  /**
+   * Roll back the transaction after each test.
+   * Set to `false` to commit instead (useful for inspecting data while debugging).
+   * @default true
+   */
+  rollback?: boolean;
+  /**
+   * Use SAVEPOINTs to make the per-test transaction behave like a normal (autocommit) connection:
+   * - `$transaction` called by the code under test becomes a real nested transaction: if it fails,
+   *   only its own writes are rolled back.
+   * - Each standalone query runs in its own SAVEPOINT, so a failing query (e.g. a unique-constraint
+   *   violation you assert with `rejects`) does not abort the rest of the test on PostgreSQL.
+   *
+   * Works on PostgreSQL, MySQL/MariaDB, SQLite and CockroachDB. Set to `false` for databases
+   * without standard SAVEPOINT syntax (SQL Server, MongoDB); nested transactions then run
+   * directly in the test transaction.
+   * @default true
+   */
+  savepoints?: boolean;
+}
+/** Options for {@link createVPrisma}. */
+interface VPrismaOptions extends FileOptions {
+  /** Options for the per-test interactive transaction. */
+  transactionOptions?: TransactionOptions;
+}
+/** The handle returned by {@link createVPrisma}. */
+interface VPrisma<Client extends PrismaClientLike> {
+  /**
+   * A client bound to the current test's transaction. Everything written through it is rolled
+   * back when the test ends. Usable in `test`, `beforeEach`, `afterEach` and in code they call.
+   * Accessing it in `beforeAll`/`afterAll` or at module top level throws `E_OUTSIDE_TEST`.
+   *
+   * It is a stable reference: pass it to `vi.mock` factories or keep it in a module-level constant.
+   */
+  readonly client: Client;
+  /**
+   * The underlying client, outside any transaction. Writes through it are NOT rolled back.
+   * Use it only in `beforeAll`/`afterAll` (e.g. seeding reference data, then cleaning it up).
+   */
+  readonly originalClient: Client;
+  /**
+   * Override {@link FileOptions} for the current test file. Call it at the top level of a test
+   * file; it is reset after the file finishes.
+   * @example
+   * ```ts
+   * vPrisma.configure({ rollback: false });
+   * ```
+   */
+  configure(options: FileOptions): void;
+}
+/**
+ * Stable identifiers for every error thrown by vitest-prisma.
+ * Each code has a matching section in `docs/errors.md` (also shipped in the npm package).
+ */
+type VPrismaErrorCode = "E_OUTSIDE_TEST" | "E_CONCURRENT_TEST" | "E_UNSUPPORTED_ON_TEST_CLIENT" | "E_INVALID_CLIENT" | "E_SAVEPOINT_FAILED" | "E_CONFIGURE_IN_TEST" | "E_INVALID_TRANSACTION_ARGUMENT";
+/** Error thrown by vitest-prisma. Check `code` to branch on the cause. */
+export declare class VPrismaError extends Error {
+  override name: string;
+  readonly code: VPrismaErrorCode;
+  readonly docs: string;
+  constructor(code: VPrismaErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Wrap every test of the current test file in a Prisma transaction that is rolled back when the
+ * test finishes. Call it from a Vitest `setupFiles` module and export the result.
+ *
+ * @param factory Creates the PrismaClient to use. Called lazily, once per test file; the client is
+ *   disconnected after the file finishes. Configure adapters, logging and `$extends` here.
+ * @param options Defaults for every test file. See {@link VPrismaOptions}.
+ *
+ * @example
+ * ```ts
+ * // vitest.setup.ts  (listed in `test.setupFiles`)
+ * import { createVPrisma } from "vitest-prisma";
+ * import { PrismaPg } from "@prisma/adapter-pg";
+ * import { PrismaClient } from "./src/generated/prisma/client";
+ *
+ * export const vPrisma = createVPrisma(
+ *   () => new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) }),
+ * );
+ *
+ * // example.test.ts
+ * import { vPrisma } from "../vitest.setup";
+ *
+ * test("creates a user", async () => {
+ *   await vPrisma.client.user.create({ data: { email: "a@example.com" } });
+ *   expect(await vPrisma.client.user.count()).toBe(1); // rolled back afterwards
+ * });
+ * ```
+ */
+export declare function createVPrisma<Client extends PrismaClientLike>(factory: () => Client, options?: VPrismaOptions): VPrisma<Client>;
+export type { FileOptions, PrismaClientLike, TransactionOptions, VPrisma, VPrismaErrorCode, VPrismaOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,270 @@
+import { afterAll, aroundEach, expect } from "vitest";
+import { AsyncLocalStorage } from "node:async_hooks";
+// src/errors.ts
+const DOCS_URL = "https://github.com/aiji42/vitest-prisma/blob/main/docs/errors.md";
+/** Error thrown by vitest-prisma. Check `code` to branch on the cause. */
+var VPrismaError = class extends Error {
+	name = "VPrismaError";
+	code;
+	docs;
+	constructor(code, message, options) {
+		const docs = `${DOCS_URL}#${code.toLowerCase()}`;
+		super(`[vitest-prisma:${code}] ${message}\nSee: ${docs}`, options);
+		this.code = code;
+		this.docs = docs;
+	}
+};
+// src/test-client.ts
+const UNSUPPORTED = /* @__PURE__ */ new Set([
+	"$on",
+	"$use",
+	"$extends"
+]);
+const RAW_QUERIES = /* @__PURE__ */ new Set([
+	"$queryRaw",
+	"$queryRawUnsafe",
+	"$executeRaw",
+	"$executeRawUnsafe",
+	"$queryRawTyped",
+	"$runCommandRaw"
+]);
+/**
+* Wrap Prisma's interactive-transaction client so that it behaves like a full PrismaClient running
+* in autocommit mode:
+* - `$transaction` becomes a nested transaction (a SAVEPOINT that is rolled back on failure).
+* - Each query issued outside such a nested transaction runs in its own SAVEPOINT, so a failing
+*   statement does not abort the whole test transaction (PostgreSQL "current transaction is aborted").
+* - Connection management is a no-op.
+*
+* With `savepoints: false`, nested transactions and queries run directly in the test transaction.
+*/
+function createTestClient(tx, savepoints) {
+	const insideNested = new AsyncLocalStorage();
+	let queue = Promise.resolve();
+	let savepointSeq = 0;
+	const serialize = (fn) => {
+		if (insideNested.getStore()) return fn();
+		const run = queue.then(fn);
+		queue = run.catch(() => {});
+		return run;
+	};
+	const nativeNested = typeof tx.$transaction === "function" ? tx.$transaction.bind(tx) : void 0;
+	const withSavepoint = async (fn) => {
+		if (!savepoints) return fn();
+		if (nativeNested) return nativeNested(async () => await fn());
+		const name = `vprisma_sp_${++savepointSeq}`;
+		await execSavepoint(tx, `SAVEPOINT ${name}`);
+		let result;
+		try {
+			result = await fn();
+		} catch (error) {
+			await execSavepoint(tx, `ROLLBACK TO SAVEPOINT ${name}`);
+			throw error;
+		}
+		await execSavepoint(tx, `RELEASE SAVEPOINT ${name}`);
+		return result;
+	};
+	const $transaction = (arg) => {
+		let body;
+		if (typeof arg === "function") body = async () => arg(proxy);
+		else if (Array.isArray(arg)) body = async () => {
+			const results = [];
+			for (const query of arg) results.push(await query);
+			return results;
+		};
+		else throw new VPrismaError("E_INVALID_TRANSACTION_ARGUMENT", `vPrisma.client.\$transaction() expects a callback or an array of Prisma queries but received ${arg === null ? "null" : typeof arg}.`);
+		return serialize(() => withSavepoint(() => insideNested.run(true, body)));
+	};
+	const wrapQuery = (query) => {
+		if (!savepoints || !isPrismaPromise(query)) return query;
+		let result;
+		const run = () => {
+			result ??= insideNested.getStore() ? Promise.resolve(query) : serialize(() => withSavepoint(() => query));
+			return result;
+		};
+		return new Proxy(query, { get(target, prop) {
+			if (prop === "then") return (ok, ng) => run().then(ok, ng);
+			if (prop === "catch") return (ng) => run().catch(ng);
+			if (prop === "finally") return (fn) => run().finally(fn);
+			const value = Reflect.get(target, prop, target);
+			return typeof value === "function" ? value.bind(target) : value;
+		} });
+	};
+	const wrapFunction = (fn, thisArg) => (...args) => wrapQuery(fn.apply(thisArg, args));
+	const delegates = /* @__PURE__ */ new Map();
+	const wrapDelegate = (prop, delegate) => {
+		let wrapped = delegates.get(prop);
+		if (!wrapped) {
+			wrapped = new Proxy(delegate, { get(target, key) {
+				const value = Reflect.get(target, key, target);
+				return typeof value === "function" ? wrapFunction(value, target) : value;
+			} });
+			delegates.set(prop, wrapped);
+		}
+		return wrapped;
+	};
+	const proxy = new Proxy(tx, { get(target, prop) {
+		if (prop === "$transaction") return $transaction;
+		if (prop === "$connect" || prop === "$disconnect") return async () => {};
+		if (UNSUPPORTED.has(prop)) throw new VPrismaError("E_UNSUPPORTED_ON_TEST_CLIENT", `\`${String(prop)}\` is not available on vPrisma.client because it is bound to a transaction. Apply \`${String(prop)}\` to the client inside the factory passed to createVPrisma() instead.`);
+		const value = Reflect.get(target, prop, target);
+		if (RAW_QUERIES.has(prop) && typeof value === "function") return wrapFunction(value, target);
+		if (typeof prop === "string" && !prop.startsWith("$") && isObject(value)) return wrapDelegate(prop, value);
+		return value;
+	} });
+	return proxy;
+}
+const isObject = (value) => (typeof value === "object" || typeof value === "function") && value !== null;
+const isPrismaPromise = (value) => isObject(value) && value[Symbol.toStringTag] === "PrismaPromise";
+async function execSavepoint(tx, sql) {
+	try {
+		await tx.$executeRawUnsafe(sql);
+	} catch (cause) {
+		throw new VPrismaError("E_SAVEPOINT_FAILED", `Failed to run \`${sql}\`: ${cause instanceof Error ? cause.message.trim().split("\n").at(-1) : String(cause)}. If your database does not support standard SAVEPOINT syntax (e.g. SQL Server, MongoDB), use createVPrisma(factory, { savepoints: false }).`, { cause });
+	}
+}
+// src/index.ts
+const DEFAULT_TIMEOUT = 864e5;
+const DEFAULT_MAX_WAIT = 5e3;
+const PROBED_PROPS = /* @__PURE__ */ new Set([
+	"then",
+	"__esModule",
+	"toJSON",
+	"asymmetricMatch",
+	"$$typeof",
+	"nodeType",
+	"inspect",
+	"_isMockFunction"
+]);
+var RollbackSignal = class extends Error {};
+const STATE_KEY = Symbol.for("vitest-prisma.state");
+const globals = globalThis;
+const workerState = globals[STATE_KEY] ?? {
+	slots: [],
+	next: 0,
+	file: void 0
+};
+globals[STATE_KEY] = workerState;
+/**
+* Wrap every test of the current test file in a Prisma transaction that is rolled back when the
+* test finishes. Call it from a Vitest `setupFiles` module and export the result.
+*
+* @param factory Creates the PrismaClient to use. Called lazily, once per test file; the client is
+*   disconnected after the file finishes. Configure adapters, logging and `$extends` here.
+* @param options Defaults for every test file. See {@link VPrismaOptions}.
+*
+* @example
+* ```ts
+* // vitest.setup.ts  (listed in `test.setupFiles`)
+* import { createVPrisma } from "vitest-prisma";
+* import { PrismaPg } from "@prisma/adapter-pg";
+* import { PrismaClient } from "./src/generated/prisma/client";
+*
+* export const vPrisma = createVPrisma(
+*   () => new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) }),
+* );
+*
+* // example.test.ts
+* import { vPrisma } from "../vitest.setup";
+*
+* test("creates a user", async () => {
+*   await vPrisma.client.user.create({ data: { email: "a@example.com" } });
+*   expect(await vPrisma.client.user.count()).toBe(1); // rolled back afterwards
+* });
+* ```
+*/
+function createVPrisma(factory, options = {}) {
+	const { transactionOptions, ...defaultFileOptions } = options;
+	const slot = takeSlot();
+	const getOriginal = () => {
+		if (slot.original) return slot.original;
+		const client = factory();
+		if (typeof client?.$transaction !== "function") throw new VPrismaError("E_INVALID_CLIENT", "The factory passed to createVPrisma() must return a PrismaClient instance.");
+		slot.original = client;
+		return client;
+	};
+	const hookTimeout = transactionOptions?.maxWait === void 0 ? void 0 : transactionOptions.maxWait + 1e4;
+	aroundEach(async (runTest) => {
+		if (slot.running) throw new VPrismaError("E_CONCURRENT_TEST", "Tests in the same file cannot run concurrently with vitest-prisma because they would share one transaction. Remove `.concurrent` / `sequence.concurrent` for files that use vPrisma.");
+		slot.running = true;
+		const { rollback = true, savepoints = true } = {
+			...defaultFileOptions,
+			...slot.fileOptions
+		};
+		try {
+			await getOriginal().$transaction(async (tx) => {
+				slot.current = createTestClient(tx, savepoints);
+				try {
+					await runTest();
+				} finally {
+					slot.current = void 0;
+				}
+				if (rollback) throw new RollbackSignal();
+			}, {
+				maxWait: DEFAULT_MAX_WAIT,
+				timeout: DEFAULT_TIMEOUT,
+				...transactionOptions
+			});
+		} catch (error) {
+			if (!(error instanceof RollbackSignal)) throw error;
+		} finally {
+			slot.running = false;
+		}
+	}, hookTimeout);
+	afterAll(async () => {
+		workerState.next = 0;
+		workerState.file = void 0;
+		slot.fileOptions = {};
+		const client = slot.original;
+		slot.original = void 0;
+		await client?.$disconnect();
+	});
+	return {
+		client: new Proxy({}, { get(_, prop) {
+			if (slot.current) return Reflect.get(slot.current, prop);
+			if (prop === "$connect" || prop === "$disconnect") return async () => {};
+			if (typeof prop === "symbol" || PROBED_PROPS.has(prop)) return void 0;
+			if (prop in Object.prototype) return Reflect.get(Object.prototype, prop);
+			throw new VPrismaError("E_OUTSIDE_TEST", `vPrisma.client.${prop} was accessed outside a test. vPrisma.client is only usable inside \`test\`, \`beforeEach\`, \`afterEach\` and code called from them. Use vPrisma.originalClient in \`beforeAll\`/\`afterAll\` (writes are not rolled back), and avoid destructuring vPrisma.client at module top level.`);
+		} }),
+		get originalClient() {
+			return getOriginal();
+		},
+		configure(options) {
+			if (slot.running) throw new VPrismaError("E_CONFIGURE_IN_TEST", "vPrisma.configure() was called while a test was running. It applies to the whole test file, so call it once at the top level of the file.");
+			slot.fileOptions = {
+				...slot.fileOptions,
+				...options
+			};
+		}
+	};
+}
+/**
+* Pick the slot for the next createVPrisma() call. Calls are numbered from 0 within each test
+* file; the numbering restarts when the file changes, even if the previous file never reached its
+* afterAll (collection error, skipped file).
+*/
+function takeSlot() {
+	const file = expect.getState().testPath;
+	if (file !== workerState.file) {
+		workerState.file = file;
+		workerState.next = 0;
+		for (const slot of workerState.slots) {
+			slot.fileOptions = {};
+			slot.original?.$disconnect().catch(() => {});
+			slot.original = void 0;
+		}
+	}
+	const index = workerState.next++;
+	const slot = workerState.slots[index] ?? {
+		current: void 0,
+		running: false,
+		original: void 0,
+		fileOptions: {}
+	};
+	workerState.slots[index] = slot;
+	return slot;
+}
+export { VPrismaError, createVPrisma };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/errors.ts","../src/test-client.ts","../src/index.ts"],"sourcesContent":["const DOCS_URL = \"https://github.com/aiji42/vitest-prisma/blob/main/docs/errors.md\";\n\n/**\n * Stable identifiers for every error thrown by vitest-prisma.\n * Each code has a matching section in `docs/errors.md` (also shipped in the npm package).\n */\nexport type VPrismaErrorCode =\n  | \"E_OUTSIDE_TEST\"\n  | \"E_CONCURRENT_TEST\"\n  | \"E_UNSUPPORTED_ON_TEST_CLIENT\"\n  | \"E_INVALID_CLIENT\"\n  | \"E_SAVEPOINT_FAILED\"\n  | \"E_CONFIGURE_IN_TEST\"\n  | \"E_INVALID_TRANSACTION_ARGUMENT\";\n\n/** Error thrown by vitest-prisma. Check `code` to branch on the cause. */\nexport class VPrismaError extends Error {\n  override name = \"VPrismaError\";\n  readonly code: VPrismaErrorCode;\n  readonly docs: string;\n\n  constructor(code: VPrismaErrorCode, message: string, options?: ErrorOptions) {\n    const docs = `${DOCS_URL}#${code.toLowerCase()}`;\n    super(`[vitest-prisma:${code}] ${message}\\nSee: ${docs}`, options);\n    this.code = code;\n    this.docs = docs;\n  }\n}\n","import { AsyncLocalStorage } from \"node:async_hooks\";\nimport { VPrismaError } from \"./errors.ts\";\n\ntype TxClient = {\n  $executeRawUnsafe(query: string): PromiseLike<unknown>;\n  /** Native nested transactions (savepoints through the driver adapter), in recent Prisma 7+. */\n  $transaction?: (fn: () => Promise<unknown>) => Promise<unknown>;\n};\n\nconst UNSUPPORTED = new Set<PropertyKey>([\"$on\", \"$use\", \"$extends\"]);\nconst RAW_QUERIES = new Set<PropertyKey>([\n  \"$queryRaw\",\n  \"$queryRawUnsafe\",\n  \"$executeRaw\",\n  \"$executeRawUnsafe\",\n  \"$queryRawTyped\",\n  \"$runCommandRaw\",\n]);\n\n/**\n * Wrap Prisma's interactive-transaction client so that it behaves like a full PrismaClient running\n * in autocommit mode:\n * - `$transaction` becomes a nested transaction (a SAVEPOINT that is rolled back on failure).\n * - Each query issued outside such a nested transaction runs in its own SAVEPOINT, so a failing\n *   statement does not abort the whole test transaction (PostgreSQL \"current transaction is aborted\").\n * - Connection management is a no-op.\n *\n * With `savepoints: false`, nested transactions and queries run directly in the test transaction.\n */\nexport function createTestClient<Client>(tx: TxClient, savepoints: boolean): Client {\n  // Set while running inside a nested transaction (or batch), whose own SAVEPOINT already applies.\n  const insideNested = new AsyncLocalStorage<true>();\n  // All statements share one connection, so top-level units of work must run one at a time.\n  let queue: Promise<unknown> = Promise.resolve();\n  let savepointSeq = 0;\n\n  const serialize = <T>(fn: () => Promise<T>): Promise<T> => {\n    if (insideNested.getStore()) return fn();\n    const run = queue.then(fn);\n    queue = run.catch(() => {});\n    return run;\n  };\n\n  // Prefer Prisma's own nested transactions: the driver adapter issues SAVEPOINT with the right\n  // protocol (MySQL rejects SAVEPOINT as a prepared statement, which $executeRawUnsafe uses).\n  const nativeNested = typeof tx.$transaction === \"function\" ? tx.$transaction.bind(tx) : undefined;\n\n  const withSavepoint = async <T>(fn: () => PromiseLike<T>): Promise<T> => {\n    if (!savepoints) return fn();\n    if (nativeNested) return nativeNested(async () => await fn()) as Promise<T>;\n    const name = `vprisma_sp_${++savepointSeq}`;\n    await execSavepoint(tx, `SAVEPOINT ${name}`);\n    let result: T;\n    try {\n      result = await fn();\n    } catch (error) {\n      await execSavepoint(tx, `ROLLBACK TO SAVEPOINT ${name}`);\n      throw error;\n    }\n    await execSavepoint(tx, `RELEASE SAVEPOINT ${name}`);\n    return result;\n  };\n\n  const $transaction = (arg: unknown): Promise<unknown> => {\n    let body: () => Promise<unknown>;\n    if (typeof arg === \"function\") {\n      body = async () => arg(proxy);\n    } else if (Array.isArray(arg)) {\n      body = async () => {\n        const results: unknown[] = [];\n        for (const query of arg) results.push(await query);\n        return results;\n      };\n    } else {\n      throw new VPrismaError(\n        \"E_INVALID_TRANSACTION_ARGUMENT\",\n        \"vPrisma.client.$transaction() expects a callback or an array of Prisma queries \" +\n          `but received ${arg === null ? \"null\" : typeof arg}.`,\n      );\n    }\n    return serialize(() => withSavepoint(() => insideNested.run(true, body)));\n  };\n\n  // Defer a lazy PrismaPromise until it is awaited, then run it in its own SAVEPOINT.\n  const wrapQuery = (query: unknown): unknown => {\n    // Only lazy PrismaPromises: an eager promise (e.g. from a $extends method) has already started.\n    if (!savepoints || !isPrismaPromise(query)) return query;\n    let result: Promise<unknown> | undefined;\n    const run = () => {\n      // Inside a nested transaction a failing query fails that transaction, as it would for real.\n      result ??= insideNested.getStore()\n        ? Promise.resolve(query)\n        : serialize(() => withSavepoint(() => query));\n      return result;\n    };\n    return new Proxy(query, {\n      get(target, prop) {\n        if (prop === \"then\") return (ok?: Fn, ng?: Fn) => run().then(ok, ng);\n        if (prop === \"catch\") return (ng?: Fn) => run().catch(ng);\n        if (prop === \"finally\") return (fn?: () => void) => run().finally(fn);\n        const value = Reflect.get(target, prop, target);\n        return typeof value === \"function\" ? value.bind(target) : value;\n      },\n    });\n  };\n\n  const wrapFunction =\n    (fn: Fn, thisArg: unknown): Fn =>\n    (...args) =>\n      wrapQuery(fn.apply(thisArg, args));\n\n  const delegates = new Map<PropertyKey, unknown>();\n  const wrapDelegate = (prop: PropertyKey, delegate: object): unknown => {\n    let wrapped = delegates.get(prop);\n    if (!wrapped) {\n      wrapped = new Proxy(delegate, {\n        get(target, key) {\n          const value = Reflect.get(target, key, target);\n          return typeof value === \"function\" ? wrapFunction(value, target) : value;\n        },\n      });\n      delegates.set(prop, wrapped);\n    }\n    return wrapped;\n  };\n\n  const proxy = new Proxy(tx, {\n    get(target, prop) {\n      if (prop === \"$transaction\") return $transaction;\n      if (prop === \"$connect\" || prop === \"$disconnect\") return async () => {};\n      if (UNSUPPORTED.has(prop)) {\n        throw new VPrismaError(\n          \"E_UNSUPPORTED_ON_TEST_CLIENT\",\n          `\\`${String(prop)}\\` is not available on vPrisma.client because it is bound to a transaction. ` +\n            `Apply \\`${String(prop)}\\` to the client inside the factory passed to createVPrisma() instead.`,\n        );\n      }\n      const value = Reflect.get(target, prop, target);\n      if (RAW_QUERIES.has(prop) && typeof value === \"function\") return wrapFunction(value, target);\n      if (typeof prop === \"string\" && !prop.startsWith(\"$\") && isObject(value)) {\n        return wrapDelegate(prop, value);\n      }\n      return value;\n    },\n  }) as Client;\n  return proxy;\n}\n\n// biome-ignore lint/suspicious/noExplicitAny: generic passthrough\ntype Fn = (...args: any[]) => any;\n\nconst isObject = (value: unknown): value is object =>\n  (typeof value === \"object\" || typeof value === \"function\") && value !== null;\n\nconst isPrismaPromise = (value: unknown): value is PromiseLike<unknown> =>\n  isObject(value) &&\n  (value as { [Symbol.toStringTag]?: unknown })[Symbol.toStringTag] === \"PrismaPromise\";\n\nasync function execSavepoint(tx: TxClient, sql: string): Promise<void> {\n  try {\n    await tx.$executeRawUnsafe(sql);\n  } catch (cause) {\n    const reason = cause instanceof Error ? cause.message.trim().split(\"\\n\").at(-1) : String(cause);\n    throw new VPrismaError(\n      \"E_SAVEPOINT_FAILED\",\n      `Failed to run \\`${sql}\\`: ${reason}. ` +\n        \"If your database does not support standard SAVEPOINT syntax (e.g. SQL Server, MongoDB), \" +\n        \"use createVPrisma(factory, { savepoints: false }).\",\n      { cause },\n    );\n  }\n}\n","import { afterAll, aroundEach, expect } from \"vitest\";\nimport { VPrismaError } from \"./errors.ts\";\nimport { createTestClient } from \"./test-client.ts\";\nimport type { FileOptions, PrismaClientLike, VPrisma, VPrismaOptions } from \"./types.ts\";\n\nexport { VPrismaError, type VPrismaErrorCode } from \"./errors.ts\";\nexport type {\n  FileOptions,\n  PrismaClientLike,\n  TransactionOptions,\n  VPrisma,\n  VPrismaOptions,\n} from \"./types.ts\";\n\nconst DEFAULT_TIMEOUT = 86_400_000;\n// Below Vitest's default hookTimeout (10s), so Prisma's pool-timeout error surfaces instead of a\n// hook timeout.\nconst DEFAULT_MAX_WAIT = 5_000;\n\n// Properties that tooling (vi.mock, util.inspect, expect, await) probes on arbitrary objects.\n// They must not throw when accessed outside a test. Object.prototype members are allowed too.\nconst PROBED_PROPS = new Set<PropertyKey>([\n  \"then\",\n  \"__esModule\",\n  \"toJSON\",\n  \"asymmetricMatch\",\n  \"$$typeof\",\n  \"nodeType\",\n  \"inspect\",\n  \"_isMockFunction\",\n]);\n\nclass RollbackSignal extends Error {}\n\n/**\n * Per-worker state shared by every createVPrisma() call. With `isolate: false`, the setup file is\n * re-run for each test file while application modules (and the vPrisma.client they captured in\n * vi.mock) stay cached. Instances are matched to slots by call order within a file, so a stale\n * reference still reaches the current file's transaction.\n */\ninterface Slot {\n  /** Client bound to the running test's transaction. */\n  current: unknown;\n  running: boolean;\n  original: PrismaClientLike | undefined;\n  fileOptions: FileOptions;\n}\ninterface WorkerState {\n  slots: Slot[];\n  next: number;\n  /** Test file whose setup is (or was last) running in this worker. */\n  file: string | undefined;\n}\nconst STATE_KEY = Symbol.for(\"vitest-prisma.state\");\nconst globals = globalThis as Record<symbol, WorkerState | undefined>;\nconst workerState: WorkerState = globals[STATE_KEY] ?? {\n  slots: [],\n  next: 0,\n  file: undefined,\n};\nglobals[STATE_KEY] = workerState;\n\n/**\n * Wrap every test of the current test file in a Prisma transaction that is rolled back when the\n * test finishes. Call it from a Vitest `setupFiles` module and export the result.\n *\n * @param factory Creates the PrismaClient to use. Called lazily, once per test file; the client is\n *   disconnected after the file finishes. Configure adapters, logging and `$extends` here.\n * @param options Defaults for every test file. See {@link VPrismaOptions}.\n *\n * @example\n * ```ts\n * // vitest.setup.ts  (listed in `test.setupFiles`)\n * import { createVPrisma } from \"vitest-prisma\";\n * import { PrismaPg } from \"@prisma/adapter-pg\";\n * import { PrismaClient } from \"./src/generated/prisma/client\";\n *\n * export const vPrisma = createVPrisma(\n *   () => new PrismaClient({ adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }) }),\n * );\n *\n * // example.test.ts\n * import { vPrisma } from \"../vitest.setup\";\n *\n * test(\"creates a user\", async () => {\n *   await vPrisma.client.user.create({ data: { email: \"a@example.com\" } });\n *   expect(await vPrisma.client.user.count()).toBe(1); // rolled back afterwards\n * });\n * ```\n */\nexport function createVPrisma<Client extends PrismaClientLike>(\n  factory: () => Client,\n  options: VPrismaOptions = {},\n): VPrisma<Client> {\n  const { transactionOptions, ...defaultFileOptions } = options;\n  const slot = takeSlot();\n\n  const getOriginal = (): Client => {\n    if (slot.original) return slot.original as Client;\n    const client = factory();\n    if (typeof client?.$transaction !== \"function\") {\n      throw new VPrismaError(\n        \"E_INVALID_CLIENT\",\n        \"The factory passed to createVPrisma() must return a PrismaClient instance.\",\n      );\n    }\n    slot.original = client;\n    return client;\n  };\n\n  // The connection wait happens in aroundEach's setup phase, which Vitest bounds by hookTimeout.\n  const hookTimeout =\n    transactionOptions?.maxWait === undefined ? undefined : transactionOptions.maxWait + 10_000;\n\n  aroundEach(async (runTest) => {\n    if (slot.running) {\n      throw new VPrismaError(\n        \"E_CONCURRENT_TEST\",\n        \"Tests in the same file cannot run concurrently with vitest-prisma because they would share \" +\n          \"one transaction. Remove `.concurrent` / `sequence.concurrent` for files that use vPrisma.\",\n      );\n    }\n    slot.running = true;\n    const { rollback = true, savepoints = true } = {\n      ...defaultFileOptions,\n      ...slot.fileOptions,\n    };\n    try {\n      await getOriginal().$transaction(\n        async (tx: Parameters<typeof createTestClient>[0]) => {\n          slot.current = createTestClient<Client>(tx, savepoints);\n          try {\n            await runTest();\n          } finally {\n            slot.current = undefined;\n          }\n          if (rollback) throw new RollbackSignal();\n        },\n        {\n          maxWait: DEFAULT_MAX_WAIT,\n          timeout: DEFAULT_TIMEOUT,\n          ...transactionOptions,\n        },\n      );\n    } catch (error) {\n      if (!(error instanceof RollbackSignal)) throw error;\n    } finally {\n      slot.running = false;\n    }\n  }, hookTimeout);\n\n  afterAll(async () => {\n    workerState.next = 0;\n    workerState.file = undefined;\n    slot.fileOptions = {};\n    const client = slot.original;\n    slot.original = undefined;\n    await client?.$disconnect();\n  });\n\n  const client = new Proxy({} as Client, {\n    get(_, prop) {\n      if (slot.current) return Reflect.get(slot.current, prop);\n      // e.g. `afterAll(() => db.$disconnect())` on a mocked shared client.\n      if (prop === \"$connect\" || prop === \"$disconnect\") return async () => {};\n      if (typeof prop === \"symbol\" || PROBED_PROPS.has(prop)) return undefined;\n      if (prop in Object.prototype) return Reflect.get(Object.prototype, prop);\n      throw new VPrismaError(\n        \"E_OUTSIDE_TEST\",\n        `vPrisma.client.${prop} was accessed outside a test. vPrisma.client is only usable inside ` +\n          \"`test`, `beforeEach`, `afterEach` and code called from them. Use vPrisma.originalClient \" +\n          \"in `beforeAll`/`afterAll` (writes are not rolled back), and avoid destructuring \" +\n          \"vPrisma.client at module top level.\",\n      );\n    },\n  });\n\n  return {\n    client,\n    get originalClient() {\n      return getOriginal();\n    },\n    configure(options) {\n      if (slot.running) {\n        throw new VPrismaError(\n          \"E_CONFIGURE_IN_TEST\",\n          \"vPrisma.configure() was called while a test was running. It applies to the whole test \" +\n            \"file, so call it once at the top level of the file.\",\n        );\n      }\n      slot.fileOptions = { ...slot.fileOptions, ...options };\n    },\n  };\n}\n\n/**\n * Pick the slot for the next createVPrisma() call. Calls are numbered from 0 within each test\n * file; the numbering restarts when the file changes, even if the previous file never reached its\n * afterAll (collection error, skipped file).\n */\nfunction takeSlot(): Slot {\n  const file = expect.getState().testPath;\n  if (file !== workerState.file) {\n    workerState.file = file;\n    workerState.next = 0;\n    // Clean up after a file whose afterAll did not run.\n    for (const slot of workerState.slots) {\n      slot.fileOptions = {};\n      void slot.original?.$disconnect().catch(() => {});\n      slot.original = undefined;\n    }\n  }\n  const index = workerState.next++;\n  const slot = workerState.slots[index] ?? {\n    current: undefined,\n    running: false,\n    original: undefined,\n    fileOptions: {},\n  };\n  workerState.slots[index] = slot;\n  return slot;\n}\n"],"mappings":"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"}

package/docs/errors.md

@@ -0,0 +1,118 @@
+# Error reference
+
+Every error thrown by vitest-prisma is a `VPrismaError` whose message starts with
+`[vitest-prisma:<CODE>]` and ends with a link to the matching section below. Branch on
+`error.code` in code; search this file for the code when diagnosing a failure.
+
+## E_OUTSIDE_TEST
+
+**Cause:** `vPrisma.client` was accessed when no test transaction is open:
+
+- in `beforeAll` / `afterAll`,
+- at module top level (for example `const { user } = vPrisma.client`),
+- from code that keeps running after its test has finished (an un-awaited promise, a timer).
+
+**Fix:**
+
+- Move the code into `test`, `beforeEach` or `afterEach`. These all run inside the test transaction.
+- For per-file setup that must happen once, use `vPrisma.originalClient` in `beforeAll` and clean up
+  in `afterAll`. These writes are **not** rolled back.
+- Keep a reference to the client (`const prisma = vPrisma.client`), not to its properties.
+- Make sure every query in the test is awaited.
+
+## E_CONCURRENT_TEST
+
+**Cause:** two tests in the same file ran at the same time (`test.concurrent`, `describe.concurrent`
+or `sequence.concurrent: true`). All tests of a file share one client, and each test needs its own
+transaction, so they cannot overlap.
+
+**Fix:** remove `.concurrent` from files that use vPrisma. Different test files still run in
+parallel, each in its own worker and transaction. To speed up one large file, split it into several files.
+
+## E_UNSUPPORTED_ON_TEST_CLIENT
+
+**Cause:** `$extends`, `$on` or `$use` was called on `vPrisma.client`. The test client wraps a
+transaction, and Prisma does not support these methods on transaction clients.
+
+**Fix:** apply them inside the factory you pass to `createVPrisma`:
+
+```ts
+export const vPrisma = createVPrisma(() =>
+  new PrismaClient({ adapter, log: ["query"] }).$extends(myExtension),
+);
+```
+
+If application code calls `$extends` on a shared client at import time, export the extended client
+from your module and mock that export instead.
+
+## E_INVALID_CLIENT
+
+**Cause:** the factory passed to `createVPrisma` did not return an object with a `$transaction`
+method.
+
+**Fix:** return the client instance itself: `createVPrisma(() => new PrismaClient(...))`. Do not
+return a promise, a module or a model delegate.
+
+## E_SAVEPOINT_FAILED
+
+**Cause:** a `SAVEPOINT` / `RELEASE SAVEPOINT` / `ROLLBACK TO SAVEPOINT` statement failed.
+vitest-prisma uses savepoints for nested `$transaction` calls and to isolate each standalone query.
+The original database error is attached as `error.cause`.
+
+When the transaction client supports nested `$transaction` natively (recent Prisma 7+),
+vitest-prisma uses that instead and this error does not occur.
+
+**Fix:**
+
+- On MySQL with a Prisma 7 release whose transaction client lacks native nested transactions, the
+  cause reads "This command is not supported in the prepared statement protocol". Upgrade Prisma.
+  If you can't, use `savepoints: false`.
+- On SQL Server or MongoDB, which have no standard `SAVEPOINT` syntax, disable savepoints:
+  `createVPrisma(factory, { savepoints: false })`. A failed nested transaction then cannot be
+  rolled back on its own.
+- Otherwise, inspect `error.cause`. A common cause is the test transaction having already been
+  closed by Prisma's transaction `timeout`. Raise it with
+  `createVPrisma(factory, { transactionOptions: { timeout } })`.
+
+## E_CONFIGURE_IN_TEST
+
+**Cause:** `vPrisma.configure()` was called while a test was running. Its options apply to the
+whole test file and are read when each test starts, so a call inside a test would silently change
+every later test in the file.
+
+**Fix:** call `vPrisma.configure()` once, at the top level of the test file. Calling it inside a
+`describe` callback also affects the whole file. To use different options, put those tests in
+another file.
+
+## E_INVALID_TRANSACTION_ARGUMENT
+
+**Cause:** `vPrisma.client.$transaction()` received something other than a callback or an array of
+Prisma queries.
+
+**Fix:** pass `async (tx) => { ... }` or `[prisma.a.create(...), prisma.b.update(...)]`. Query
+arrays must hold un-awaited Prisma queries.
+
+## Not a vitest-prisma error, but common
+
+### `Cannot access 'vPrisma' before initialization` (from `vi.mock`)
+
+The setup file imported the module it mocks (directly or through another import), so the
+mock factory ran before `vPrisma` existed. Import the client *factory* from a module that is
+not mocked, and mock only the module that holds the shared instance. See
+[Mocking a shared client](../README.md#mocking-a-shared-client).
+
+### `Transaction already closed` / `Transaction API error: Transaction ... timed out`
+
+The test ran longer than `transactionOptions.timeout`, which defaults to 24 hours. You may have
+lowered it, or the test leaked a query past its own end. Await every query, or raise the timeout.
+
+### `Transaction failed due to a write conflict or a deadlock` / lock wait timeouts
+
+Two test files running in parallel inserted the same unique value. Each holds its row lock
+until its transaction rolls back, so they block each other. Make test data unique per file or per
+test, or set `fileParallelism: false`.
+
+### SQLite: `database is locked` / `SQLITE_BUSY`
+
+SQLite allows only one writer at a time, and every test holds a write transaction. Set
+`fileParallelism: false` in your Vitest config, or give each worker its own database file.

package/docs/migration-from-vitest-environment-vprisma.md

@@ -0,0 +1,85 @@
+# Migrating from vitest-environment-vprisma
+
+`vitest-prisma` is the successor of `vitest-environment-vprisma` v1. It is a rewrite: it no longer
+ships a Vitest environment and no longer depends on `@quramy/jest-prisma-core`. The per-test
+transaction is driven by Vitest's `aroundEach` hook.
+
+## Requirements
+
+| | vitest-environment-vprisma v1 | vitest-prisma |
+|---|---|---|
+| Vitest | 0.34 – 1.x | **>= 4.1** |
+| Prisma | 2.29 – 5.x | **>= 6** (any generator, any driver adapter) |
+| Node.js | any | **>= 22.12** |
+| Module format | ESM + CJS | ESM only |
+
+## Steps
+
+1. Swap the package:
+
+   ```bash
+   npm remove vitest-environment-vprisma
+   npm install -D vitest-prisma
+   ```
+
+2. Create a setup file that builds the client yourself. This replaces `environment: "vprisma"`,
+   the `vitest-environment-vprisma/setup` setup file and the `databaseUrl` option:
+
+   ```ts
+   // vitest.setup.ts
+   import { createVPrisma } from "vitest-prisma";
+   import { createClient } from "./src/client";
+
+   export const vPrisma = createVPrisma(createClient);
+   ```
+
+3. Update `vitest.config.ts`:
+
+   ```diff
+    export default defineConfig({
+      test: {
+   -    globals: true,
+   -    environment: "vprisma",
+   -    setupFiles: ["vitest-environment-vprisma/setup", "./vitest.setup.ts"],
+   -    environmentOptions: { vprisma: { baseEnv: "jsdom", disableRollback: false } },
+   +    environment: "jsdom", // only if you used baseEnv; otherwise omit
+   +    setupFiles: ["./vitest.setup.ts"],
+      },
+    });
+   ```
+
+   `globals: true` is no longer required.
+
+4. Replace the global `vPrisma` with an import, and remove `"vitest-environment-vprisma"` from
+   `compilerOptions.types` in `tsconfig.json`:
+
+   ```diff
+   +import { vPrisma } from "../vitest.setup";
+    const prisma = vPrisma.client;
+   ```
+
+5. Map the old options:
+
+   | v1 option | vitest-prisma |
+   |---|---|
+   | `baseEnv` | Use Vitest's own `environment` option (or `// @vitest-environment jsdom`). |
+   | `disableRollback: true` | `createVPrisma(factory, { rollback: false })`, or `vPrisma.configure({ rollback: false })` in one file |
+   | `databaseUrl` | Pass the URL to your adapter / client in the factory. |
+   | `verboseQuery: true` | Enable Prisma's own logging in the factory: `new PrismaClient({ adapter, log: ["query"] })` |
+   | `// @vitest-environment-options {...}` | `vPrisma.configure({...})` at the top of the test file |
+   | `enableExperimentalRollbackInTransaction` | Always on (`savepoints: true` by default). |
+
+## Behavior changes
+
+- **Top-level `beforeEach` / `afterEach` now run inside the test transaction.** The v1 workaround
+  of moving `beforeEach` into a `describe` block is no longer needed.
+- **A failing query no longer breaks the rest of the test on PostgreSQL.** Each standalone query
+  runs in its own savepoint.
+- **Nested `$transaction` calls roll back on their own when they fail.** v1 needed an experimental
+  flag for this.
+- **Standalone queries are slower.** Each one runs in a savepoint, which takes about 1.8× as long
+  on a local PostgreSQL. Use `savepoints: false` (globally or per file) for v1-like speed. See
+  [Speed vs. savepoints](../README.md#speed-vs-savepoints).
+- **Concurrent tests in one file now fail fast** with `E_CONCURRENT_TEST`. In v1 they silently
+  shared a transaction.
+- **The client is disconnected after each test file.**

package/package.json

@@ -1,11 +1,97 @@
 {
   "name": "vitest-prisma",
-  "version": "0.0.1",
-  "description": "Successor of vitest-environment-vprisma (work in progress). Not ready for use yet.",
+  "version": "1.0.0",
+  "description": "Isolate every Vitest test in a Prisma transaction and roll it back automatically.",
+  "keywords": [
+    "vitest",
+    "prisma",
+    "testing",
+    "transaction",
+    "rollback",
+    "database"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "docs",
+    "skills"
+  ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aiji42/vitest-environment-vprisma.git"
+    "url": "git+https://github.com/aiji42/vitest-prisma.git"
   },
+  "homepage": "https://github.com/aiji42/vitest-prisma#readme",
+  "bugs": "https://github.com/aiji42/vitest-prisma/issues",
   "author": "aiji42 <aiji42@gmail.com> (https://twitter.com/aiji42_dev)",
-  "license": "MIT"
+  "license": "MIT",
+  "packageManager": "pnpm@12.15.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check:package": "publint && attw --pack . --profile esm-only",
+    "prepack": "pnpm build"
+  },
+  "peerDependencies": {
+    "vitest": ">=4.1.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.6.3",
+    "@semantic-release/exec": "^7.1.0",
+    "@types/node": "^22.20.5",
+    "publint": "^0.3.25",
+    "semantic-release": "^25.0.9",
+    "tsdown": "^0.23.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "release": {
+    "tagFormat": "vitest-prisma@${version}",
+    "branches": [
+      "main",
+      {
+        "name": "beta",
+        "prerelease": true
+      }
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/npm",
+        {
+          "npmPublish": false
+        }
+      ],
+      [
+        "@semantic-release/exec",
+        {
+          "publishCmd": "npm --version && npm stage publish --access public --tag ${nextRelease.channel || 'latest'} --loglevel verbose"
+        }
+      ],
+      [
+        "@semantic-release/github",
+        {
+          "successCommentCondition": "<% if (issue.number >= 10) { %>true<% } %>"
+        }
+      ]
+    ]
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
 }

package/skills/vitest-prisma/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: vitest-prisma
+description: Set up and debug database tests that use vitest-prisma (each Vitest test runs in a Prisma transaction that is rolled back). Use when adding vitest-prisma to a project, writing tests that touch the database through Prisma, migrating from vitest-environment-vprisma, or when a test fails with a [vitest-prisma:E_*] error.
+---
+
+# vitest-prisma
+
+vitest-prisma wraps `beforeEach` + test + `afterEach` in one Prisma interactive transaction and
+rolls it back. Full docs: `node_modules/vitest-prisma/README.md`, error reference:
+`node_modules/vitest-prisma/docs/errors.md`.
+
+## Set up
+
+1. Check requirements: `vitest >= 4.1`, Prisma `>= 6`, Node `>= 22.12`. Install with `-D vitest-prisma`.
+2. Find how the project builds its `PrismaClient` (adapter, output path such as
+   `src/generated/prisma/client`, `$extends`). If one module both creates and exports the shared
+   instance, split it into a factory module (`createClient()`) and an instance module
+   (`export const db = createClient()`). The setup file must import only the factory.
+3. Create the setup file and register it in `test.setupFiles`:
+
+   ```ts
+   // vitest.setup.ts
+   import { vi } from "vitest";
+   import { createVPrisma } from "vitest-prisma";
+   import { createClient } from "./src/client";
+
+   export const vPrisma = createVPrisma(createClient);
+   vi.mock("./src/db", () => ({ db: vPrisma.client })); // path of the shared-instance module
+   ```
+
+4. Make sure the test database has the schema (`prisma migrate deploy` or `prisma db push` in
+   `globalSetup` or CI). vitest-prisma does not migrate.
+5. SQLite: set `fileParallelism: false`.
+6. Verify: write one test that creates a row and one that expects the table to be empty, then run them.
+
+## Write tests
+
+- Use `vPrisma.client` (imported from the setup file) or the application's mocked client inside
+  `test` / `beforeEach` / `afterEach`. Do not clean up; everything is rolled back.
+- Never use `vPrisma.client` in `beforeAll` / `afterAll` or at module top level. Use
+  `vPrisma.originalClient` there, and clean up manually because those writes are not rolled back.
+- Do not use `test.concurrent` / `describe.concurrent` in files that use the database.
+- Asserting a DB error is fine: `await expect(createDuplicate()).rejects.toThrow()`, then keep querying.
+- Slow DB-heavy file that never expects query errors: `vPrisma.configure({ savepoints: false })`
+  at the top of that file (about 1.8× faster per query).
+- Debug the data a test leaves: add `vPrisma.configure({ rollback: false })` temporarily.
+
+## Diagnose failures
+
+Match the code in `[vitest-prisma:E_*]` and apply the fix from `docs/errors.md`:
+
+| Code | Usual fix |
+|---|---|
+| `E_OUTSIDE_TEST` | Move the access into `test`/`beforeEach`, use `originalClient` in `beforeAll`, or await a leaked promise. |
+| `E_CONCURRENT_TEST` | Remove `.concurrent` from the file. |
+| `E_UNSUPPORTED_ON_TEST_CLIENT` | Move `$extends`/`$on`/`$use` into the factory. |
+| `E_INVALID_CLIENT` | Make the factory return the client instance itself. |
+| `E_SAVEPOINT_FAILED` | SQL Server/MongoDB: `savepoints: false`. Otherwise read `error.cause`. |
+| `E_CONFIGURE_IN_TEST` | Move `vPrisma.configure()` to the top level of the file. |
+| `E_INVALID_TRANSACTION_ARGUMENT` | Pass a callback or an array of un-awaited queries. |
+
+Other symptoms:
+
+- `Cannot access 'vPrisma' before initialization`: the setup file imports the mocked module. Split
+  factory and instance (Set up, step 2).
+- Data leaks between tests: the code under test creates its own `PrismaClient` instead of using the
+  mocked shared module. Mock that module too, or refactor it to use the shared client.
+- `SQLITE_BUSY` / `database is locked`: set `fileParallelism: false`.
+- Deadlocks or lock waits between test files: parallel files insert the same unique values. Make
+  test data unique per file or test (for example, a random suffix).