@bezoar/pglite 0.0.0-stage → 0.0.0

package/.dist/index.d.mts

@@ -0,0 +1,55 @@
+import { PGliteInterface, PGliteOptions, ParserOptions, Transaction } from "@electric-sql/pglite";
+import { Executor } from "@bezoar/core";
+/**
+ * The parsers that make a row match the type table of `@bezoar/schema`.
+ * PGlite parses `date` and `timestamp` to a `Date`. The table declares them
+ * as strings in the form Postgres writes, so these parsers keep the text.
+ * Every other type parses as PGlite parses it.
+ */
+export declare const PARSERS: ParserOptions;
+/**
+ * The prefix of the savepoint a transaction inside a transaction opens. The
+ * depth of the transaction follows it.
+ */
+export declare const SAVEPOINT = "bezoar_";
+/**
+ * What `pglite` takes: nothing for a database in memory, a path for a
+ * database on a data directory, PGlite options, or a client the caller made.
+ */
+export type Source = string | PGliteOptions | PGliteInterface;
+/**
+ * An {@link Executor} over PGlite. `client` is the PGlite instance, for a
+ * caller that needs more of it than the executor exposes. `close` closes the
+ * instance.
+ */
+export interface PGliteExecutor extends Executor {
+  readonly client: PGliteInterface;
+  close(): Promise<void>;
+}
+/**
+ * A connection the executor runs on: the client, or a transaction of it.
+ */
+export type Connection = PGliteInterface | Transaction;
+/**
+ * The state the executors over one client share. `changed` is `true` after
+ * an `exec` ran and before the client refreshed its array types.
+ */
+export interface Session {
+  readonly client: PGliteInterface;
+  changed: boolean;
+}
+/**
+ * Builds a bezoar `Executor` over PGlite.
+ *
+ * `query` runs one statement with positional parameters. The rows match the
+ * type table of `@bezoar/schema`. `exec` runs text that can hold many
+ * statements, and then refreshes the array types of the client, so an array
+ * of a type a migration created parses as an array. `transaction` runs a
+ * function inside a transaction of the client. A transaction inside a
+ * transaction is a savepoint.
+ *
+ * @param source - Nothing for a database in memory, a path to a data
+ *   directory, PGlite options, or a client. A client the caller made stays
+ *   the caller's to close.
+ */
+export declare const pglite: (source?: Source) => PGliteExecutor;

package/.dist/index.mjs

@@ -0,0 +1,69 @@
+import { PGlite, types } from "@electric-sql/pglite";
+const PARSERS = {
+	[types.DATE]: (text) => text,
+	[types.TIMESTAMP]: (text) => text
+};
+const SAVEPOINT = "bezoar_";
+const outcome = (results) => ({
+	rows: results.rows,
+	count: results.affectedRows || results.rows.length
+});
+const refresh = async (session) => {
+	if (session.changed) {
+		session.changed = false;
+		await session.client.refreshArrayTypes();
+	}
+};
+const savepoint = async (tx, depth, run) => {
+	const name = `${SAVEPOINT}${depth}`;
+	await tx.query(`SAVEPOINT ${name}`);
+	try {
+		const result = await run();
+		await tx.query(`RELEASE SAVEPOINT ${name}`);
+		return result;
+	} catch (error) {
+		await tx.query(`ROLLBACK TO SAVEPOINT ${name}`);
+		throw error;
+	}
+};
+const defineExecutor = (session, connection, depth) => {
+	const query = async (sql, params) => outcome(await connection.query(sql, [...params], { parsers: PARSERS }));
+	const exec = async (sql) => {
+		await connection.exec(sql);
+		session.changed = true;
+		if (depth === 0) await refresh(session);
+	};
+	const transaction = async (run) => {
+		if ("transaction" in connection) {
+			const result = await connection.transaction((tx) => run(defineExecutor(session, tx, depth + 1)));
+			await refresh(session);
+			return result;
+		}
+		return savepoint(connection, depth, () => run(defineExecutor(session, connection, depth + 1)));
+	};
+	return {
+		query,
+		exec,
+		transaction
+	};
+};
+const pglite = (source = {}) => {
+	let client;
+	if (typeof source === "string") client = new PGlite(source);
+	else if ("query" in source) client = source;
+	else client = new PGlite(source);
+	const executor = defineExecutor({
+		client,
+		changed: false
+	}, client, 0);
+	const close = async () => {
+		await client.waitReady;
+		await client.close();
+	};
+	return {
+		...executor,
+		client,
+		close
+	};
+};
+export { PARSERS, SAVEPOINT, pglite };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Thorwaldson
+
+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,3 +1,69 @@
-# Temporary Holding Version
+# @bezoar/pglite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A bezoar executor over [PGlite](https://pglite.dev), the Postgres that
+runs in-process. `@bezoar/kit` builds on it. `@bezoar/testing` tests
+on it. An app can develop on it with no server.
+
+## Install
+
+```sh
+pnpm add @bezoar/pglite
+```
+
+The package carries PGlite.
+
+## Usage
+
+```ts
+import { makeBezoar } from "@bezoar/core";
+import { pglite } from "@bezoar/pglite";
+import { contract } from "@bbf/database";
+import { queries } from "@bbf/database/queries";
+import { migrations } from "@bbf/database/migrations";
+
+const executor = pglite();
+const db = makeBezoar(contract, { executor, queries });
+
+await db.migrate(migrations);
+const events = await db.events.list({ day: "sunday" });
+
+await executor.close();
+```
+
+`pglite()` makes a database in memory. `pglite("./data")` makes one on a
+data directory. `pglite(options)` passes PGlite options through. The executor
+exposes the instance as `client` and closes it with `close()`.
+
+`pglite(client)` wraps a PGlite instance the caller made. The caller closes
+it.
+
+## Types
+
+The rows of a query match the type table of `@bezoar/schema`. PGlite
+parses most types the same way. The executor sets two parsers of its own:
+`date` and `timestamp` stay strings in the form Postgres writes, where PGlite
+would make a `Date` of them.
+
+An `int8` in the safe integer range is a `number`. One outside the range is
+a `bigint`, which the row validator of the service rejects.
+
+## Array types
+
+PGlite reads the array types of the database when it starts. A type that a
+migration creates has an array type PGlite does not know until it reads them
+again. The executor refreshes them after each `exec`, and after each
+transaction that ran one, so a column such as `event_day[]` parses as an
+array as soon as `migrate` returns.
+
+## Transactions
+
+`transaction` runs a function inside a transaction of the client. A
+transaction inside a transaction is a savepoint: it is released when the
+function returns and rolled back to when it throws, and the outer transaction
+goes on.
+
+## Related
+
+- [`@bezoar/core`](../core): the service that runs on an executor.
+- `@bezoar/pg`: the executor over node-postgres, for a database with a
+  server.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@bezoar/pglite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "A bezoar executor over PGlite",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/bezoar.git",
+    "directory": "packages/pglite"
+  },
+  "type": "module",
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.mts",
+      "import": "./.dist/index.mjs"
+    }
+  },
+  "files": [
+    ".dist"
+  ],
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bezoar/core": "workspace:*",
+    "@bezoar/schema": "workspace:*",
+    "@electric-sql/pglite": "catalog:"
+  }
+}