@fuzdev/fuz_app 0.1.0

package/dist/crypto.js

@@ -0,0 +1,19 @@
+/**
+ * Shared cryptographic utilities.
+ *
+ * @module
+ */
+/**
+ * Generate a cryptographically random base64url string.
+ *
+ * @param byte_length - number of random bytes (default 32 = 256 bits)
+ * @returns base64url-encoded string without padding
+ */
+export const generate_random_base64url = (byte_length = 32) => {
+    const bytes = new Uint8Array(byte_length);
+    crypto.getRandomValues(bytes);
+    return btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+};

package/dist/db/assert_row.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Assertion helper for INSERT RETURNING results.
+ *
+ * @module
+ */
+/**
+ * Assert that a row is present, throwing a descriptive error if missing.
+ *
+ * Use after `INSERT ... RETURNING` queries where the database guarantees
+ * a row is returned on success. Replaces bare `row!` non-null assertions
+ * with an explicit runtime check.
+ *
+ * @param row - the row from `query_one` (`T | undefined`) or `rows[0]` (`T | undefined`)
+ * @param context - optional context for the error message (e.g. table or operation name)
+ * @returns the row, guaranteed non-undefined
+ */
+export declare const assert_row: <T>(row: T | undefined, context?: string) => T;
+//# sourceMappingURL=assert_row.d.ts.map

package/dist/db/assert_row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert_row.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/assert_row.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,KAAK,CAAC,GAAG,SAAS,EAAE,UAAU,MAAM,KAAG,CASpE,CAAC"}

package/dist/db/assert_row.js

@@ -0,0 +1,24 @@
+/**
+ * Assertion helper for INSERT RETURNING results.
+ *
+ * @module
+ */
+/**
+ * Assert that a row is present, throwing a descriptive error if missing.
+ *
+ * Use after `INSERT ... RETURNING` queries where the database guarantees
+ * a row is returned on success. Replaces bare `row!` non-null assertions
+ * with an explicit runtime check.
+ *
+ * @param row - the row from `query_one` (`T | undefined`) or `rows[0]` (`T | undefined`)
+ * @param context - optional context for the error message (e.g. table or operation name)
+ * @returns the row, guaranteed non-undefined
+ */
+export const assert_row = (row, context) => {
+    if (row === undefined) {
+        throw new Error(context
+            ? `Expected row from ${context}, but got undefined`
+            : 'Expected INSERT RETURNING to produce a row, but got undefined');
+    }
+    return row;
+};

package/dist/db/create_db.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Database initialization with driver auto-detection.
+ *
+ * Selects the appropriate database driver based on `database_url`:
+ * - `postgres://` or `postgresql://` — uses `pg` (PostgreSQL)
+ * - `file://` — uses `@electric-sql/pglite` (file-based)
+ * - `memory://` — uses `@electric-sql/pglite` (in-memory)
+ *
+ * Both `pg` and `@electric-sql/pglite` are optional peer dependencies,
+ * dynamically imported only when needed. For direct driver construction
+ * without auto-detection, use `db_pg.ts` or `db_pglite.ts`.
+ *
+ * @module
+ */
+import type { Db, DbType } from './db.js';
+/** Result of database initialization. */
+export interface CreateDbResult {
+    db: Db;
+    /** Close the database connection. Bound to the actual driver at construction. */
+    close: () => Promise<void>;
+    db_type: DbType;
+    db_name: string;
+}
+/**
+ * Create a database connection based on a URL.
+ *
+ * Returns the `Db` instance, a typed `close` callback, driver type, and display name.
+ * The `close` callback is bound to the actual driver — callers never need to
+ * know which driver is in use.
+ *
+ * For direct driver construction without URL routing, import
+ * `create_pg_db` from `db_pg.ts` or `create_pglite_db` from `db_pglite.ts`.
+ *
+ * @param database_url - connection URL (`postgres://`, `postgresql://`, `file://`, or `memory://`)
+ * @returns database instance, close callback, type, and display name
+ */
+export declare const create_db: (database_url: string) => Promise<CreateDbResult>;
+//# sourceMappingURL=create_db.d.ts.map

package/dist/db/create_db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/create_db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAE,MAAM,EAAC,MAAM,SAAS,CAAC;AAIxC,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,EAAE,CAAC;IACP,iFAAiF;IACjF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,cAAc,CAgC5E,CAAC"}

