acrylblends 0.7.4 → 0.7.6

package/docs/framework/getting-started/service-worker.md

@@ -17,15 +17,17 @@ fire(app)
 
 A request the app does not answer (`404`) can be passed on to the network by giving `fetch` as an option, so a Service Worker can serve some routes and leave the others to the origin:
 
-```ts no-check
+```ts lib=webworker
 import { Acryl } from 'acrylblends'
 import { handle } from 'acrylblends/service-worker'
 
+declare const self: ServiceWorkerGlobalScope
+
 const app = new Acryl()
 
 app.get('/offline', (c) => c.text('Served by the Service Worker'))
 
-addEventListener('fetch', handle(app, { fetch: globalThis.fetch }))
+self.addEventListener('fetch', handle(app, { fetch: globalThis.fetch }))
 ```
 
-`app.fire()` (a method of the app) is deprecated in favour of `fire()` from this module.
+The example is type-checked with the TypeScript `WebWorker` library: declare `self` as a `ServiceWorkerGlobalScope` as above. `app.fire()` (a method of the app) is deprecated in favour of `fire()` from this module.

package/docs/framework/guides/create-acrylblends.md

@@ -8,8 +8,8 @@
 | Template | What you get |
 | --- | --- |
 | `nodejs` | an Acryl application served with `serve()` from `acrylblends/node-server`; run with Node.js 22.19 or newer |
-| `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite (`node:sqlite`), validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
-| `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite, tests with a mock model |
+| `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
+| `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
 | `bun` (experimental) | an Acryl application with `export default app`, run with `bun` |
 | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
 

package/docs/framework/guides/data.md

@@ -0,0 +1,237 @@
+# Data: the `db` port, migrations and choosing a store
+
+An app that keeps records (users, notes, orders) keeps them in a SQL database, and reaches it through one small interface, `db`. Handlers and
+stores take a `Db` as an argument and never import a driver, so the file or server behind it can change without touching them. SQLite is the
+provider today; a Postgres provider (Postgres or Supabase through `DATABASE_URL`) is planned and serves the same interface.
+
+## Choosing
+
+| The app | Use | State |
+| --- | --- | --- |
+| Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
+| Hosted, many users | `db` with Postgres or Supabase | planned |
+| Tiny, one person, a few screens | `kv`, named JSON documents with no SQL | planned |
+| Agents or long tasks that must survive a restart | `durable`, in the same database as `db` | planned |
+
+Start with `db`. It is the only one of the four you can use today, and SQL is what people and coding agents already know.
+
+## Open the database
+
+`openDb` from `acrylblends/db/sqlite` opens one SQLite file, applies your migrations, and returns the database next to the function that closes it:
+
+```ts
+import { openDb } from 'acrylblends/db/sqlite'
+
+const { db, close } = await openDb({ path: 'data/app.sqlite', migrations: 'migrations' })
+```
+
+- `path` is the file, created with its folder when it does not exist. `':memory:'` opens a database that lives and dies with the process, which
+  is what tests use.
+- `migrations` is a folder of numbered SQL files, relative to the working directory (see below).
+- `db` is the port: `exec`, `run`, `get`, `all` and `transaction`, every one returning a promise. It has no `close`, so no part of the app can
+  close the database another part is using. `close` is the opener's: call it once, when the process stops.
+
+Pass `db` to the code that needs it. Nothing opens the database at import time, so importing a module never creates a file:
+
+```ts
+import type { Db } from 'acrylblends/db'
+
+export function notesStore(db: Db) {
+  return {
+    async titles(userId: number): Promise<string[]> {
+      const rows = await db.all<{ title: string }>(
+        'SELECT title FROM notes WHERE user_id = ? ORDER BY updated_at DESC',
+        userId,
+      )
+      return rows.map((row) => row.title)
+    },
+  }
+}
+```
+
+## Migrations
+
+The shape of the database lives in `migrations/`, one numbered file per change:
+
+```
+migrations/
+  001-notes.sql
+  002-tags.sql
+```
+
+```sql
+-- migrations/002-tags.sql
+CREATE TABLE tags (
+  note_id INTEGER NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  PRIMARY KEY (note_id, name)
+);
+```
+
+- Files are named `NNN-name.sql` and numbered from 1 with no gaps. A gap, a repeated number or a file named otherwise stops the app at start
+  with a message that names it.
+- On start, `openDb` applies the files that have not run yet, in order, **in one transaction**: a failing file leaves the database as it was.
+- The version is recorded in the `_migrations` table. Do not touch that table.
+- **Never edit a file that has been applied.** A database that already ran `001` does not run it again, so an edit changes only new databases.
+  To change a table, add the next file (`ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0`).
+- A database whose version is newer than your files (an older build started on newer data) is refused. The app does not start.
+- A migration is plain SQL. Put the data change next to the shape change in the same file when they belong together.
+
+To add a feature that needs a column or a table, the work is always the same three steps: write the next migration, change the store that
+reads and writes it, and change the handlers and views that use the store.
+
+## Reading and writing
+
+```ts
+// One row, or undefined.
+const note = await db.get<Note>('SELECT * FROM notes WHERE id = ? AND user_id = ?', id, userId)
+
+// Many rows.
+const notes = await db.all<Note>('SELECT * FROM notes WHERE user_id = ? ORDER BY id', userId)
+
+// A write: how many rows it changed.
+const { changes } = await db.run('DELETE FROM notes WHERE id = ? AND user_id = ?', id, userId)
+if (changes === 0) return c.notFound()
+
+// A write that gives back the row it made.
+const created = await db.get<Note>(
+  'INSERT INTO notes (user_id, title, body, updated_at) VALUES (?, ?, ?, ?) RETURNING *',
+  userId, title, body, new Date().toISOString(),
+)
+```
+
+- Values go in as **bindings** after the SQL (`?`, in order), never inside the SQL text. This is what keeps a title like `'); DROP TABLE notes;--`
+  a title. A binding is `null`, a number, a bigint, a string or a `Uint8Array`; turn a boolean into `0` or `1` and a date into
+  `toISOString()` yourself.
+- `exec(sql)` runs SQL text with no bindings, and may hold several statements. Use it for setup, not for user input.
+- `db.get` has no `lastInsertRowid`. To get the new row or its id, end the insert with `RETURNING *` or `RETURNING id`.
+- `changes` is what makes "update only if nothing changed meanwhile" possible: `UPDATE ... WHERE id = ? AND version = ?` and check `changes`.
+
+## Transactions
+
+Changes that must happen together go in `transaction`. Everything inside goes through the handle the callback receives:
+
+```ts
+await db.transaction(async (tx) => {
+  const { changes } = await tx.run('UPDATE accounts SET balance = balance - ? WHERE id = ? AND balance >= ?', amount, from, amount)
+  if (changes === 0) throw new Error('not enough money')
+  await tx.run('UPDATE accounts SET balance = balance + ? WHERE id = ?', amount, to)
+})
+```
+
+- If the callback throws, the transaction is rolled back and `transaction` rejects with that same error.
+- Other calls, and other transactions, wait until the transaction finishes. So **never call `db` itself inside the callback**, only `tx`: that
+  call would wait for a transaction that waits for it, and never return.
+- The handle stops working when the callback settles. Do not keep it.
+
+## Writing SQL that moves to Postgres
+
+The Postgres provider is not released yet, and it will serve the same interface. SQL that stays inside this list runs on both:
+
+- Placeholders are `?` on every provider.
+- Use `RETURNING` to get a new row, not a driver-specific "last id".
+- Keep dates as ISO 8601 text (`new Date().toISOString()`), and booleans as `0` and `1`.
+- Keep identifiers lower case and unquoted.
+- `INTEGER PRIMARY KEY` makes an automatically numbered key in SQLite. The identity column of another database is spelled differently, so keep key
+  definitions in migration files, where a different provider's version of the file can differ.
+- SQLite lets a column hold a value of another type than it declares; most other databases do not. Store what you declare.
+
+## In tests
+
+A test opens its own database in memory, with the same migrations as production, and closes it:
+
+```ts
+import { afterEach, beforeEach, expect, test } from 'vitest'
+import { openDb } from 'acrylblends/db/sqlite'
+import { notesStore } from './db.ts'
+
+let close: () => Promise<void>
+let store: ReturnType<typeof notesStore>
+
+beforeEach(async () => {
+  const opened = await openDb({ path: ':memory:', migrations: 'migrations' })
+  close = opened.close
+  store = notesStore(opened.db)
+})
+afterEach(() => close())
+
+test('a new store has no notes', async () => {
+  expect(await store.titles(1)).toEqual([])
+})
+```
+
+## In production
+
+Open the database once at start, serve, and close it when the process is told to stop, after the server has stopped taking requests:
+
+```ts
+import { serve } from 'acrylblends/node-server'
+import { openDb } from 'acrylblends/db/sqlite'
+import { createApp } from './app.ts'
+
+const { db, close } = await openDb({ path: process.env.DATABASE_FILE ?? 'data/app.sqlite', migrations: 'migrations' })
+const server = serve({ fetch: createApp(db).fetch, port: Number(process.env.PORT ?? 3000) })
+
+process.once('SIGTERM', async () => {
+  server.close()
+  await close()
+})
+```
+
+`close` waits for the calls and the transaction that are running, flushes the write-ahead log into the main file, and releases the file, so a
+copy of `data/app.sqlite` made afterwards is complete. Keep the file on a disk that outlives a deploy; on a host with only an ephemeral disk the
+data goes with the machine.
+
+## Why the database is opened in one place
+
+Only one file of an app opens the database: the **opener** (`src/db.ts` in the templates). Every other file receives a `Db` as an argument and
+imports its type from `acrylblends/db`. Nothing outside the opener imports `node:sqlite`, `pg`, `postgres`, `@electric-sql/pglite` or another
+driver, or `acrylblends/db/sqlite` itself.
+
+Why it matters:
+
+- **Changing the database is one file.** Moving from SQLite to Postgres changes what the opener calls, and no route, store or test.
+- **A test opens its own database.** Code that opens a database by itself cannot be given an in-memory one, and a test that reaches the real file
+  breaks the next one.
+- **There is one place to close it.** The code that opened a database closes it; the port has no `close`, so a route cannot do it by mistake.
+- **An agent that adds a feature keeps the shape.** A coding agent asked for "tags" writes a migration and a store function, and has no reason to
+  reach for a driver when the interface is in front of it.
+
+The rule is checked, not hoped for. The app names its opener once, in `package.json`:
+
+```json
+{
+  "acryl": { "opener": "src/db.ts" }
+}
+```
+
+`acrylblends check-deps` reads every `.ts`, `.tsx` and `.js` file in `src/`, `test/`, `tests/` and `extensions/`, and fails when a file other than
+the opener imports a database driver, an opener such as `acrylblends/db/sqlite` or `acryl-db-sqlite`, or (outside `src/plugins/desktop`) `electron`.
+It names the file and the line:
+
+```
+src/routes.ts:3: "node:sqlite" is a database driver; take a Db (import type { Db } from "acrylblends/db") as an argument and let src/db.ts open the database
+```
+
+The `notes` and `chat` templates run it in `npm test` and `npm run check`. List more than one opener as an array (`"opener": ["src/db.ts", "src/app.ts"]`).
+In a Blend app, `acrylblends add db` declares `src/app.ts`, where the provider is mounted, and a plugin that declares `inject: ['db']` must not import
+`acryl-db-sqlite`: it receives `ctx.db`.
+
+## In a Cordis app
+
+An ACRYL app gets the same interface as a service. The `acryl-db-sqlite` plugin row opens the file (by default `data.sqlite` in the app home),
+applies the `migrations` folder, and provides `db`; a plugin declares `inject: ['db']` and imports the types only:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from 'acryl-db'
+
+export const name = 'notes'
+export const inject = ['db']
+
+export function apply(ctx: Context) {
+  void ctx.db.run('INSERT INTO notes (title) VALUES (?)', 'first')
+}
+```
+
+The plugin never imports a driver, so replacing the SQLite row by another provider is a change to the configuration.

package/docs/framework/guides/forms-and-sessions.md

@@ -3,31 +3,34 @@
 This page shows the parts a small multi-user app needs, in the order an app uses them: a database, passwords, a cookie session, HTML forms with server-side validation, and a JSON API that shares the same rules.
 It is the shape of a "Notes" app built from these docs alone (sign up, log in, create, edit, delete and search notes, a typed test client for the API).
 
-## A database with `node:sqlite`
-
-Node.js 22.19 and later include SQLite, so there is nothing to install. `DatabaseSync` is synchronous, which suits a small app.
+## A database with the `db` port
+
+`openDb` from `acrylblends/db/sqlite` opens a SQLite file (Node.js 22.19 and later include SQLite, so there is nothing to install), applies the SQL files in `migrations/`, and returns `{ db, close }`.
+Every call on `db` returns a promise, so `await` it. The [data guide](data.md) has the whole story: migrations, transactions, tests and shutdown.
+
+```sql
+-- migrations/001-notes.sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL
+);
+
+CREATE TABLE sessions (
+  token TEXT PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+);
+```
 
 ```ts
-import { DatabaseSync } from 'node:sqlite'
-
-export function openDb(path = process.env.NOTES_DB ?? 'notes.db'): DatabaseSync {
-  const db = new DatabaseSync(path)
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS users (
-      id INTEGER PRIMARY KEY,
-      email TEXT NOT NULL UNIQUE,
-      password_hash TEXT NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS sessions (
-      token TEXT PRIMARY KEY,
-      user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
-    );
-  `)
-  return db
+import { openDb } from 'acrylblends/db/sqlite'
+
+export function openNotesDb(path = process.env.NOTES_DB ?? 'data/notes.sqlite') {
+  return openDb({ path, migrations: 'migrations' })
 }
 ```
 
-Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then passes `openDb(':memory:')`, and importing the app module does not create a file.
+Take the database as an argument (`createApp(db)`) instead of opening it at import time. A test then opens `openNotesDb(':memory:')`, and importing the app module does not create a file.
 
 ## Passwords with `node:crypto`
 
@@ -63,20 +66,21 @@ import { Acryl } from 'acrylblends'
 import { createMiddleware } from 'acrylblends/factory'
 import { deleteCookie, getCookie, setCookie } from 'acrylblends/cookie'
 import { randomBytes } from 'node:crypto'
-import type { DatabaseSync } from 'node:sqlite'
+import type { Db } from 'acrylblends/db'
 
 type Env = { Variables: { user: { id: number; email: string } } }
 
-export function createApp(db: DatabaseSync) {
+export function createApp(db: Db) {
   const userFor = (token: string | undefined) =>
     token
-      ? (db
-          .prepare('SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?')
-          .get(token) as { id: number; email: string } | undefined)
+      ? db.get<{ id: number; email: string }>(
+          'SELECT users.id AS id, users.email AS email FROM sessions JOIN users ON users.id = sessions.user_id WHERE token = ?',
+          token
+        )
       : undefined
 
   const requireUser = createMiddleware<Env>(async (c, next) => {
-    const user = userFor(getCookie(c, 'sid'))
+    const user = await userFor(getCookie(c, 'sid'))
     if (!user) return c.redirect('/login')
     c.set('user', user)
     await next()
@@ -87,16 +91,16 @@ export function createApp(db: DatabaseSync) {
   app.use('/notes/*', requireUser)
   app.get('/notes', (c) => c.text(`Hello ${c.get('user').email}`))
 
-  app.post('/login-example', (c) => {
+  app.post('/login-example', async (c) => {
     const token = randomBytes(32).toString('hex')
-    db.prepare('INSERT INTO sessions (token, user_id) VALUES (?, ?)').run(token, 1)
+    await db.run('INSERT INTO sessions (token, user_id) VALUES (?, ?)', token, 1)
     setCookie(c, 'sid', token, { path: '/', httpOnly: true, sameSite: 'Lax', maxAge: 60 * 60 * 24 * 30 })
     return c.redirect('/notes', 303)
   })
 
-  app.post('/logout', (c) => {
+  app.post('/logout', async (c) => {
     const token = getCookie(c, 'sid')
-    if (token) db.prepare('DELETE FROM sessions WHERE token = ?').run(token)
+    if (token) await db.run('DELETE FROM sessions WHERE token = ?', token)
     deleteCookie(c, 'sid', { path: '/' })
     return c.redirect('/login', 303)
   })

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
+    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
   },
-  "files": 98,
-  "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
+  "files": 99,
+  "digest": "sha256:2ff7cb6e36f1a04caece3bc14736ff23fd6eb2f86752453255973344e3344a0a"
 }

package/lib/db/sqlite.d.ts

@@ -0,0 +1,27 @@
+import { c as DbExecutor, l as SqlValue, s as Db } from "../index-D4FAsBZu.js";
+
+//#region ../../plugins/acryl-db-sqlite/src/open.d.ts
+interface OpenDbOptions {
+  /** The database file, its folder created if missing; `:memory:` for a database that lives until `close`. */
+  readonly path: string;
+  /** A folder of `NNN-name.sql` files numbered from 1, as a path or a file URL, applied in order before `openDb` resolves. */
+  readonly migrations?: string | URL;
+  /** How long SQLite waits for a competing file lock, in milliseconds. Defaults to 5000. */
+  readonly busyTimeoutMs?: number;
+  /** The WAL auto-checkpoint threshold in pages; 0 disables it. Defaults to 1000. */
+  readonly walAutoCheckpointPages?: number;
+}
+/** An open database: the port, and the one function that closes it. */
+interface OpenDb {
+  readonly db: Db;
+  /** Waits for running operations and transactions, checkpoints the WAL and releases the file. Calling it again does nothing. */
+  close(): Promise<void>;
+}
+/**
+ * Open, configure and migrate a SQLite database.
+ * @throws when the migration files are misnamed or misnumbered, or a migration fails (the file is closed, and unchanged), or the
+ *   database's schema is newer than the migrations.
+ */
+declare function openDb(options: OpenDbOptions): Promise<OpenDb>;
+//#endregion
+export { type Db, type DbExecutor, OpenDb, OpenDbOptions, type SqlValue, openDb };

package/lib/db/sqlite.js

@@ -0,0 +1,197 @@
+import { i as applyMigrations, n as MIGRATIONS_TABLE, r as readMigrationFiles } from "../src-MWcsMS8i.js";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+//#region ../../plugins/acryl-db-sqlite/src/facade/node.ts
+const DEFAULT_WAL_AUTO_CHECKPOINT_PAGES = 1e3;
+const DEFAULT_BUSY_TIMEOUT_MS = 5e3;
+const ignore = () => {};
+/**
+* Runs operations in call order. An operation starts immediately when nothing is running or waiting;
+* otherwise it waits for everything before it. An asynchronous operation holds the queue until it settles.
+*/
+var SerialOperationQueue = class {
+	tail = Promise.resolve();
+	pending = 0;
+	run(operation) {
+		if (this.pending > 0) return this.enqueue(operation);
+		try {
+			return Promise.resolve(operation());
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+	runAsync(operation) {
+		if (this.pending > 0) return this.enqueue(operation);
+		this.pending++;
+		const { promise: barrier, resolve: releaseBarrier } = Promise.withResolvers();
+		this.tail = barrier;
+		let started;
+		try {
+			started = operation();
+		} catch (error) {
+			started = Promise.reject(error);
+		}
+		return started.finally(() => {
+			this.pending--;
+			releaseBarrier();
+		});
+	}
+	enqueue(operation) {
+		this.pending++;
+		return this.release(this.tail.then(operation));
+	}
+	release(operation) {
+		const settled = operation.finally(() => {
+			this.pending--;
+		});
+		this.tail = settled.then(ignore, ignore);
+		return settled;
+	}
+};
+/**
+* Executes SQL on one connection. Prepared statements are cached per connection by SQL text, so the
+* database and its transaction handles share them across transactions.
+*/
+var NodeSqliteExecutor = class {
+	database;
+	statements;
+	constructor(database, statements) {
+		this.database = database;
+		this.statements = statements;
+	}
+	exec(sql) {
+		return this.runOperation(() => {
+			this.database.exec(sql);
+		});
+	}
+	run(sql, ...params) {
+		return this.runOperation(() => ({ changes: Number(this.statement(sql).run(...params).changes) }));
+	}
+	get(sql, ...params) {
+		return this.runOperation(() => this.statement(sql).get(...params));
+	}
+	all(sql, ...params) {
+		return this.runOperation(() => this.statement(sql).all(...params));
+	}
+	statement(sql) {
+		let statement = this.statements.get(sql);
+		if (statement === void 0) {
+			statement = this.database.prepare(sql);
+			this.statements.set(sql, statement);
+		}
+		return statement;
+	}
+};
+var NodeSqliteTransaction = class extends NodeSqliteExecutor {
+	scope;
+	constructor(database, statements, scope) {
+		super(database, statements);
+		this.scope = scope;
+	}
+	async runOperation(operation) {
+		if (!this.scope.active) throw new Error("SQLite transaction handle is no longer active");
+		return operation();
+	}
+};
+/** `Db` adapter backed by Node's built-in `node:sqlite`. */
+var NodeSqliteDatabase = class extends NodeSqliteExecutor {
+	access = new SerialOperationQueue();
+	closed = false;
+	constructor(database) {
+		super(database, /* @__PURE__ */ new Map());
+	}
+	transaction(callback) {
+		return this.access.runAsync(async () => {
+			this.database.exec("BEGIN IMMEDIATE");
+			const scope = { active: true };
+			try {
+				const result = await callback(new NodeSqliteTransaction(this.database, this.statements, scope));
+				scope.active = false;
+				this.database.exec("COMMIT");
+				return result;
+			} catch (error) {
+				scope.active = false;
+				try {
+					this.database.exec("ROLLBACK");
+				} catch (rollbackError) {
+					throw new AggregateError([error, rollbackError], "SQLite transaction failed and rollback failed");
+				}
+				throw error;
+			}
+		});
+	}
+	close() {
+		return this.access.run(() => {
+			if (this.closed) return;
+			this.closed = true;
+			this.statements.clear();
+			try {
+				this.database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+			} finally {
+				this.database.close();
+			}
+		});
+	}
+	runOperation(operation) {
+		return this.access.run(operation);
+	}
+};
+/** Open and configure a Node-backed SQLite database facade. */
+async function openNodeSqliteDatabase(path, options = {}) {
+	const checkpointPages = options.walAutoCheckpointPages ?? DEFAULT_WAL_AUTO_CHECKPOINT_PAGES;
+	const timeout = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+	if (path !== ":memory:") await mkdir(dirname(path), { recursive: true });
+	const adapter = new NodeSqliteDatabase(new DatabaseSync(path, { timeout }));
+	try {
+		await adapter.exec("PRAGMA journal_mode = WAL");
+		await adapter.exec("PRAGMA synchronous = NORMAL");
+		await adapter.exec(`PRAGMA wal_autocheckpoint = ${checkpointPages}`);
+		return adapter;
+	} catch (error) {
+		try {
+			await adapter.close();
+		} catch {}
+		throw error;
+	}
+}
+//#endregion
+//#region ../../plugins/acryl-db-sqlite/src/open.ts
+/**
+* The plain way to open the SQLite provider, for code without Cordis (an acrylblends app): `openDb({ path, migrations })` opens one
+* `node:sqlite` file with the ported facade's settings (WAL, `synchronous = NORMAL`, a busy timeout) and foreign keys enforced, applies the
+* numbered migrations, and resolves the `db` port with the function that closes it. The Cordis plugin is a thin wrapper over this, so both
+* run one code path.
+* This entry imports nothing from Cordis.
+*/
+/**
+* Open, configure and migrate a SQLite database.
+* @throws when the migration files are misnamed or misnumbered, or a migration fails (the file is closed, and unchanged), or the
+*   database's schema is newer than the migrations.
+*/
+async function openDb(options) {
+	const migrations = options.migrations === void 0 ? [] : await readMigrationFiles(options.migrations);
+	const database = await openNodeSqliteDatabase(options.path, {
+		...options.busyTimeoutMs === void 0 ? {} : { busyTimeoutMs: options.busyTimeoutMs },
+		...options.walAutoCheckpointPages === void 0 ? {} : { walAutoCheckpointPages: options.walAutoCheckpointPages }
+	});
+	try {
+		await database.exec("PRAGMA foreign_keys = ON");
+		await applyMigrations(database, migrations, { table: MIGRATIONS_TABLE });
+	} catch (error) {
+		await database.close();
+		throw error;
+	}
+	return {
+		db: {
+			exec: (sql) => database.exec(sql),
+			run: (sql, ...params) => database.run(sql, ...params),
+			get: (sql, ...params) => database.get(sql, ...params),
+			all: (sql, ...params) => database.all(sql, ...params),
+			transaction: (work) => database.transaction(work)
+		},
+		close: () => database.close()
+	};
+}
+//#endregion
+export { openDb };

package/lib/db.d.ts

@@ -0,0 +1,2 @@
+import { a as Migration, c as DbExecutor, i as validateSchemaPrefix, l as SqlValue, n as MIGRATIONS_TABLE, o as applyMigrations, r as readMigrationFiles, s as Db, t as DB_SERVICE } from "./index-D4FAsBZu.js";
+export { DB_SERVICE, type Db, type DbExecutor, MIGRATIONS_TABLE, type Migration, type SqlValue, applyMigrations, readMigrationFiles, validateSchemaPrefix };

package/lib/db.js

@@ -0,0 +1,2 @@
+import { a as validateSchemaPrefix, i as applyMigrations, n as MIGRATIONS_TABLE, r as readMigrationFiles, t as DB_SERVICE } from "./src-MWcsMS8i.js";
+export { DB_SERVICE, MIGRATIONS_TABLE, applyMigrations, readMigrationFiles, validateSchemaPrefix };