@bezoar/core 0.0.0-stage → 0.0.1

package/.dist/index.d.mts

@@ -0,0 +1,296 @@
+import { Arguments, Bundle, Definition, Issue, Query, Returns, Row, RowQuery, Schema } from "@bezoar/schema";
+/**
+ * The members of a service. A query group cannot take one of these names.
+ */
+export declare const RESERVED: readonly ["config", "schema", "query", "first", "transaction", "migrate", "seed"];
+/**
+ * The table that records each applied migration: its version, its name, its
+ * checksum, and when it was applied.
+ */
+export declare const TABLE = "bezoar_migrations";
+/**
+ * The key of the advisory lock a migration run holds. Two runs against one
+ * database wait for each other.
+ */
+export declare const LOCK = 6451064;
+/**
+ * Takes the advisory lock for the rest of the transaction.
+ */
+export declare const ACQUIRE = "SELECT pg_advisory_xact_lock($1)";
+/**
+ * Makes the tracking table when the database lacks it.
+ */
+export declare const CREATE = "CREATE TABLE IF NOT EXISTS bezoar_migrations (\n  version text PRIMARY KEY,\n  name text NOT NULL,\n  checksum text NOT NULL,\n  applied_at timestamptz NOT NULL DEFAULT now()\n)";
+/**
+ * Reads the version and the checksum of each applied migration.
+ */
+export declare const APPLIED = "SELECT version, checksum FROM bezoar_migrations ORDER BY version";
+/**
+ * Records one applied migration.
+ */
+export declare const RECORD = "INSERT INTO bezoar_migrations (version, name, checksum) VALUES ($1, $2, $3)";
+/**
+ * Raised at construction when the SQL bundle does not match the contract: a
+ * query without SQL, or SQL for a query the contract does not declare.
+ * Carries the schema's issues.
+ */
+export declare class InvalidBundleError extends Error {
+  readonly issues: Issue[];
+  constructor(issues: Issue[]);
+}
+/**
+ * Raised when the arguments of a call do not fit the slots of the query.
+ * Carries the query name and the schema's issues.
+ */
+export declare class InvalidArgumentsError extends Error {
+  readonly query: string;
+  readonly issues: Issue[];
+  constructor(query: string, issues: Issue[]);
+}
+/**
+ * Raised when a row the driver returned does not fit the columns of the
+ * query. Carries the query name, the index of the row, and the schema's
+ * issues.
+ */
+export declare class InvalidRowError extends Error {
+  readonly query: string;
+  readonly index: number;
+  readonly issues: Issue[];
+  constructor(query: string, index: number, issues: Issue[]);
+}
+/**
+ * Raised at construction when a query group takes the name of a member of
+ * the service, such as `migrate`.
+ */
+export declare class ReservedQueryError extends Error {
+  readonly query: string;
+  constructor(query: string);
+}
+/**
+ * Raised at construction when a name is both a query and a group, as
+ * `events` is when `events` and `events.list` are both queries.
+ */
+export declare class AmbiguousQueryError extends Error {
+  readonly query: string;
+  constructor(query: string);
+}
+/**
+ * Raised when the driver fails to run a query. Carries the query name and
+ * the driver's error as `cause`.
+ */
+export declare class QueryError extends Error {
+  readonly query: string;
+  constructor(query: string, cause: unknown);
+}
+/**
+ * Raised when a migration fails to apply. Carries the version and the
+ * driver's error as `cause`. The run rolls back. No migration of the run is
+ * kept.
+ */
+export declare class MigrationError extends Error {
+  readonly version: string;
+  constructor(version: string, cause: unknown);
+}
+/**
+ * Raised when the database holds a migration that the list does not match:
+ * the checksum changed, or the version is not in the list. The database and
+ * the build disagree.
+ */
+export declare class MigrationDriftError extends Error {
+  readonly version: string;
+  constructor(version: string, reason: string);
+}
+/**
+ * Raised when a seed fails to run. Carries the name and the driver's error
+ * as `cause`. The transaction rolls back.
+ */
+export declare class SeedError extends Error {
+  readonly seed: string;
+  constructor(seed: string, cause: unknown);
+}
+/**
+ * Runs a schema check and rethrows its {@link SchemaError} as the error that
+ * `frame` makes from the issues. Any other error propagates untouched.
+ *
+ * @param frame - Makes the core error from the issues.
+ * @param run - The check.
+ */
+export declare const reframe: <R>(frame: (issues: Issue[]) => Error, run: () => R) => R;
+/**
+ * What a driver answers a query with. `rows` is each row as an object, by
+ * column name, with the values parsed to the types the schema table
+ * declares. `count` is the number of rows the statement changed, or
+ * returned when it changed none.
+ */
+export interface Outcome {
+  readonly rows: readonly Record<string, unknown>[];
+  readonly count: number;
+}
+/**
+ * A connection to Postgres, as a driver package provides one. The service
+ * knows nothing of the driver beyond this.
+ *
+ * `query` runs one statement with positional parameters, through the
+ * extended protocol. `exec` runs text that can hold many statements and no
+ * parameters, through the simple protocol. A migration runs through `exec`.
+ * `transaction` runs a function with an executor bound to one transaction.
+ * The transaction commits when the function returns and rolls back when it
+ * throws.
+ */
+export interface Executor {
+  query(sql: string, params: readonly unknown[]): Promise<Outcome>;
+  exec(sql: string): Promise<void>;
+  transaction<T>(run: (executor: Executor) => Promise<T>): Promise<T>;
+}
+/**
+ * The caller-owned state a {@link Bezoar} service reads: the executor it
+ * runs on and the SQL of every query. The service reads the executor on each
+ * call. A caller can replace it.
+ */
+export type Config<D extends Definition> = {
+  /** The connection the service runs on. */
+  executor: Executor;
+  /** The SQL of each query, by name, as `@bezoar/kit` built it. */
+  queries: Bundle<D>;
+};
+/**
+ * What the service reports after a query runs: the name, the arguments, the
+ * time it took in milliseconds, and the count of the outcome.
+ */
+export interface Report<D extends Definition> {
+  readonly query: Query<D>;
+  readonly arguments: unknown;
+  readonly ms: number;
+  readonly count: number;
+}
+/**
+ * The runtime features of a service.
+ */
+export type Options<D extends Definition> = {
+  /**
+   * Called after each query runs, with its {@link Report}. A place for a log
+   * or a trace. A transaction shares the option with the service that
+   * opened it.
+   */
+  onQuery?: (report: Report<D>) => void;
+};
+/**
+ * One migration, as `@bezoar/kit` built it: a version that orders it, a
+ * name, its SQL, and a checksum of the SQL. The runner keeps the version
+ * and the checksum in the database, and refuses a migration whose checksum
+ * changed after it was applied.
+ */
+export interface Migration {
+  readonly version: string;
+  readonly name: string;
+  readonly sql: string;
+  readonly checksum: string;
+}
+/**
+ * One seed, as `@bezoar/kit` built it: a name and its SQL. A seed is not
+ * tracked. A seed must be safe to run again.
+ */
+export interface Seed {
+  readonly name: string;
+  readonly sql: string;
+}
+/**
+ * The arguments a query is called with: its arguments when it has a required
+ * slot, and optional arguments when every slot is nullable or there is none.
+ */
+export type Args<D extends Definition, Q extends Query<D>> = Record<never, never> extends Arguments<D, Q> ? [args?: Arguments<D, Q>] : [args: Arguments<D, Q>];
+/**
+ * The function of one query. The function takes the arguments of the query
+ * and returns its rows, or its count when it has no column. A query with a
+ * column also has `first`, which returns the first row or `null`.
+ */
+export type Method<D extends Definition, Q extends Query<D>> = ((...args: Args<D, Q>) => Promise<Returns<D, Q>>) & (Q extends RowQuery<D> ? {
+  readonly first: (...args: Args<D, Q>) => Promise<Row<D, Q> | null>;
+} : unknown);
+/**
+ * One level of the {@link Groups}: a function for every name that completes
+ * a query name, and the next level for every name that is a group. `K` is
+ * what is left of the names below the prefix `P`.
+ */
+type Tree<D extends Definition, K extends string, P extends string = ""> = { readonly [H in Exclude<K, `${string}.${string}`>]: Method<D, `${P}${H}` & Query<D>>; } & { readonly [H in K extends `${infer S}.${string}` ? S : never]: Tree<D, K extends `${H}.${infer R}` ? R : never, `${P}${H}.`>; };
+/**
+ * The queries of a contract as functions: `db.events.list({ day })`. A dot
+ * in a name is a level of the object. The query `events.list` is
+ * `db.events.list()`, and its first row is `db.events.list.first()`. The
+ * directory of a query file is its group and the file is its name.
+ */
+export type Groups<D extends Definition> = Tree<D, Query<D>>;
+/**
+ * The members of a service other than its queries. A query group cannot
+ * take one of these names.
+ */
+export interface Service<D extends Definition> {
+  /**
+   * The caller-owned state: the executor and the SQL bundle.
+   */
+  config: Config<D>;
+  /**
+   * The validation bundle for the contract.
+   */
+  schema: Schema<D>;
+  /**
+   * Runs a query by name. The same call as the function under its group.
+   * Returns the rows of a query with a column, and the count of the rows
+   * the statement changed for one without. Throws `InvalidArgumentsError`
+   * when the arguments do not fit the slots, `QueryError` when the driver
+   * fails, and `InvalidRowError` when a row does not fit the columns.
+   */
+  query: <Q extends Query<D>>(query: Q, ...args: Args<D, Q>) => Promise<Returns<D, Q>>;
+  /**
+   * Runs a query with a column by name and returns its first row, or `null`
+   * when it has none. The same call as `first` on the function under its
+   * group. Proves the row it returns and no other. Throws as `query` does.
+   */
+  first: <Q extends RowQuery<D>>(query: Q, ...args: Args<D, Q>) => Promise<Row<D, Q> | null>;
+  /**
+   * Runs a function inside one transaction. The function receives a service
+   * over the transaction, with the same queries and options. The transaction
+   * commits when the function returns and rolls back when it throws.
+   */
+  transaction: <T>(run: (tx: Bezoar<D>) => Promise<T>) => Promise<T>;
+  /**
+   * Applies the migrations the database lacks, in the order given, inside
+   * one transaction under an advisory lock. Returns the versions it applied.
+   * Throws `MigrationDriftError` when an applied migration has another
+   * checksum or is not in the list, and `MigrationError` when one fails.
+   */
+  migrate: (migrations: readonly Migration[]) => Promise<string[]>;
+  /**
+   * Runs the seeds, in the order given, inside one transaction. Throws
+   * `SeedError` when one fails.
+   */
+  seed: (seeds: readonly Seed[]) => Promise<void>;
+}
+/**
+ * A runtime database service over a contract. The service has its members
+ * and, beside them, a function for every query under its group. It never
+ * connects: the caller brings an executor from a driver package.
+ */
+export type Bezoar<D extends Definition> = Service<D> & Groups<D>;
+/**
+ * Builds the runtime {@link Bezoar} service over a contract.
+ *
+ * The service runs the queries of the contract by name, on the executor the
+ * container holds. A call proves its arguments against the slots of the
+ * query, binds them by position, runs the SQL of the bundle, proves each row
+ * against the columns, and returns the rows, or the count when the query
+ * has no column. `first` returns the first row instead. The service never
+ * connects: the caller brings an executor from a driver
+ * package, and a transaction is the same service over the executor of the
+ * transaction.
+ *
+ * @param definition - The contract: the kit's `contract` export.
+ * @param config - The caller-owned container: the executor and the bundle.
+ * @param options - The runtime features: a report after each query.
+ * @returns A {@link Bezoar} service bound to the container.
+ * @throws InvalidBundleError when the bundle does not match the contract.
+ * @throws ReservedQueryError when a query group takes a member's name.
+ * @throws AmbiguousQueryError when a name is both a query and a group.
+ */
+export declare const makeBezoar: <const D extends Definition>(definition: D, config: Config<D>, options?: Options<D>) => Bezoar<D>;
+export {};