package/dist/db/create_db.js

@@ -0,0 +1,57 @@
+/**
+ * Database initialization with driver auto-detection.
+ *
+ * Selects the appropriate database driver based on `database_url`:
+ * - `postgres://` or `postgresql://` — uses `pg` (PostgreSQL)
+ * - `file://` — uses `@electric-sql/pglite` (file-based)
+ * - `memory://` — uses `@electric-sql/pglite` (in-memory)
+ *
+ * Both `pg` and `@electric-sql/pglite` are optional peer dependencies,
+ * dynamically imported only when needed. For direct driver construction
+ * without auto-detection, use `db_pg.ts` or `db_pglite.ts`.
+ *
+ * @module
+ */
+import { create_pg_db } from './db_pg.js';
+import { create_pglite_db } from './db_pglite.js';
+/**
+ * Create a database connection based on a URL.
+ *
+ * Returns the `Db` instance, a typed `close` callback, driver type, and display name.
+ * The `close` callback is bound to the actual driver — callers never need to
+ * know which driver is in use.
+ *
+ * For direct driver construction without URL routing, import
+ * `create_pg_db` from `db_pg.ts` or `create_pglite_db` from `db_pglite.ts`.
+ *
+ * @param database_url - connection URL (`postgres://`, `postgresql://`, `file://`, or `memory://`)
+ * @returns database instance, close callback, type, and display name
+ */
+export const create_db = async (database_url) => {
+    if (database_url.startsWith('postgres://') || database_url.startsWith('postgresql://')) {
+        const { default: pg } = await import('pg');
+        const pool = new pg.Pool({ connectionString: database_url });
+        const { db, close } = create_pg_db(pool);
+        return {
+            db,
+            close,
+            db_type: 'postgres',
+            db_name: new URL(database_url).pathname.slice(1) || 'postgres',
+        };
+    }
+    if (database_url.startsWith('memory://')) {
+        const { PGlite } = await import('@electric-sql/pglite');
+        const pglite = new PGlite(database_url);
+        const { db, close } = create_pglite_db(pglite);
+        return { db, close, db_type: 'pglite-memory', db_name: '(memory)' };
+    }
+    if (database_url.startsWith('file://')) {
+        const path = new URL(database_url).pathname;
+        const { PGlite } = await import('@electric-sql/pglite');
+        const pglite = new PGlite(path);
+        const { db, close } = create_pglite_db(pglite);
+        return { db, close, db_type: 'pglite-file', db_name: path };
+    }
+    const scheme = database_url.split('://')[0] ?? database_url;
+    throw new Error(`Unsupported database URL scheme: ${scheme}://. Expected postgres://, postgresql://, file://, or memory://`);
+};

