pglite-test 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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

@@ -0,0 +1,158 @@
+# pglite-test
+
+A drop-in [`pgsql-test`](../pgsql-test) `getConnections()` backed by an in-process
+[**PGlite**](https://github.com/electric-sql/pglite) instance (WASM Postgres) —
+**no Postgres server, no `createdb`, no `psql`, no TCP.**
+
+It follows the same pattern as `drizzle-orm-test` / `supabase-test`: a thin
+`getConnections()` wrapper that composes the existing `pg-cache` / `pgsql-client`
+seams.
+
+- [`@pgpmjs/pglite-adapter`](../pglite-adapter)'s `registerPglite()` routes
+  `pg-cache`'s `getPgPool()` at PGlite, so `seed.pgpm()` deploys your module into
+  it with the unmodified pgpm engine.
+- `pgsql-client`'s client-factory seam routes `PgTestClient`'s underlying
+  `pg.Client` at the same PGlite session.
+
+## Usage
+
+```typescript
+import { getConnections, PgTestClient } from 'pglite-test';
+
+let pg: PgTestClient;
+let db: PgTestClient;
+let teardown: () => Promise<void>;
+
+beforeAll(async () => {
+  ({ pg, db, teardown } = await getConnections());
+});
+
+afterAll(async () => {
+  await teardown();
+});
+
+beforeEach(async () => {
+  await pg.beforeEach();
+  await db.beforeEach();
+});
+
+afterEach(async () => {
+  await db.afterEach();
+  await pg.afterEach();
+});
+
+it('queries the pgpm-deployed schema', async () => {
+  const { rows } = await db.query('SELECT count(*)::int AS n FROM app.users');
+  expect(rows[0].n).toBe(0);
+});
+```
+
+Jest must run with `NODE_OPTIONS=--experimental-vm-modules` (PGlite loads a WASM
+module); the package's `test` script sets this.
+
+## Single-session model
+
+PGlite is one in-process session, so `pg` and `db` share it. That differs from
+`pgsql-test` (two authenticated connections on a real server):
+
+- Transaction control is **ref-counted** (`SharedTxn`) so the standard
+  two-client `beforeEach`/`afterEach` harness emits exactly one
+  `BEGIN`/`SAVEPOINT`/`ROLLBACK`/`COMMIT` per test. The single-client (`db` only)
+  pattern also works.
+- Role-based RLS uses `setContext({ role })` (i.e. `SET LOCAL role`) on the shared
+  session rather than separate authenticated connections. Any role you switch to
+  must exist — create it via `pglite.extensionSql` (e.g.
+  `['CREATE ROLE authenticated;']`).
+- `publish()` (commit-and-continue) is not supported under the shared-session
+  coordinator.
+
+## Options
+
+```typescript
+await getConnections(
+  {
+    pglite: {
+      dataDir: undefined,          // in-memory by default
+      extensions: { vector },       // WASM extensions (e.g. pglite-pgvector)
+      extensionSql: [               // run once after ready
+        'CREATE EXTENSION IF NOT EXISTS vector;',
+        'CREATE ROLE authenticated;'
+      ]
+    }
+  },
+  [seed.pgpm()]                     // default seed adapter
+);
+```
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.js

@@ -0,0 +1,85 @@
+/**
+ * pglite-test
+ *
+ * A drop-in `getConnections()` — like `drizzle-orm-test` / `supabase-test` — that
+ * backs the pgsql-test client model with an in-process **PGlite** instance
+ * instead of a Postgres server. No `createdb`, no `psql`, no TCP: one WASM
+ * Postgres session per suite.
+ *
+ * It composes the existing seams rather than forking anything:
+ * - `@pgpmjs/pglite-adapter`'s `registerPglite()` routes `pg-cache`'s
+ *   `getPgPool()` at PGlite (so `seed.pgpm()` deploys into it), and
+ * - `pgsql-client`'s client-factory seam routes `PgTestClient`'s underlying
+ *   `pg.Client` at the same PGlite session.
+ *
+ * Because PGlite is a single session, `pg` and `db` share it; transaction
+ * control is ref-counted (see `SharedTxn`) so the standard
+ * `pg.beforeEach()/db.beforeEach()` + `db.afterEach()/pg.afterEach()` harness
+ * works unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { getConnections, PgTestClient } from 'pglite-test';
+ *
+ * let pg: PgTestClient, db: PgTestClient, teardown: () => Promise<void>;
+ * beforeAll(async () => { ({ pg, db, teardown } = await getConnections()); });
+ * afterAll(async () => { await teardown(); });
+ * beforeEach(async () => { await pg.beforeEach(); await db.beforeEach(); });
+ * afterEach(async () => { await db.afterEach(); await pg.afterEach(); });
+ * ```
+ */
+import { createPgliteClient, registerPglite } from '@pgpmjs/pglite-adapter';
+import { getPgEnvOptions } from 'pg-env';
+import { getActivePgClientFactory, registerPgClientFactory } from 'pgsql-client';
+import { seed } from 'pgsql-test';
+import { PgliteTestClient, SharedTxn } from './txn';
+/**
+ * Create an isolated PGlite-backed test environment and return `pg`/`db` clients
+ * plus a `teardown()`. Defaults to seeding via `seed.pgpm()` (deploys the pgpm
+ * module in `cwd`), matching pgsql-test.
+ */
+export const getConnections = async (cn = {}, seedAdapters = [seed.pgpm()]) => {
+    // Capture the previously-active client factory so teardown restores it
+    // (rather than clobbering to the default), mirroring how registerPglite
+    // restores the previous pool factory. Keeps nested/sequential suites clean.
+    const previousClientFactory = getActivePgClientFactory();
+    const handle = await registerPglite({
+        dataDir: cn.pglite?.dataDir,
+        extensions: cn.pglite?.extensions,
+        extensionSql: cn.pglite?.extensionSql,
+        instance: cn.pglite?.instance
+    });
+    // Route pgsql-client's PgClient at the same in-process PGlite session.
+    registerPgClientFactory(() => createPgliteClient(handle.db));
+    try {
+        const config = getPgEnvOptions({ database: 'postgres', ...cn.pg });
+        const txn = new SharedTxn();
+        const pg = new PgliteTestClient(config, {}, txn);
+        const db = new PgliteTestClient(config, { auth: cn.db?.auth, roles: cn.db?.roles }, txn);
+        // seed.pgpm deploys via getPgPool -> PGlite; sqlfile/json/csv/fn use ctx.pg.
+        if (seedAdapters.length) {
+            await seed.compose(seedAdapters).seed({
+                connect: cn.db ?? {},
+                admin: undefined, // unused by the PGlite-safe adapters
+                config,
+                pg
+            });
+        }
+        const teardown = async () => {
+            registerPgClientFactory(previousClientFactory);
+            await pg.close();
+            await db.close();
+            await handle.close();
+        };
+        return { pg, db, instance: handle.db, teardown };
+    }
+    catch (err) {
+        // Setup failed after registering the seams — unwind so a broken suite
+        // doesn't leak factories/instance into the next one.
+        registerPgClientFactory(previousClientFactory);
+        await handle.close();
+        throw err;
+    }
+};
+export { PgliteTestClient, SharedTxn } from './txn';
+export { PgTestClient, seed } from 'pgsql-test';

package/esm/txn.js

@@ -0,0 +1,61 @@
+import { PgTestClient } from 'pgsql-test';
+/**
+ * Coordinates transaction control across the `pg` and `db` clients when they
+ * share ONE PGlite session.
+ *
+ * On a real Postgres server `pg` and `db` are independent connections, each with
+ * its own transaction, so the standard harness opens a `BEGIN`+`SAVEPOINT` on
+ * both. PGlite is a single in-process session, so a second `BEGIN` is a no-op
+ * and a `ROLLBACK TO SAVEPOINT` after the other client's `COMMIT` errors.
+ *
+ * This coordinator ref-counts the shared depth so exactly one `BEGIN`, one
+ * outer `SAVEPOINT`, one `ROLLBACK TO SAVEPOINT` and one `COMMIT` run per test —
+ * regardless of whether the caller drives one client or both. It works for the
+ * common orderings:
+ *   beforeEach: pg.beforeEach(); db.beforeEach();
+ *   afterEach:  db.afterEach();  pg.afterEach();
+ * and for the single-client pattern (`db` only).
+ */
+export class SharedTxn {
+    depth = 0;
+    /** True only for the outermost `begin()` (the one that should emit BEGIN). */
+    beginNeeded() {
+        return this.depth++ === 0;
+    }
+    /** True only for the outermost `commit()` (the one that should emit COMMIT). */
+    commitNeeded() {
+        return --this.depth === 0;
+    }
+    /** True while exactly one transaction level is open (the outer savepoint scope). */
+    atOuter() {
+        return this.depth === 1;
+    }
+}
+/**
+ * `PgTestClient` whose transaction control is routed through a `SharedTxn`, so
+ * two clients over one PGlite session don't double-`BEGIN` or over-`COMMIT`.
+ * Everything else (query, setContext, auth, loadSql, ...) is inherited verbatim.
+ */
+export class PgliteTestClient extends PgTestClient {
+    txn;
+    constructor(config, opts, txn) {
+        super(config, opts);
+        this.txn = txn;
+    }
+    async begin() {
+        if (this.txn.beginNeeded())
+            await super.begin();
+    }
+    async savepoint(name) {
+        if (this.txn.atOuter())
+            await super.savepoint(name);
+    }
+    async rollback(name) {
+        if (this.txn.atOuter())
+            await super.rollback(name);
+    }
+    async commit() {
+        if (this.txn.commitNeeded())
+            await super.commit();
+    }
+}

package/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * pglite-test
+ *
+ * A drop-in `getConnections()` — like `drizzle-orm-test` / `supabase-test` — that
+ * backs the pgsql-test client model with an in-process **PGlite** instance
+ * instead of a Postgres server. No `createdb`, no `psql`, no TCP: one WASM
+ * Postgres session per suite.
+ *
+ * It composes the existing seams rather than forking anything:
+ * - `@pgpmjs/pglite-adapter`'s `registerPglite()` routes `pg-cache`'s
+ *   `getPgPool()` at PGlite (so `seed.pgpm()` deploys into it), and
+ * - `pgsql-client`'s client-factory seam routes `PgTestClient`'s underlying
+ *   `pg.Client` at the same PGlite session.
+ *
+ * Because PGlite is a single session, `pg` and `db` share it; transaction
+ * control is ref-counted (see `SharedTxn`) so the standard
+ * `pg.beforeEach()/db.beforeEach()` + `db.afterEach()/pg.afterEach()` harness
+ * works unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { getConnections, PgTestClient } from 'pglite-test';
+ *
+ * let pg: PgTestClient, db: PgTestClient, teardown: () => Promise<void>;
+ * beforeAll(async () => { ({ pg, db, teardown } = await getConnections()); });
+ * afterAll(async () => { await teardown(); });
+ * beforeEach(async () => { await pg.beforeEach(); await db.beforeEach(); });
+ * afterEach(async () => { await db.afterEach(); await pg.afterEach(); });
+ * ```
+ */
+import type { PGlite } from '@electric-sql/pglite';
+import { GetConnectionOpts, PgTestClient, SeedAdapter } from 'pgsql-test';
+export interface PgliteConnectionOpts extends GetConnectionOpts {
+    /** PGlite-specific knobs (in-memory by default). */
+    pglite?: {
+        /** Persist to a directory (default: in-memory). */
+        dataDir?: string;
+        /** WASM extensions registered at construction, e.g. `{ vector }`. */
+        extensions?: Record<string, any>;
+        /**
+         * SQL run once after the instance is ready — `CREATE EXTENSION ...`, and any
+         * `CREATE ROLE ...` needed for RLS role switching (PGlite starts as a single
+         * superuser, so roles used via `setContext({ role })` must be created here).
+         */
+        extensionSql?: string[];
+        /** Reuse an already-created PGlite instance instead of creating one. */
+        instance?: PGlite;
+    };
+}
+export interface PgliteConnectionResult {
+    /** Superuser-style client (bypasses RLS by not switching role). */
+    pg: PgTestClient;
+    /** Application client (role/context switched via `setContext`). */
+    db: PgTestClient;
+    /** The underlying PGlite instance, for direct access. */
+    instance: PGlite;
+    /** Unregister the seams and close the PGlite instance. */
+    teardown: () => Promise<void>;
+}
+/**
+ * Create an isolated PGlite-backed test environment and return `pg`/`db` clients
+ * plus a `teardown()`. Defaults to seeding via `seed.pgpm()` (deploys the pgpm
+ * module in `cwd`), matching pgsql-test.
+ */
+export declare const getConnections: (cn?: PgliteConnectionOpts, seedAdapters?: SeedAdapter[]) => Promise<PgliteConnectionResult>;
+export { PgliteTestClient, SharedTxn } from './txn';
+export type { GetConnectionOpts, SeedAdapter } from 'pgsql-test';
+export { PgTestClient, seed } from 'pgsql-test';

package/index.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * pglite-test
+ *
+ * A drop-in `getConnections()` — like `drizzle-orm-test` / `supabase-test` — that
+ * backs the pgsql-test client model with an in-process **PGlite** instance
+ * instead of a Postgres server. No `createdb`, no `psql`, no TCP: one WASM
+ * Postgres session per suite.
+ *
+ * It composes the existing seams rather than forking anything:
+ * - `@pgpmjs/pglite-adapter`'s `registerPglite()` routes `pg-cache`'s
+ *   `getPgPool()` at PGlite (so `seed.pgpm()` deploys into it), and
+ * - `pgsql-client`'s client-factory seam routes `PgTestClient`'s underlying
+ *   `pg.Client` at the same PGlite session.
+ *
+ * Because PGlite is a single session, `pg` and `db` share it; transaction
+ * control is ref-counted (see `SharedTxn`) so the standard
+ * `pg.beforeEach()/db.beforeEach()` + `db.afterEach()/pg.afterEach()` harness
+ * works unchanged.
+ *
+ * @example
+ * ```typescript
+ * import { getConnections, PgTestClient } from 'pglite-test';
+ *
+ * let pg: PgTestClient, db: PgTestClient, teardown: () => Promise<void>;
+ * beforeAll(async () => { ({ pg, db, teardown } = await getConnections()); });
+ * afterAll(async () => { await teardown(); });
+ * beforeEach(async () => { await pg.beforeEach(); await db.beforeEach(); });
+ * afterEach(async () => { await db.afterEach(); await pg.afterEach(); });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seed = exports.PgTestClient = exports.SharedTxn = exports.PgliteTestClient = exports.getConnections = void 0;
+const pglite_adapter_1 = require("@pgpmjs/pglite-adapter");
+const pg_env_1 = require("pg-env");
+const pgsql_client_1 = require("pgsql-client");
+const pgsql_test_1 = require("pgsql-test");
+const txn_1 = require("./txn");
+/**
+ * Create an isolated PGlite-backed test environment and return `pg`/`db` clients
+ * plus a `teardown()`. Defaults to seeding via `seed.pgpm()` (deploys the pgpm
+ * module in `cwd`), matching pgsql-test.
+ */
+const getConnections = async (cn = {}, seedAdapters = [pgsql_test_1.seed.pgpm()]) => {
+    // Capture the previously-active client factory so teardown restores it
+    // (rather than clobbering to the default), mirroring how registerPglite
+    // restores the previous pool factory. Keeps nested/sequential suites clean.
+    const previousClientFactory = (0, pgsql_client_1.getActivePgClientFactory)();
+    const handle = await (0, pglite_adapter_1.registerPglite)({
+        dataDir: cn.pglite?.dataDir,
+        extensions: cn.pglite?.extensions,
+        extensionSql: cn.pglite?.extensionSql,
+        instance: cn.pglite?.instance
+    });
+    // Route pgsql-client's PgClient at the same in-process PGlite session.
+    (0, pgsql_client_1.registerPgClientFactory)(() => (0, pglite_adapter_1.createPgliteClient)(handle.db));
+    try {
+        const config = (0, pg_env_1.getPgEnvOptions)({ database: 'postgres', ...cn.pg });
+        const txn = new txn_1.SharedTxn();
+        const pg = new txn_1.PgliteTestClient(config, {}, txn);
+        const db = new txn_1.PgliteTestClient(config, { auth: cn.db?.auth, roles: cn.db?.roles }, txn);
+        // seed.pgpm deploys via getPgPool -> PGlite; sqlfile/json/csv/fn use ctx.pg.
+        if (seedAdapters.length) {
+            await pgsql_test_1.seed.compose(seedAdapters).seed({
+                connect: cn.db ?? {},
+                admin: undefined, // unused by the PGlite-safe adapters
+                config,
+                pg
+            });
+        }
+        const teardown = async () => {
+            (0, pgsql_client_1.registerPgClientFactory)(previousClientFactory);
+            await pg.close();
+            await db.close();
+            await handle.close();
+        };
+        return { pg, db, instance: handle.db, teardown };
+    }
+    catch (err) {
+        // Setup failed after registering the seams — unwind so a broken suite
+        // doesn't leak factories/instance into the next one.
+        (0, pgsql_client_1.registerPgClientFactory)(previousClientFactory);
+        await handle.close();
+        throw err;
+    }
+};
+exports.getConnections = getConnections;
+var txn_2 = require("./txn");
+Object.defineProperty(exports, "PgliteTestClient", { enumerable: true, get: function () { return txn_2.PgliteTestClient; } });
+Object.defineProperty(exports, "SharedTxn", { enumerable: true, get: function () { return txn_2.SharedTxn; } });
+var pgsql_test_2 = require("pgsql-test");
+Object.defineProperty(exports, "PgTestClient", { enumerable: true, get: function () { return pgsql_test_2.PgTestClient; } });
+Object.defineProperty(exports, "seed", { enumerable: true, get: function () { return pgsql_test_2.seed; } });

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "pglite-test",
+  "version": "0.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Drop-in pgsql-test getConnections backed by an in-process PGlite instance — no Postgres server, instance-per-suite isolation",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "pglite",
+    "wasm",
+    "testing",
+    "integration-tests",
+    "database-testing",
+    "rls",
+    "pgsql-test",
+    "jest"
+  ],
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "0.5.4",
+    "@types/pg": "^8.20.0",
+    "makage": "^0.3.0"
+  },
+  "dependencies": {
+    "@pgpmjs/env": "^2.26.1",
+    "@pgpmjs/pglite-adapter": "^0.1.0",
+    "pg-cache": "^3.14.0",
+    "pg-env": "^1.17.0",
+    "pgsql-client": "^3.20.0",
+    "pgsql-test": "^4.18.3"
+  },
+  "peerDependencies": {
+    "@electric-sql/pglite": ">=0.5.0"
+  },
+  "gitHead": "7cbe15fac21a9345b169203ba9542ba9a50c866c"
+}

