pglite-test 0.1.0 → 0.1.1

package/README.md

@@ -1,18 +1,52 @@
 # 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.**
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+  <a href="https://www.npmjs.com/package/pglite-test">
+    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=postgres%2Fpglite-test%2Fpackage.json"/>
+  </a>
+</p>
+
+`pglite-test` is a [**PGlite**](https://github.com/electric-sql/pglite)-optimized version of [`pgsql-test`](https://www.npmjs.com/package/pgsql-test) that runs entirely **in-process** — no Postgres server, no `createdb`, no `psql`, no TCP. It provides instant, isolated PostgreSQL databases for testing with automatic transaction rollbacks, context switching, and clean seeding, all backed by ElectricSQL's WASM build of Postgres. It's ideal for local-first development and especially great for GitHub Actions and CI/CD — **no service container required**.
+
+Like [`supabase-test`](https://www.npmjs.com/package/supabase-test) and [`drizzle-orm-test`](https://www.npmjs.com/package/drizzle-orm-test), it's a thin `getConnections()` wrapper that composes the existing `pg-cache` / `pgsql-client` seams, so your tests read exactly like `pgsql-test`.
+
+## Install
+
+```sh
+npm install pglite-test
+```
+
+You also install PGlite yourself (it's a peer dependency, so you pin the version):
+
+```sh
+npm install @electric-sql/pglite
+```
+
+## Features
 
-It follows the same pattern as `drizzle-orm-test` / `supabase-test`: a thin
-`getConnections()` wrapper that composes the existing `pg-cache` / `pgsql-client`
-seams.
+* 🚀 **Zero infrastructure** — pure WASM, no Postgres server, no Docker, no service container in CI
+* ⚡ **Instant test DBs** — spin up an isolated in-process instance per suite
+* 🔄 **Per-test rollback** — every test runs in its own transaction/savepoint (ref-counted for the single session)
+* 🛡️ **RLS-friendly** — role-based auth via `.setContext()` (full GUC support)
+* 🌱 **pgpm-native seeding** — deploy your real modules with the unmodified pgpm engine via `seed.pgpm()`
+* 🧠 **pgvector & friends** — register WASM extensions (`vector`, `pg_trgm`, …) at construction
+* 🧪 **Compatible with any async runner** — works with `Jest`, `Mocha`, etc.
+* 🧹 **Auto teardown** — no residue, no reboots, just clean exits
 
-- [`@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.
+## How it works
+
+- [`@pgpmjs/pglite-adapter`](https://www.npmjs.com/package/@pgpmjs/pglite-adapter)'s `registerPglite()` routes `pg-cache`'s `getPgPool()` at an in-process PGlite instance, 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
 
@@ -47,32 +81,17 @@ it('queries the pgpm-deployed schema', async () => {
 });
 ```
 
-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.
+Jest must run with `NODE_OPTIONS=--experimental-vm-modules` (PGlite loads a WASM module); the package's `test` script sets this.
 
 ## Options
 
 ```typescript
+import { vector } from '@electric-sql/pglite-pgvector';
+
 await getConnections(
   {
     pglite: {
-      dataDir: undefined,          // in-memory by default
+      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;',
@@ -84,6 +103,20 @@ await getConnections(
 );
 ```
 
+## 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.
+
+## Related
+
+- [`@pgpmjs/pglite-adapter`](https://www.npmjs.com/package/@pgpmjs/pglite-adapter) — the in-process PGlite driver that both this package and the pgpm engine ride on.
+- [`pgsql-test`](https://www.npmjs.com/package/pgsql-test) — the server-backed original this mirrors.
+- [`supabase-test`](https://www.npmjs.com/package/supabase-test) · [`drizzle-orm-test`](https://www.npmjs.com/package/drizzle-orm-test) — sibling `getConnections()` wrappers.
+
 ---
 
 ## Education and Tutorials

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pglite-test",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -46,15 +46,15 @@
     "makage": "^0.3.0"
   },
   "dependencies": {
-    "@pgpmjs/env": "^2.26.1",
-    "@pgpmjs/pglite-adapter": "^0.1.0",
-    "pg-cache": "^3.14.0",
+    "@pgpmjs/env": "^2.26.2",
+    "@pgpmjs/pglite-adapter": "^0.1.1",
+    "pg-cache": "^3.14.1",
     "pg-env": "^1.17.0",
-    "pgsql-client": "^3.20.0",
-    "pgsql-test": "^4.18.3"
+    "pgsql-client": "^3.20.1",
+    "pgsql-test": "^4.18.4"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"
   },
-  "gitHead": "7cbe15fac21a9345b169203ba9542ba9a50c866c"
+  "gitHead": "87e65cd31d4e23c367ca4d398416b19ac863c7de"
 }