package/.dist/index.mjs

@@ -0,0 +1,237 @@
+import { SchemaError, defineSchema } from "@bezoar/schema";
+import { keys, record, rekey } from "objectively";
+const RESERVED = [
+	"config",
+	"schema",
+	"query",
+	"first",
+	"transaction",
+	"migrate",
+	"seed"
+];
+const TABLE = "bezoar_migrations";
+const LOCK = 6451064;
+const ACQUIRE = "SELECT pg_advisory_xact_lock($1)";
+const CREATE = `CREATE TABLE IF NOT EXISTS ${TABLE} (
+  version text PRIMARY KEY,
+  name text NOT NULL,
+  checksum text NOT NULL,
+  applied_at timestamptz NOT NULL DEFAULT now()
+)`;
+const APPLIED = `SELECT version, checksum FROM ${TABLE} ORDER BY version`;
+const RECORD = `INSERT INTO ${TABLE} (version, name, checksum) VALUES ($1, $2, $3)`;
+const summarize = (issues) => issues.map((issue) => issue.path.length ? `${issue.path.map(String).join(".")}: ${issue.message}` : issue.message).join("\n");
+var InvalidBundleError = class extends Error {
+	issues;
+	constructor(issues) {
+		super(`@bezoar/core: the bundle is invalid —\n${summarize(issues)}`);
+		this.name = "InvalidBundleError";
+		this.issues = issues;
+	}
+};
+var InvalidArgumentsError = class extends Error {
+	query;
+	issues;
+	constructor(query, issues) {
+		super(`@bezoar/core: the arguments of ${JSON.stringify(query)} are invalid —\n${summarize(issues)}`);
+		this.name = "InvalidArgumentsError";
+		this.query = query;
+		this.issues = issues;
+	}
+};
+var InvalidRowError = class extends Error {
+	query;
+	index;
+	issues;
+	constructor(query, index, issues) {
+		super(`@bezoar/core: row ${index} of ${JSON.stringify(query)} is invalid —\n${summarize(issues)}`);
+		this.name = "InvalidRowError";
+		this.query = query;
+		this.index = index;
+		this.issues = issues;
+	}
+};
+var ReservedQueryError = class extends Error {
+	query;
+	constructor(query) {
+		super(`@bezoar/core: ${JSON.stringify(query)} is reserved by the service`);
+		this.name = "ReservedQueryError";
+		this.query = query;
+	}
+};
+var AmbiguousQueryError = class extends Error {
+	query;
+	constructor(query) {
+		super(`@bezoar/core: ${JSON.stringify(query)} is both a query and a group`);
+		this.name = "AmbiguousQueryError";
+		this.query = query;
+	}
+};
+var QueryError = class extends Error {
+	query;
+	constructor(query, cause) {
+		super(`@bezoar/core: ${JSON.stringify(query)} failed`, { cause });
+		this.name = "QueryError";
+		this.query = query;
+	}
+};
+var MigrationError = class extends Error {
+	version;
+	constructor(version, cause) {
+		super(`@bezoar/core: migration ${version} failed`, { cause });
+		this.name = "MigrationError";
+		this.version = version;
+	}
+};
+var MigrationDriftError = class extends Error {
+	version;
+	constructor(version, reason) {
+		super(`@bezoar/core: migration ${version} ${reason}`);
+		this.name = "MigrationDriftError";
+		this.version = version;
+	}
+};
+var SeedError = class extends Error {
+	seed;
+	constructor(seed, cause) {
+		super(`@bezoar/core: seed ${JSON.stringify(seed)} failed`, { cause });
+		this.name = "SeedError";
+		this.seed = seed;
+	}
+};
+const reframe = (frame, run) => {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof SchemaError) throw frame(error.issues);
+		throw error;
+	}
+};
+const descend = (level, segment, name) => {
+	const next = level[segment] ?? {};
+	if (!record(next)) throw new AmbiguousQueryError(name);
+	level[segment] = next;
+	return next;
+};
+const place = (level, segment, name, fn) => {
+	if (segment in level) throw new AmbiguousQueryError(name);
+	level[segment] = fn;
+};
+const defineGroups = (names, reserved, method) => {
+	const root = {};
+	for (const name of names) {
+		const segments = name.split(".");
+		const last = segments.pop();
+		if (reserved.has(segments[0] ?? last)) throw new ReservedQueryError(name);
+		let level = root;
+		for (const segment of segments) level = descend(level, segment, name);
+		place(level, last, name, method(name));
+	}
+	return rekey(root, (key, value) => [key, value]);
+};
+const applied = async (tx) => {
+	const { rows } = await tx.query(APPLIED, []);
+	const found = /* @__PURE__ */ new Map();
+	for (const row of rows) found.set(String(row.version), String(row.checksum));
+	return found;
+};
+const compare = (checksums, migrations) => {
+	const listed = new Set(migrations.map((migration) => migration.version));
+	for (const version of checksums.keys()) if (!listed.has(version)) throw new MigrationDriftError(version, "is applied but not listed");
+	for (const migration of migrations) {
+		const checksum = checksums.get(migration.version);
+		if (checksum !== void 0 && checksum !== migration.checksum) throw new MigrationDriftError(migration.version, "changed after it was applied");
+	}
+};
+const apply = async (tx, migration) => {
+	try {
+		await tx.exec(migration.sql);
+	} catch (cause) {
+		throw new MigrationError(migration.version, cause);
+	}
+	await tx.query(RECORD, [
+		migration.version,
+		migration.name,
+		migration.checksum
+	]);
+};
+const migrate = (executor, migrations) => executor.transaction(async (tx) => {
+	await tx.query(ACQUIRE, [LOCK]);
+	await tx.exec(CREATE);
+	const checksums = await applied(tx);
+	compare(checksums, migrations);
+	const done = [];
+	for (const migration of migrations) if (!checksums.has(migration.version)) {
+		await apply(tx, migration);
+		done.push(migration.version);
+	}
+	return done;
+});
+const seed = (executor, seeds) => executor.transaction(async (tx) => {
+	for (const entry of seeds) try {
+		await tx.exec(entry.sql);
+	} catch (cause) {
+		throw new SeedError(entry.name, cause);
+	}
+});
+const bind = (slots, given) => slots.map((slot) => given[slot.name] ?? null);
+const defineService = (definition, schema, config, options) => {
+	const execute = async (query, params) => {
+		try {
+			return await config.executor.query(config.queries[query], params);
+		} catch (cause) {
+			throw new QueryError(query, cause);
+		}
+	};
+	const prove = (query, index, row) => reframe((issues) => new InvalidRowError(query, index, issues), () => schema.assert.row(query, row));
+	const perform = async (query, args) => {
+		const statement = definition.queries[query];
+		const given = reframe((issues) => new InvalidArgumentsError(query, issues), () => schema.parse.arguments(query, args));
+		const started = performance.now();
+		const outcome = await execute(query, bind(statement.slots, given));
+		options.onQuery?.({
+			query,
+			arguments: args,
+			ms: performance.now() - started,
+			count: outcome.count
+		});
+		return outcome;
+	};
+	const returnsRows = (query) => definition.queries[query].columns.length > 0;
+	async function run(query, args = {}) {
+		const outcome = await perform(query, args);
+		if (!returnsRows(query)) return outcome.count;
+		for (const [index, row] of outcome.rows.entries()) prove(query, index, row);
+		return outcome.rows;
+	}
+	async function take(query, args = {}) {
+		const row = (await perform(query, args)).rows[0];
+		if (row === void 0) return null;
+		prove(query, 0, row);
+		return row;
+	}
+	const transaction = (fn) => config.executor.transaction((executor) => fn(defineService(definition, schema, {
+		...config,
+		executor
+	}, options)));
+	const service = {
+		config,
+		schema,
+		query: run,
+		first: take,
+		transaction,
+		migrate: (migrations) => migrate(config.executor, migrations),
+		seed: (seeds) => seed(config.executor, seeds)
+	};
+	const groups = defineGroups(keys(definition.queries), new Set(RESERVED), (query) => {
+		const method = (args) => run(query, args);
+		return returnsRows(query) ? Object.assign(method, { first: (args) => take(query, args) }) : method;
+	});
+	return Object.assign(service, groups);
+};
+const makeBezoar = (definition, config, options = {}) => {
+	const schema = defineSchema(definition);
+	reframe((issues) => new InvalidBundleError(issues), () => schema.assert.bundle(config.queries));
+	return defineService(definition, schema, config, options);
+};
+export { ACQUIRE, APPLIED, AmbiguousQueryError, CREATE, InvalidArgumentsError, InvalidBundleError, InvalidRowError, LOCK, MigrationDriftError, MigrationError, QueryError, RECORD, RESERVED, ReservedQueryError, SeedError, TABLE, makeBezoar, reframe };

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,162 @@
-# Temporary Holding Version
+# @bezoar/core
 