package/txn.d.ts

@@ -0,0 +1,41 @@
+import { PgConfig } from 'pg-env';
+import { PgTestClient, PgTestClientOpts } from 'pgsql-test';
+/**
+ * Coordinates transaction control across the `pg` and `db` clients when they
+ * share ONE PGlite session.
+ *
+ * On a real Postgres server `pg` and `db` are independent connections, each with
+ * its own transaction, so the standard harness opens a `BEGIN`+`SAVEPOINT` on
+ * both. PGlite is a single in-process session, so a second `BEGIN` is a no-op
+ * and a `ROLLBACK TO SAVEPOINT` after the other client's `COMMIT` errors.
+ *
+ * This coordinator ref-counts the shared depth so exactly one `BEGIN`, one
+ * outer `SAVEPOINT`, one `ROLLBACK TO SAVEPOINT` and one `COMMIT` run per test —
+ * regardless of whether the caller drives one client or both. It works for the
+ * common orderings:
+ *   beforeEach: pg.beforeEach(); db.beforeEach();
+ *   afterEach:  db.afterEach();  pg.afterEach();
+ * and for the single-client pattern (`db` only).
+ */
+export declare class SharedTxn {
+    private depth;
+    /** True only for the outermost `begin()` (the one that should emit BEGIN). */
+    beginNeeded(): boolean;
+    /** True only for the outermost `commit()` (the one that should emit COMMIT). */
+    commitNeeded(): boolean;
+    /** True while exactly one transaction level is open (the outer savepoint scope). */
+    atOuter(): boolean;
+}
+/**
+ * `PgTestClient` whose transaction control is routed through a `SharedTxn`, so
+ * two clients over one PGlite session don't double-`BEGIN` or over-`COMMIT`.
+ * Everything else (query, setContext, auth, loadSql, ...) is inherited verbatim.
+ */
+export declare class PgliteTestClient extends PgTestClient {
+    private txn;
+    constructor(config: PgConfig, opts: PgTestClientOpts, txn: SharedTxn);
+    begin(): Promise<void>;
+    savepoint(name?: string): Promise<void>;
+    rollback(name?: string): Promise<void>;
+    commit(): Promise<void>;
+}