package/dist/db/db.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Database wrapper with duck-typed interface.
+ *
+ * Accepts any client with a query(text, values) method.
+ * Both `pg.Pool` and `@electric-sql/pglite` satisfy this interface.
+ *
+ * Transaction safety is provided by an injected `transaction` callback —
+ * the driver adapters (`db_pg.ts`, `db_pglite.ts`) supply the driver-appropriate
+ * implementation. Close is handled externally (returned alongside the Db
+ * as `DbDriverResult`), not as a method on this class.
+ *
+ * @module
+ */
+/**
+ * Minimal interface that both pg and pglite satisfy.
+ */
+export interface DbClient {
+    query: <T = unknown>(text: string, values?: Array<unknown>) => Promise<{
+        rows: Array<T>;
+    }>;
+}
+/**
+ * Configuration for constructing a `Db` with transaction support.
+ *
+ * `transaction` is injected by `create_db` which knows the driver.
+ * For pg: acquires a dedicated pool client per transaction.
+ * For PGlite: delegates to `pglite.transaction()`.
+ */
+export interface DbDeps {
+    client: DbClient;
+    transaction: <T>(fn: (tx_db: Db) => Promise<T>) => Promise<T>;
+}
+/**
+ * Result of constructing a driver-specific `Db`.
+ *
+ * Returned by `create_pg_db()` and `create_pglite_db()`.
+ * The `close` callback is bound to the actual driver — callers
+ * never need to know which driver is in use.
+ */
+export interface DbDriverResult {
+    db: Db;
+    /** Close the database connection. Bound to the actual driver at construction. */
+    close: () => Promise<void>;
+}
+/** Database driver type. */
+export type DbType = 'postgres' | 'pglite-file' | 'pglite-memory';
+/**
+ * Sentinel transaction function for transaction-scoped `Db` instances.
+ *
+ * Throws immediately — nested transactions are not supported.
+ * Used by driver adapters when constructing the inner `Db` passed
+ * to transaction callbacks.
+ */
+export declare const no_nested_transaction: DbDeps['transaction'];
+/**
+ * Database wrapper providing a consistent query and transaction interface.
+ *
+ * Construct via `create_pg_db()` from `db_pg.ts` or `create_pglite_db()` from
+ * `db_pglite.ts` for proper transaction support, or via `create_db()` for
+ * URL-based auto-detection.
+ *
+ * @example
+ * ```ts
+ * const {db, close} = await create_db('postgres://...');
+ * const users = await db.query<User>('SELECT * FROM users WHERE active = $1', [true]);
+ * await db.transaction(async (tx) => {
+ *   await tx.query('INSERT INTO users ...');
+ *   await tx.query('INSERT INTO audit_log ...');
+ * });
+ * await close();
+ * ```
+ */
+export declare class Db {
+    #private;
+    readonly client: DbClient;
+    constructor(options: DbDeps);
+    /**
+     * Execute a query and return all rows.
+     */
+    query<T>(text: string, values?: Array<unknown>): Promise<Array<T>>;
+    /**
+     * Execute a query and return the first row, or undefined if no rows.
+     */
+    query_one<T>(text: string, values?: Array<unknown>): Promise<T | undefined>;
+    /**
+     * Run a function inside a database transaction.
+     *
+     * The callback receives a transaction-scoped `Db`. Queries inside the callback
+     * go through the transaction connection; queries outside use the pool normally.
+     * Commits on success, rolls back on error.
+     *
+     * @param fn - async function receiving a transaction-scoped `Db`
+     * @returns the value returned by `fn`
+     */
+    transaction<T>(fn: (tx_db: Db) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=db.d.ts.map

package/dist/db/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;KAAC,CAAC,CAAC;CACzF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACtB,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,EAAE,CAAC;IACP,iFAAiF;IACjF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,4BAA4B;AAC5B,MAAM,MAAM,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,eAAe,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,CAEvD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,EAAE;;IACd,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAId,OAAO,EAAE,MAAM;IAK3B;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAKxE;;OAEG;IACG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKjF;;;;;;;;;OASG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAG/D"}

package/dist/db/db.js

@@ -0,0 +1,76 @@
+/**
+ * Database wrapper with duck-typed interface.
+ *
+ * Accepts any client with a query(text, values) method.
+ * Both `pg.Pool` and `@electric-sql/pglite` satisfy this interface.
+ *
+ * Transaction safety is provided by an injected `transaction` callback —
+ * the driver adapters (`db_pg.ts`, `db_pglite.ts`) supply the driver-appropriate
+ * implementation. Close is handled externally (returned alongside the Db
+ * as `DbDriverResult`), not as a method on this class.
+ *
+ * @module
+ */
+/**
+ * Sentinel transaction function for transaction-scoped `Db` instances.
+ *
+ * Throws immediately — nested transactions are not supported.
+ * Used by driver adapters when constructing the inner `Db` passed
+ * to transaction callbacks.
+ */
+export const no_nested_transaction = () => {
+    throw new Error('Nested transactions are not supported');
+};
+/**
+ * Database wrapper providing a consistent query and transaction interface.
+ *
+ * Construct via `create_pg_db()` from `db_pg.ts` or `create_pglite_db()` from
+ * `db_pglite.ts` for proper transaction support, or via `create_db()` for
+ * URL-based auto-detection.
+ *
+ * @example
+ * ```ts
+ * const {db, close} = await create_db('postgres://...');
+ * const users = await db.query<User>('SELECT * FROM users WHERE active = $1', [true]);
+ * await db.transaction(async (tx) => {
+ *   await tx.query('INSERT INTO users ...');
+ *   await tx.query('INSERT INTO audit_log ...');
+ * });
+ * await close();
+ * ```
+ */
+export class Db {
+    client;
+    #transaction;
+    constructor(options) {
+        this.client = options.client;
+        this.#transaction = options.transaction;
+    }
+    /**
+     * Execute a query and return all rows.
+     */
+    async query(text, values) {
+        const result = await this.client.query(text, values);
+        return result.rows;
+    }
+    /**
+     * Execute a query and return the first row, or undefined if no rows.
+     */
+    async query_one(text, values) {
+        const rows = await this.query(text, values);
+        return rows[0];
+    }
+    /**
+     * Run a function inside a database transaction.
+     *
+     * The callback receives a transaction-scoped `Db`. Queries inside the callback
+     * go through the transaction connection; queries outside use the pool normally.
+     * Commits on success, rolls back on error.
+     *
+     * @param fn - async function receiving a transaction-scoped `Db`
+     * @returns the value returned by `fn`
+     */
+    async transaction(fn) {
+        return this.#transaction(fn);
+    }
+}

package/dist/db/db_pg.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PostgreSQL driver adapter for `Db`.
+ *
+ * Provides `create_pg_db()` to construct a `Db` backed by a `pg.Pool`.
+ * Only imports `pg` types — the actual `pg` package is dynamically imported
+ * by callers (e.g., `create_db`) that construct the `Pool`.
+ *
+ * @module
+ */
+import type { Pool } from 'pg';
+import { type DbDriverResult } from './db.js';
+/**
+ * Create a `Db` backed by a pg `Pool`.
+ *
+ * Owns the transaction implementation (acquires a dedicated pool client
+ * per transaction) and returns a `close` callback bound to `pool.end()`.
+ *
+ * @param pool - an already-constructed `pg.Pool`
+ */
+export declare const create_pg_db: (pool: Pool) => DbDriverResult;
+//# sourceMappingURL=db_pg.d.ts.map

package/dist/db/db_pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db_pg.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db_pg.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,IAAI,CAAC;AAE7B,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,SAAS,CAAC;AA0BvE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,IAAI,KAAG,cAGxC,CAAC"}

package/dist/db/db_pg.js

@@ -0,0 +1,45 @@
+/**
+ * PostgreSQL driver adapter for `Db`.
+ *
+ * Provides `create_pg_db()` to construct a `Db` backed by a `pg.Pool`.
+ * Only imports `pg` types — the actual `pg` package is dynamically imported
+ * by callers (e.g., `create_db`) that construct the `Pool`.
+ *
+ * @module
+ */
+import { Db, no_nested_transaction } from './db.js';
+/**
+ * Create a transaction implementation for a pg Pool.
+ *
+ * Acquires a dedicated client from the pool for each transaction,
+ * ensuring BEGIN/COMMIT/ROLLBACK all hit the same connection.
+ */
+const create_pg_transaction = (pool) => async (fn) => {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const tx_db = new Db({ client, transaction: no_nested_transaction });
+        const result = await fn(tx_db);
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+};
+/**
+ * Create a `Db` backed by a pg `Pool`.
+ *
+ * Owns the transaction implementation (acquires a dedicated pool client
+ * per transaction) and returns a `close` callback bound to `pool.end()`.
+ *
+ * @param pool - an already-constructed `pg.Pool`
+ */
+export const create_pg_db = (pool) => ({
+    db: new Db({ client: pool, transaction: create_pg_transaction(pool) }),
+    close: () => pool.end(),
+});

package/dist/db/db_pglite.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PGlite driver adapter for `Db`.
+ *
+ * Provides `create_pglite_db()` to construct a `Db` backed by `@electric-sql/pglite`.
+ * Only imports PGlite types — the actual package is dynamically imported
+ * by callers (e.g., `create_db`) that construct the `PGlite` instance.
+ *
+ * @module
+ */
+import type { PGlite } from '@electric-sql/pglite';
+import { type DbDriverResult } from './db.js';
+/**
+ * Create a `Db` backed by a PGlite instance.
+ *
+ * Delegates transactions to PGlite's native `transaction()` method
+ * and returns a `close` callback bound to `pglite.close()`.
+ *
+ * @param pglite - an already-constructed PGlite instance
+ */
+export declare const create_pglite_db: (pglite: PGlite) => DbDriverResult;
+//# sourceMappingURL=db_pglite.d.ts.map

package/dist/db/db_pglite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db_pglite.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/db_pglite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,SAAS,CAAC;AAYvE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,cAGhD,CAAC"}

package/dist/db/db_pglite.js

@@ -0,0 +1,28 @@
+/**
+ * PGlite driver adapter for `Db`.
+ *
+ * Provides `create_pglite_db()` to construct a `Db` backed by `@electric-sql/pglite`.
+ * Only imports PGlite types — the actual package is dynamically imported
+ * by callers (e.g., `create_db`) that construct the `PGlite` instance.
+ *
+ * @module
+ */
+import { Db, no_nested_transaction } from './db.js';
+/**
+ * Create a transaction implementation for PGlite.
+ *
+ * Delegates to PGlite's native `transaction()` method.
+ */
+const create_pglite_transaction = (pglite) => async (fn) => pglite.transaction(async (tx) => fn(new Db({ client: tx, transaction: no_nested_transaction })));
+/**
+ * Create a `Db` backed by a PGlite instance.
+ *
+ * Delegates transactions to PGlite's native `transaction()` method
+ * and returns a `close` callback bound to `pglite.close()`.
+ *
+ * @param pglite - an already-constructed PGlite instance
+ */
+export const create_pglite_db = (pglite) => ({
+    db: new Db({ client: pglite, transaction: create_pglite_transaction(pglite) }),
+    close: () => pglite.close(),
+});

package/dist/db/migrate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Version-gated database migration runner.
+ *
+ * Migrations are functions in ordered arrays, grouped by namespace.
+ * A `schema_version` table tracks progress per namespace.
+ * Each migration runs in its own transaction.
+ *
+ * **Forward-only**: No down-migrations. Schema changes are additive.
+ * For pre-release development, collapse migrations into a single v0.
+ *
+ * **Named migrations**: Migrations can be bare functions or `{name, up}` objects.
+ * Names appear in error messages for debuggability.
+ *
+ * **Advisory locking**: Per-namespace PostgreSQL advisory locks serialize
+ * concurrent migration runs, preventing double-application in multi-instance deployments.
+ *
+ * @module
+ */
+import type { Db } from './db.js';
+/**
+ * A single migration function that receives a `Db` and applies DDL/DML.
+ *
+ * Runs inside a transaction — throw to rollback.
+ */
+export type MigrationFn = (db: Db) => Promise<void>;
+/**
+ * A migration: either a bare function or a named object with an `up` function.
+ *
+ * Named migrations include their name in error messages for debuggability.
+ */
+export type Migration = MigrationFn | {
+    name: string;
+    up: MigrationFn;
+};
+/**
+ * A named group of ordered migrations.
+ *
+ * Array index = version number: `migrations[0]` is version 0, etc.
+ */
+export interface MigrationNamespace {
+    namespace: string;
+    migrations: Array<Migration>;
+}
+/** Result of running migrations for a single namespace. */
+export interface MigrationResult {
+    namespace: string;
+    from_version: number;
+    to_version: number;
+    migrations_applied: number;
+}
+/**
+ * Run pending migrations for each namespace.
+ *
+ * Creates the `schema_version` tracking table if it does not exist,
+ * then for each namespace: acquires an advisory lock, reads the current
+ * version, runs pending migrations in order (each in its own transaction),
+ * updates the stored version, and releases the lock.
+ *
+ * **Concurrency**: Uses PostgreSQL advisory locks to serialize concurrent
+ * callers on the same namespace. Safe for multi-instance deployments.
+ *
+ * @param db - the database instance
+ * @param namespaces - migration namespaces to process in order
+ * @returns results per namespace (only includes namespaces that had work to do)
+ */
+export declare const run_migrations: (db: Db, namespaces: Array<MigrationNamespace>) => Promise<Array<MigrationResult>>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/db/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,WAAW,CAAA;CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC7B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AA8BD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,kBAAkB,CAAC,KACnC,OAAO,CAAC,KAAK,CAAC,eAAe,CAAC,CA2EhC,CAAC"}

package/dist/db/migrate.js

@@ -0,0 +1,118 @@
+/**
+ * Version-gated database migration runner.
+ *
+ * Migrations are functions in ordered arrays, grouped by namespace.
+ * A `schema_version` table tracks progress per namespace.
+ * Each migration runs in its own transaction.
+ *
+ * **Forward-only**: No down-migrations. Schema changes are additive.
+ * For pre-release development, collapse migrations into a single v0.
+ *
+ * **Named migrations**: Migrations can be bare functions or `{name, up}` objects.
+ * Names appear in error messages for debuggability.
+ *
+ * **Advisory locking**: Per-namespace PostgreSQL advisory locks serialize
+ * concurrent migration runs, preventing double-application in multi-instance deployments.
+ *
+ * @module
+ */
+const SCHEMA_VERSION_DDL = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  namespace TEXT PRIMARY KEY,
+  version INTEGER NOT NULL DEFAULT 0,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`;
+/** Normalize a migration to its function and optional name. */
+const resolve_migration = (m) => {
+    if (typeof m === 'function') {
+        return { fn: m, name: null };
+    }
+    return { fn: m.up, name: m.name };
+};
+/**
+ * Compute a stable int32 advisory lock key from a namespace string.
+ *
+ * Uses djb2 hash, masked to int32 range for `pg_advisory_lock`.
+ */
+const namespace_lock_key = (namespace) => {
+    let hash = 5381;
+    for (let i = 0; i < namespace.length; i++) {
+        hash = ((hash << 5) + hash + namespace.charCodeAt(i)) | 0;
+    }
+    return hash;
+};
+/**
+ * Run pending migrations for each namespace.
+ *
+ * Creates the `schema_version` tracking table if it does not exist,
+ * then for each namespace: acquires an advisory lock, reads the current
+ * version, runs pending migrations in order (each in its own transaction),
+ * updates the stored version, and releases the lock.
+ *
+ * **Concurrency**: Uses PostgreSQL advisory locks to serialize concurrent
+ * callers on the same namespace. Safe for multi-instance deployments.
+ *
+ * @param db - the database instance
+ * @param namespaces - migration namespaces to process in order
+ * @returns results per namespace (only includes namespaces that had work to do)
+ */
+export const run_migrations = async (db, namespaces) => {
+    await db.query(SCHEMA_VERSION_DDL);
+    const results = [];
+    /* eslint-disable no-await-in-loop */
+    for (const { namespace, migrations } of namespaces) {
+        const lock_key = namespace_lock_key(namespace);
+        // Acquire advisory lock — serializes concurrent migration runs
+        try {
+            await db.query('SELECT pg_advisory_lock($1)', [lock_key]);
+        }
+        catch {
+            // Advisory lock not supported (e.g. some PGlite versions) — proceed without
+        }
+        try {
+            const row = await db.query_one('SELECT version FROM schema_version WHERE namespace = $1', [namespace]);
+            const current_version = row?.version ?? 0;
+            if (current_version > migrations.length) {
+                throw new Error(`schema_version for "${namespace}" is ${current_version} but only ${migrations.length} migrations exist — was a migration removed?`);
+            }
+            if (current_version === migrations.length) {
+                continue; // up to date
+            }
+            // run pending migrations, each in its own transaction with version upsert
+            for (let i = current_version; i < migrations.length; i++) {
+                const { fn, name } = resolve_migration(migrations[i]);
+                const label = name != null ? `"${name}"` : '';
+                try {
+                    await db.transaction(async (tx) => {
+                        await fn(tx);
+                        await tx.query(`INSERT INTO schema_version (namespace, version, applied_at)
+							 VALUES ($1, $2, NOW())
+							 ON CONFLICT (namespace)
+							 DO UPDATE SET version = $2, applied_at = NOW()`, [namespace, i + 1]);
+                    });
+                }
+                catch (err) {
+                    const name_part = label ? ` ${label}` : '';
+                    throw new Error(`Migration ${namespace}[${i}]${name_part} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+                }
+            }
+            results.push({
+                namespace,
+                from_version: current_version,
+                to_version: migrations.length,
+                migrations_applied: migrations.length - current_version,
+            });
+        }
+        finally {
+            // Release advisory lock
+            try {
+                await db.query('SELECT pg_advisory_unlock($1)', [lock_key]);
+            }
+            catch {
+                // Advisory lock not supported — nothing to release
+            }
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    return results;
+};