@better-forge/db 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BetterStatusPage contributors
+
+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,33 @@
-# Temporary Holding Version
-
-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.
+# @better-forge/db
+
+SQLite (`node:sqlite`) and Drizzle bootstrap, transactions, and the registries that let each module own its tables and
+migrations. No state of its own: the application opens the connection and passes it in.
+
+```ts
+import { composeModules, openDatabase, runMigrations, type DbModule } from '@better-forge/db'
+
+const notes: DbModule = {
+  id: 'notes',
+  tables: { notesTable },               // Drizzle tables the module owns
+  migrations: [
+    { kind: 'exec', sql: 'CREATE TABLE IF NOT EXISTS notes (...)' },                       // idempotent DDL
+    { kind: 'column', sql: 'ALTER TABLE notes ADD COLUMN pinned INTEGER', desc: 'notes.pinned' }, // tolerates "already applied" only
+    { kind: 'data', name: 'seed-notes-v1', run: (sqlite) => { /* once, in a transaction */ } },
+  ],
+}
+
+const { schema } = composeModules([auth, audit, notes])   // throws on a repeated module, table export or data name
+const { sqlite, db, close } = openDatabase({ path, schema })
+runMigrations(sqlite, [auth, audit, notes])               // modules run in the order given
+```
+
+Rules for a module's migrations:
+
+- Steps run in the listed order on every start, so each must be idempotent.
+- A `data` step's name is stored in `schema_migrations`. Never rename or drop one: it would run again on existing data.
+- Order matters where SQLite stores the statement text: columns added with `ALTER` keep their relative order per table.
+- A module may rely on the tables of the modules listed before it.
+
+`drizzle-orm` is a peer dependency, so the application and every module share one copy. Requires Node 22.5 or newer.
+
+Status: pre-1.0.

package/dist/database.d.ts

@@ -0,0 +1,23 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy';
+/**
+ * The Drizzle handle as a package sees it. Which tables it knows is the application's business, so the schema is left
+ * open; each package names the tables it uses in its queries.
+ */
+export type SqliteDatabase = SqliteRemoteDatabase<any>;
+export interface Database<Schema extends Record<string, unknown>> {
+    /** Raw node:sqlite handle. */
+    sqlite: DatabaseSync;
+    /** Drizzle handle over the same connection. */
+    db: SqliteRemoteDatabase<Schema>;
+    close(): void;
+}
+/**
+ * Opens (creating its directory when needed) the SQLite file at `path` in WAL mode with foreign keys on, and wires
+ * Drizzle to the same connection. A process uses one connection; the caller decides where that instance lives.
+ */
+export declare function openDatabase<Schema extends Record<string, unknown>>(options: {
+    path: string;
+    schema: Schema;
+}): Database<Schema>;
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAEpE;;;GAGG;AAEH,MAAM,MAAM,cAAc,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAA;AAItD,MAAM,WAAW,QAAQ,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,8BAA8B;IAC9B,MAAM,EAAE,YAAY,CAAA;IACpB,+CAA+C;IAC/C,EAAE,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAChC,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAyBhI"}

package/dist/database.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { drizzle } from 'drizzle-orm/sqlite-proxy';
+/**
+ * Opens (creating its directory when needed) the SQLite file at `path` in WAL mode with foreign keys on, and wires
+ * Drizzle to the same connection. A process uses one connection; the caller decides where that instance lives.
+ */
+export function openDatabase(options) {
+    const dir = path.dirname(options.path);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const sqlite = new DatabaseSync(options.path);
+    sqlite.exec('PRAGMA journal_mode = WAL');
+    sqlite.exec('PRAGMA foreign_keys = ON');
+    // sqlite-proxy maps result rows by position, so rows are handed over as value arrays.
+    const db = drizzle(async (sql, params, method) => {
+        const p = params;
+        const stmt = sqlite.prepare(sql);
+        if (method === 'run') {
+            stmt.run(...p);
+            return { rows: [] };
+        }
+        else if (method === 'get') {
+            const row = stmt.get(...p);
+            return { rows: row ? [Object.values(row)] : [] };
+        }
+        else {
+            const rows = stmt.all(...p);
+            return { rows: rows.map((r) => Object.values(r)) };
+        }
+    }, { schema: options.schema });
+    return { sqlite, db, close: () => sqlite.close() };
+}
+//# sourceMappingURL=database.js.map

package/dist/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAoBlD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAyC,OAAyC;IAC5G,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/D,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;IACxC,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;IACvC,sFAAsF;IACtF,MAAM,EAAE,GAAG,OAAO,CAChB,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;QAC5B,MAAM,CAAC,GAAG,MAAiB,CAAA;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAChC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;YACd,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAA;QACrB,CAAC;aAAM,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAwC,CAAA;YACjE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;QAClD,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAA8B,CAAA;YACxD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;QACpD,CAAC;IACH,CAAC,EACD,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAC3B,CAAA;IACD,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAA;AACpD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { openDatabase, type Database, type SqliteDatabase } from './database.js';
+export { applyColumnMigration, composeModules, runMigrations, type DbModule, type MigrationStep } from './migrations.js';
+export { withImmediateTransaction } from './transaction.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAChF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACxH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { openDatabase } from './database.js';
+export { applyColumnMigration, composeModules, runMigrations } from './migrations.js';
+export { withImmediateTransaction } from './transaction.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsC,MAAM,eAAe,CAAA;AAChF,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,aAAa,EAAqC,MAAM,iBAAiB,CAAA;AACxH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/migrations.d.ts

@@ -0,0 +1,54 @@
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * One step of a module's migrations. Steps run in the order they are listed, on every start, so each must be
+ * idempotent; a `data` step is made so by being recorded in `schema_migrations` under its name.
+ */
+export type MigrationStep = 
+/** Idempotent DDL, such as `CREATE TABLE IF NOT EXISTS`. */
+{
+    kind: 'exec';
+    sql: string;
+}
+/**
+ * A change that fails when it was already applied (`ADD COLUMN`, `DROP COLUMN`). Only that failure is expected;
+ * anything else (typo, locked database, disk full) surfaces.
+ */
+ | {
+    kind: 'column';
+    sql: string;
+    desc: string;
+}
+/** Runs once in an immediate transaction. The name is stored: renaming it would run the step again on existing data. */
+ | {
+    kind: 'data';
+    name: string;
+    run(sqlite: DatabaseSync): void;
+};
+/** A part of the schema with the migrations that create and evolve it. */
+export interface DbModule<Tables extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    /** Drizzle table definitions the module owns. */
+    tables: Tables;
+    migrations: readonly MigrationStep[];
+}
+/**
+ * Merges the tables of several modules into one Drizzle schema. A repeated module id, table export or data
+ * migration name is a mistake that would silently shadow or double-run something, so it throws.
+ */
+export declare function composeModules<const Modules extends readonly DbModule[]>(modules: Modules): {
+    schema: Record<string, unknown>;
+    modules: Modules;
+};
+/**
+ * Applies the `column` change in `sql`. Returns true when it changed the schema and false when it had already been
+ * applied.
+ */
+export declare function applyColumnMigration(sqlite: DatabaseSync, sql: string): boolean;
+/**
+ * Brings the database to the schema the modules describe: first the migration ledger, then each module's steps in
+ * the order the modules are given. Safe to run on every start.
+ */
+export declare function runMigrations(sqlite: DatabaseSync, modules: readonly DbModule[], options?: {
+    log?: (message: string) => void;
+}): void;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;GAGG;AACH,MAAM,MAAM,aAAa;AACvB,4DAA4D;AAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AAC/B;;;GAGG;GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC/C,wHAAwH;GACtH;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,CAAA;AAEnE,0EAA0E;AAC1E,MAAM,WAAW,QAAQ,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxF,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CACrC;AASD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,OAAO,SAAS,SAAS,QAAQ,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG;IAC3F,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,EAAE,OAAO,CAAA;CACjB,CAkBA;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAW/E;AAiBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,QAAQ,EAAE,EAAE,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAAG,IAAI,CAYzI"}

package/dist/migrations.js

@@ -0,0 +1,89 @@
+const SCHEMA_MIGRATIONS = `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  name TEXT PRIMARY KEY,
+  applied_at INTEGER NOT NULL
+);
+`;
+/**
+ * Merges the tables of several modules into one Drizzle schema. A repeated module id, table export or data
+ * migration name is a mistake that would silently shadow or double-run something, so it throws.
+ */
+export function composeModules(modules) {
+    const ids = new Set();
+    const dataNames = new Set();
+    const schema = {};
+    for (const module of modules) {
+        if (ids.has(module.id))
+            throw new Error(`Duplicate database module "${module.id}"`);
+        ids.add(module.id);
+        for (const [exportName, table] of Object.entries(module.tables)) {
+            if (Object.hasOwn(schema, exportName))
+                throw new Error(`Duplicate table export "${exportName}" in module "${module.id}"`);
+            schema[exportName] = table;
+        }
+        for (const step of module.migrations) {
+            if (step.kind !== 'data')
+                continue;
+            if (dataNames.has(step.name))
+                throw new Error(`Duplicate data migration "${step.name}" in module "${module.id}"`);
+            dataNames.add(step.name);
+        }
+    }
+    return { schema, modules };
+}
+/**
+ * Applies the `column` change in `sql`. Returns true when it changed the schema and false when it had already been
+ * applied.
+ */
+export function applyColumnMigration(sqlite, sql) {
+    const alreadyApplied = /\bADD\s+COLUMN\b/i.test(sql) ? /duplicate column name/i
+        : /\bDROP\s+COLUMN\b/i.test(sql) ? /no such column/i
+            : null;
+    try {
+        sqlite.exec(sql);
+        return true;
+    }
+    catch (error) {
+        if (alreadyApplied && error instanceof Error && alreadyApplied.test(error.message))
+            return false;
+        throw error;
+    }
+}
+function runDataMigration(sqlite, name, migrate) {
+    sqlite.exec('BEGIN IMMEDIATE');
+    try {
+        const applied = sqlite.prepare('SELECT 1 FROM schema_migrations WHERE name = ?').get(name);
+        if (!applied) {
+            migrate();
+            sqlite.prepare('INSERT INTO schema_migrations (name, applied_at) VALUES (?, ?)').run(name, Date.now());
+        }
+        sqlite.exec('COMMIT');
+    }
+    catch (error) {
+        sqlite.exec('ROLLBACK');
+        throw error;
+    }
+}
+/**
+ * Brings the database to the schema the modules describe: first the migration ledger, then each module's steps in
+ * the order the modules are given. Safe to run on every start.
+ */
+export function runMigrations(sqlite, modules, options = {}) {
+    const log = options.log ?? console.log;
+    composeModules(modules);
+    sqlite.exec(SCHEMA_MIGRATIONS);
+    for (const module of modules) {
+        for (const step of module.migrations) {
+            if (step.kind === 'exec')
+                sqlite.exec(step.sql);
+            else if (step.kind === 'column') {
+                if (applyColumnMigration(sqlite, step.sql))
+                    log(`✓ Column migration: ${step.desc}`);
+            }
+            else
+                runDataMigration(sqlite, step.name, () => step.run(sqlite));
+        }
+    }
+    log('✓ Migrations applied');
+}
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"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"}

package/dist/transaction.d.ts

@@ -0,0 +1,14 @@
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * Runs `work` between BEGIN IMMEDIATE and COMMIT (or ROLLBACK if it throws).
+ *
+ * There is one SQLite connection, so a second transaction cannot begin while another is open. Callers that arrive
+ * meanwhile wait their turn instead of failing. A transaction started from inside `work` can never get its turn, so
+ * it throws.
+ *
+ * The `await`s inside `work` only yield to microtasks as long as every database call is synchronous underneath, which
+ * holds for the node:sqlite driver: no other request can run its statements inside this transaction. Do not await real
+ * I/O here (a network call, a timer): that lets another request's writes join the transaction and be rolled back with it.
+ */
+export declare function withImmediateTransaction<T>(sqlite: DatabaseSync, work: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAO/C;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAKpG"}

package/dist/transaction.js

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+// Transactions of one connection take turns: the next one begins when the previous one has committed or rolled back.
+const queues = new WeakMap();
+// The connection whose transaction the current async chain is inside, to refuse a nested one.
+const inside = new AsyncLocalStorage();
+/**
+ * Runs `work` between BEGIN IMMEDIATE and COMMIT (or ROLLBACK if it throws).
+ *
+ * There is one SQLite connection, so a second transaction cannot begin while another is open. Callers that arrive
+ * meanwhile wait their turn instead of failing. A transaction started from inside `work` can never get its turn, so
+ * it throws.
+ *
+ * The `await`s inside `work` only yield to microtasks as long as every database call is synchronous underneath, which
+ * holds for the node:sqlite driver: no other request can run its statements inside this transaction. Do not await real
+ * I/O here (a network call, a timer): that lets another request's writes join the transaction and be rolled back with it.
+ */
+export function withImmediateTransaction(sqlite, work) {
+    if (inside.getStore() === sqlite)
+        return Promise.reject(new Error('Nested transaction: it would wait for the one it is part of'));
+    const run = (queues.get(sqlite) ?? Promise.resolve()).then(() => runTransaction(sqlite, work));
+    queues.set(sqlite, run.catch(() => undefined));
+    return run;
+}
+async function runTransaction(sqlite, work) {
+    sqlite.exec('BEGIN IMMEDIATE');
+    try {
+        const result = await inside.run(sqlite, work);
+        sqlite.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        try {
+            sqlite.exec('ROLLBACK');
+        }
+        catch { /* preserve the original error */ }
+        throw error;
+    }
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGpD,qHAAqH;AACrH,MAAM,MAAM,GAAG,IAAI,OAAO,EAAkC,CAAA;AAC5D,8FAA8F;AAC9F,MAAM,MAAM,GAAG,IAAI,iBAAiB,EAAgB,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAI,MAAoB,EAAE,IAAsB;IACtF,IAAI,MAAM,CAAC,QAAQ,EAAE,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC,CAAA;IACjI,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IAC9F,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAA;IAC9C,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,KAAK,UAAU,cAAc,CAAI,MAAoB,EAAE,IAAsB;IAC3E,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;IAC9B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QAC7C,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACrB,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC;YAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,iCAAiC,CAAC,CAAC;QAC3E,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
-{
-  "name": "@better-forge/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@better-forge/db",
+  "version": "0.1.0",
+  "description": "SQLite (node:sqlite) and Drizzle bootstrap, transactions, schema and migration registries.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/db"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/db#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "drizzle-orm": "^0.45.2",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/database.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { drizzle } from 'drizzle-orm/sqlite-proxy'
+import type { SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy'
+
+/**
+ * The Drizzle handle as a package sees it. Which tables it knows is the application's business, so the schema is left
+ * open; each package names the tables it uses in its queries.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type SqliteDatabase = SqliteRemoteDatabase<any>
+
+type Param = string | number | bigint | null | Uint8Array
+
+export interface Database<Schema extends Record<string, unknown>> {
+  /** Raw node:sqlite handle. */
+  sqlite: DatabaseSync
+  /** Drizzle handle over the same connection. */
+  db: SqliteRemoteDatabase<Schema>
+  close(): void
+}
+
+/**
+ * Opens (creating its directory when needed) the SQLite file at `path` in WAL mode with foreign keys on, and wires
+ * Drizzle to the same connection. A process uses one connection; the caller decides where that instance lives.
+ */
+export function openDatabase<Schema extends Record<string, unknown>>(options: { path: string; schema: Schema }): Database<Schema> {
+  const dir = path.dirname(options.path)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  const sqlite = new DatabaseSync(options.path)
+  sqlite.exec('PRAGMA journal_mode = WAL')
+  sqlite.exec('PRAGMA foreign_keys = ON')
+  // sqlite-proxy maps result rows by position, so rows are handed over as value arrays.
+  const db = drizzle(
+    async (sql, params, method) => {
+      const p = params as Param[]
+      const stmt = sqlite.prepare(sql)
+      if (method === 'run') {
+        stmt.run(...p)
+        return { rows: [] }
+      } else if (method === 'get') {
+        const row = stmt.get(...p) as Record<string, unknown> | undefined
+        return { rows: row ? [Object.values(row)] : [] }
+      } else {
+        const rows = stmt.all(...p) as Record<string, unknown>[]
+        return { rows: rows.map((r) => Object.values(r)) }
+      }
+    },
+    { schema: options.schema },
+  )
+  return { sqlite, db, close: () => sqlite.close() }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { openDatabase, type Database, type SqliteDatabase } from './database.js'
+export { applyColumnMigration, composeModules, runMigrations, type DbModule, type MigrationStep } from './migrations.js'
+export { withImmediateTransaction } from './transaction.js'

package/src/migrations.ts

@@ -0,0 +1,108 @@
+import type { DatabaseSync } from 'node:sqlite'
+
+/**
+ * One step of a module's migrations. Steps run in the order they are listed, on every start, so each must be
+ * idempotent; a `data` step is made so by being recorded in `schema_migrations` under its name.
+ */
+export type MigrationStep =
+  /** Idempotent DDL, such as `CREATE TABLE IF NOT EXISTS`. */
+  | { kind: 'exec'; sql: string }
+  /**
+   * A change that fails when it was already applied (`ADD COLUMN`, `DROP COLUMN`). Only that failure is expected;
+   * anything else (typo, locked database, disk full) surfaces.
+   */
+  | { kind: 'column'; sql: string; desc: string }
+  /** Runs once in an immediate transaction. The name is stored: renaming it would run the step again on existing data. */
+  | { kind: 'data'; name: string; run(sqlite: DatabaseSync): void }
+
+/** A part of the schema with the migrations that create and evolve it. */
+export interface DbModule<Tables extends Record<string, unknown> = Record<string, unknown>> {
+  id: string
+  /** Drizzle table definitions the module owns. */
+  tables: Tables
+  migrations: readonly MigrationStep[]
+}
+
+const SCHEMA_MIGRATIONS = `
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  name TEXT PRIMARY KEY,
+  applied_at INTEGER NOT NULL
+);
+`
+
+/**
+ * Merges the tables of several modules into one Drizzle schema. A repeated module id, table export or data
+ * migration name is a mistake that would silently shadow or double-run something, so it throws.
+ */
+export function composeModules<const Modules extends readonly DbModule[]>(modules: Modules): {
+  schema: Record<string, unknown>
+  modules: Modules
+} {
+  const ids = new Set<string>()
+  const dataNames = new Set<string>()
+  const schema: Record<string, unknown> = {}
+  for (const module of modules) {
+    if (ids.has(module.id)) throw new Error(`Duplicate database module "${module.id}"`)
+    ids.add(module.id)
+    for (const [exportName, table] of Object.entries(module.tables)) {
+      if (Object.hasOwn(schema, exportName)) throw new Error(`Duplicate table export "${exportName}" in module "${module.id}"`)
+      schema[exportName] = table
+    }
+    for (const step of module.migrations) {
+      if (step.kind !== 'data') continue
+      if (dataNames.has(step.name)) throw new Error(`Duplicate data migration "${step.name}" in module "${module.id}"`)
+      dataNames.add(step.name)
+    }
+  }
+  return { schema, modules }
+}
+
+/**
+ * Applies the `column` change in `sql`. Returns true when it changed the schema and false when it had already been
+ * applied.
+ */
+export function applyColumnMigration(sqlite: DatabaseSync, sql: string): boolean {
+  const alreadyApplied = /\bADD\s+COLUMN\b/i.test(sql) ? /duplicate column name/i
+    : /\bDROP\s+COLUMN\b/i.test(sql) ? /no such column/i
+      : null
+  try {
+    sqlite.exec(sql)
+    return true
+  } catch (error) {
+    if (alreadyApplied && error instanceof Error && alreadyApplied.test(error.message)) return false
+    throw error
+  }
+}
+
+function runDataMigration(sqlite: DatabaseSync, name: string, migrate: () => void): void {
+  sqlite.exec('BEGIN IMMEDIATE')
+  try {
+    const applied = sqlite.prepare('SELECT 1 FROM schema_migrations WHERE name = ?').get(name)
+    if (!applied) {
+      migrate()
+      sqlite.prepare('INSERT INTO schema_migrations (name, applied_at) VALUES (?, ?)').run(name, Date.now())
+    }
+    sqlite.exec('COMMIT')
+  } catch (error) {
+    sqlite.exec('ROLLBACK')
+    throw error
+  }
+}
+
+/**
+ * Brings the database to the schema the modules describe: first the migration ledger, then each module's steps in
+ * the order the modules are given. Safe to run on every start.
+ */
+export function runMigrations(sqlite: DatabaseSync, modules: readonly DbModule[], options: { log?: (message: string) => void } = {}): void {
+  const log = options.log ?? console.log
+  composeModules(modules)
+  sqlite.exec(SCHEMA_MIGRATIONS)
+  for (const module of modules) {
+    for (const step of module.migrations) {
+      if (step.kind === 'exec') sqlite.exec(step.sql)
+      else if (step.kind === 'column') { if (applyColumnMigration(sqlite, step.sql)) log(`✓ Column migration: ${step.desc}`) }
+      else runDataMigration(sqlite, step.name, () => step.run(sqlite))
+    }
+  }
+  log('✓ Migrations applied')
+}

package/src/transaction.ts

@@ -0,0 +1,37 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { DatabaseSync } from 'node:sqlite'
+
+// Transactions of one connection take turns: the next one begins when the previous one has committed or rolled back.
+const queues = new WeakMap<DatabaseSync, Promise<unknown>>()
+// The connection whose transaction the current async chain is inside, to refuse a nested one.
+const inside = new AsyncLocalStorage<DatabaseSync>()
+
+/**
+ * Runs `work` between BEGIN IMMEDIATE and COMMIT (or ROLLBACK if it throws).
+ *
+ * There is one SQLite connection, so a second transaction cannot begin while another is open. Callers that arrive
+ * meanwhile wait their turn instead of failing. A transaction started from inside `work` can never get its turn, so
+ * it throws.
+ *
+ * The `await`s inside `work` only yield to microtasks as long as every database call is synchronous underneath, which
+ * holds for the node:sqlite driver: no other request can run its statements inside this transaction. Do not await real
+ * I/O here (a network call, a timer): that lets another request's writes join the transaction and be rolled back with it.
+ */
+export function withImmediateTransaction<T>(sqlite: DatabaseSync, work: () => Promise<T>): Promise<T> {
+  if (inside.getStore() === sqlite) return Promise.reject(new Error('Nested transaction: it would wait for the one it is part of'))
+  const run = (queues.get(sqlite) ?? Promise.resolve()).then(() => runTransaction(sqlite, work))
+  queues.set(sqlite, run.catch(() => undefined))
+  return run
+}
+
+async function runTransaction<T>(sqlite: DatabaseSync, work: () => Promise<T>): Promise<T> {
+  sqlite.exec('BEGIN IMMEDIATE')
+  try {
+    const result = await inside.run(sqlite, work)
+    sqlite.exec('COMMIT')
+    return result
+  } catch (error) {
+    try { sqlite.exec('ROLLBACK') } catch { /* preserve the original error */ }
+    throw error
+  }
+}