package/txn.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PgliteTestClient = exports.SharedTxn = void 0;
+const pgsql_test_1 = require("pgsql-test");
+/**
+ * Coordinates transaction control across the `pg` and `db` clients when they
+ * share ONE PGlite session.
+ *
+ * On a real Postgres server `pg` and `db` are independent connections, each with
+ * its own transaction, so the standard harness opens a `BEGIN`+`SAVEPOINT` on
+ * both. PGlite is a single in-process session, so a second `BEGIN` is a no-op
+ * and a `ROLLBACK TO SAVEPOINT` after the other client's `COMMIT` errors.
+ *
+ * This coordinator ref-counts the shared depth so exactly one `BEGIN`, one
+ * outer `SAVEPOINT`, one `ROLLBACK TO SAVEPOINT` and one `COMMIT` run per test —
+ * regardless of whether the caller drives one client or both. It works for the
+ * common orderings:
+ *   beforeEach: pg.beforeEach(); db.beforeEach();
+ *   afterEach:  db.afterEach();  pg.afterEach();
+ * and for the single-client pattern (`db` only).
+ */
+class SharedTxn {
+    depth = 0;
+    /** True only for the outermost `begin()` (the one that should emit BEGIN). */
+    beginNeeded() {
+        return this.depth++ === 0;
+    }
+    /** True only for the outermost `commit()` (the one that should emit COMMIT). */
+    commitNeeded() {
+        return --this.depth === 0;
+    }
+    /** True while exactly one transaction level is open (the outer savepoint scope). */
+    atOuter() {
+        return this.depth === 1;
+    }
+}
+exports.SharedTxn = SharedTxn;
+/**
+ * `PgTestClient` whose transaction control is routed through a `SharedTxn`, so
+ * two clients over one PGlite session don't double-`BEGIN` or over-`COMMIT`.
+ * Everything else (query, setContext, auth, loadSql, ...) is inherited verbatim.
+ */
+class PgliteTestClient extends pgsql_test_1.PgTestClient {
+    txn;
+    constructor(config, opts, txn) {
+        super(config, opts);
+        this.txn = txn;
+    }
+    async begin() {
+        if (this.txn.beginNeeded())
+            await super.begin();
+    }
+    async savepoint(name) {
+        if (this.txn.atOuter())
+            await super.savepoint(name);
+    }
+    async rollback(name) {
+        if (this.txn.atOuter())
+            await super.rollback(name);
+    }
+    async commit() {
+        if (this.txn.commitNeeded())
+            await super.commit();
+    }
+}
+exports.PgliteTestClient = PgliteTestClient;