-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.
+The runtime service of bezoar. The service runs the queries of a contract
+by name, proves the arguments and the rows against the contract, and applies
+migrations and seeds.
+
+[`@bezoar/schema`](../schema) has the contract types and the validation.
+A driver package provides the connection.
+
+## Install
+
+```sh
+pnpm add @bezoar/core
+```
+
+## Usage
+
+`bezoar build` writes the contract to `.output/index.mjs` and the SQL to
+`.output/queries.mjs`. `makeBezoar` makes the service from the contract
+and a container with an executor and the SQL.
+
+```ts
+import { makeBezoar } from "@bezoar/core";
+import { pglite } from "@bezoar/pglite";
+import { contract } from "@bbf/database";
+import { queries } from "@bbf/database/queries";
+
+const db = makeBezoar(contract, { executor: pglite(client), queries });
+
+const events = await db.events.list({ day: "sunday" });
+const found = await db.events.bySlug.first({ slug: "worship-service" });
+const inserted = await db.events.insert({ slug: "prayer", title: "Prayer" });
+```
+
+The directory of a query file is its group and the file is its name, so
+`events/list.sql` is `db.events.list()`. `db.query("events.list", args)` is
+the same call by name. The arguments complete to the slots of the query. A
+required slot is required. A nullable slot is optional and takes `null`.
+
+A query with a column returns its rows. A query with no column, a write
+without `RETURNING`, returns the count of the rows the statement changed.
+A query with a column also has `first`, which returns the first row or
+`null` when there is none: `db.events.bySlug.first({ slug })`, or
+`db.first("events.bySlug", { slug })` by name. A query with no column has
+no `first`.
+
+## The container
+
+The container holds the executor and the SQL bundle. The service reads the
+executor on each call, so a caller can replace it. The service never
+connects. The caller brings an executor from a driver package.
+
+```ts
+interface Executor {
+  query(sql: string, params: readonly unknown[]): Promise<Outcome>;
+  exec(sql: string): Promise<void>;
+  transaction<T>(run: (executor: Executor) => Promise<T>): Promise<T>;
+}
+```
+
+`query` runs one statement with positional parameters. `exec` runs text
+that can hold many statements and no parameters, which is how a migration
+runs. `transaction` runs a function on one transaction and commits or rolls
+back by whether the function returns or throws. The rows of an outcome are
+objects by column name, with the values parsed to the types the schema table
+declares.
+
+## A call
+
+A call proves its arguments against the slots of the query before anything
+runs, and throws `InvalidArgumentsError` with every issue. The service binds
+the arguments by slot position and runs the SQL of the bundle. A driver
+failure is a `QueryError` that names the query and carries the driver's
+error as `cause`. For `one` and `many`, each row is proven against the
+columns, and a row that does not fit is an `InvalidRowError` with its index.
+
+The `onQuery` option receives a report after each call: the query name, the
+arguments, the time in milliseconds, and the count of the outcome.
+
+```ts
+const db = makeBezoar(contract, config, {
+  onQuery: ({ query, ms }) => console.log(`${query} ${ms.toFixed(1)}ms`),
+});
+```
+
+## Transactions
+
+`transaction` runs a function with a service over one transaction. The
+service has the same queries and options.
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.events.insert({ slug: "prayer", title: "Prayer Meeting" });
+  await tx.events.archive({ ids: [3, 4] });
+});
+```
+
+The transaction commits when the function returns and rolls back when it
+throws. Whether a transaction inside a transaction opens a savepoint is up
+to the driver.
+
+## Migrations and seeds
+
+`migrate` applies the migrations the database lacks. The kit builds the
+list: each entry has a version, a name, its SQL, and a checksum.
+
+```ts
+import { migrations } from "@bbf/database/migrations";
+import { seeds } from "@bbf/database/seeds";
+
+const applied = await db.migrate(migrations); // the versions it applied
+await db.seed(seeds);
+```
+
+The run is one transaction under an advisory lock. The lock makes two runs
+wait for each other, so a rolling deploy applies each migration once. The
+transaction makes the run all or nothing. The runner keeps each applied
+version and its checksum in `bezoar_migrations`.
+
+Before it applies anything, the runner compares the list with the database.
+An applied version with another checksum, or an applied version that is not
+in the list, is a `MigrationDriftError`: the database and the build
+disagree, and the runner does not guess. A migration that fails is a
+`MigrationError` with its version, and the run rolls back.
+
+`seed` runs the seeds in order inside one transaction. Seeds are not
+tracked. Write a seed so that it can run again. A seed that fails is a
+`SeedError`, and the run rolls back.
+
+## Names
+
+The members of the service are `config`, `schema`, `query`, `transaction`,
+`migrate`, and `seed`. A query group cannot take one of these names, and a
+name cannot be both a query and a group. Either is an error at
+construction: `ReservedQueryError` or `AmbiguousQueryError`.
+
+## Errors
+
+- `InvalidBundleError`: the SQL bundle does not match the contract.
+- `InvalidArgumentsError`: the arguments of a call do not fit the slots.
+- `InvalidRowError`: a row does not fit the columns.
+- `QueryError`: the driver failed. `cause` is the driver's error.
+- `MigrationDriftError`: the database holds a migration the list does not
+  match.
+- `MigrationError`, `SeedError`: a migration or a seed failed. `cause` is
+  the driver's error.
+- `ReservedQueryError`, `AmbiguousQueryError`: a query name the service
+  cannot place.
+
+## Types
+
+- `Bezoar<D>` is the service: `Service<D>` and the `Groups<D>`.
+- `Config<D>` is the container. `Options<D>` has `onQuery`.
+- `Executor` and `Outcome` are what a driver provides.
+- `Method<D, Q>` is the function of one query. `Report<D>` is what `onQuery`
+  receives.
+- `Migration` and `Seed` are what the kit builds for the runner.
+
+## Related
+
+- [`@bezoar/schema`](../schema): the contract types and the validation.
+- `@bezoar/pglite`: an executor over PGlite.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@bezoar/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "The bezoar runtime service: run queries by name, migrate, seed",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/bezoar.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.mts",
+      "import": "./.dist/index.mjs"
+    }
+  },
+  "files": [
+    ".dist"
+  ],
+  "dependencies": {
+    "objectively": "^0.3.0",
+    "@bezoar/schema": "0.0.1"
+  },
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }