acrylblends 0.7.6 → 0.7.7

package/lib/database-D_UN6We8.d.ts

@@ -0,0 +1,44 @@
+//#region ../../plugins/acryl-db/lib/types/facade/database.d.ts
+/** Values supported by the portable SQL drivers. */
+type SqlValue = null | number | bigint | string | Uint8Array;
+/**
+ * Asynchronous SQL operations shared by a database and its transaction handles.
+ *
+ * `exec` runs SQL text without bindings and may contain several statements. `run`, `get`, and `all`
+ * execute one statement with positional bindings. Adapters may cache prepared statements by SQL text,
+ * so callers pass values as bindings instead of interpolating them. `run` resolves the number of rows
+ * the statement changed.
+ */
+interface DbExecutor {
+  exec(sql: string): Promise<void>;
+  run(sql: string, ...params: SqlValue[]): Promise<{
+    readonly changes: number;
+  }>;
+  get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined>;
+  all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]>;
+}
+/**
+ * Minimal portable SQL database facade.
+ *
+ * All operations are asynchronous so adapters may execute outside the caller's runtime.
+ *
+ * `transaction` passes the callback a transaction handle. All work in the transaction
+ * must use that handle; the handle is invalid after the callback settles. Adapters must
+ * queue unrelated operations and other transactions until the transaction finishes. The
+ * returned promise settles after commit or rollback. Calling the database itself (including
+ * `transaction`) from inside a callback therefore waits for that transaction and
+ * never settles.
+ *
+ * When the callback rejects, the adapter must roll the transaction back before rejecting
+ * with that same error. If rollback fails, it must reject with a different error (for
+ * example an `AggregateError`) so callers cannot mistake the callback error for a
+ * guaranteed rollback.
+ *
+ * Closing is the adapter's: the plugin that opened a database closes it, so the facade an
+ * app receives has no `close`.
+ */
+interface Db extends DbExecutor {
+  transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
+}
+//#endregion
+export { DbExecutor as n, SqlValue as r, Db as t };

package/lib/db/sqlite.d.ts

@@ -1,4 +1,4 @@
-import { c as DbExecutor, l as SqlValue, s as Db } from "../index-D4FAsBZu.js";
+import { n as DbExecutor, r as SqlValue, t as Db } from "../database-D_UN6We8.js";
 
 //#region ../../plugins/acryl-db-sqlite/src/open.d.ts
 interface OpenDbOptions {

package/lib/db.d.ts

@@ -1,2 +1,85 @@
-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";
+//#region ../../plugins/acryl-db/src/facade/database.d.ts
+/** Values supported by the portable SQL drivers. */
+type SqlValue = null | number | bigint | string | Uint8Array;
+/**
+ * Asynchronous SQL operations shared by a database and its transaction handles.
+ *
+ * `exec` runs SQL text without bindings and may contain several statements. `run`, `get`, and `all`
+ * execute one statement with positional bindings. Adapters may cache prepared statements by SQL text,
+ * so callers pass values as bindings instead of interpolating them. `run` resolves the number of rows
+ * the statement changed.
+ */
+interface DbExecutor {
+  exec(sql: string): Promise<void>;
+  run(sql: string, ...params: SqlValue[]): Promise<{
+    readonly changes: number;
+  }>;
+  get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined>;
+  all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]>;
+}
+/**
+ * Minimal portable SQL database facade.
+ *
+ * All operations are asynchronous so adapters may execute outside the caller's runtime.
+ *
+ * `transaction` passes the callback a transaction handle. All work in the transaction
+ * must use that handle; the handle is invalid after the callback settles. Adapters must
+ * queue unrelated operations and other transactions until the transaction finishes. The
+ * returned promise settles after commit or rollback. Calling the database itself (including
+ * `transaction`) from inside a callback therefore waits for that transaction and
+ * never settles.
+ *
+ * When the callback rejects, the adapter must roll the transaction back before rejecting
+ * with that same error. If rollback fails, it must reject with a different error (for
+ * example an `AggregateError`) so callers cannot mistake the callback error for a
+ * guaranteed rollback.
+ *
+ * Closing is the adapter's: the plugin that opened a database closes it, so the facade an
+ * app receives has no `close`.
+ */
+interface Db extends DbExecutor {
+  transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region ../../plugins/acryl-db/src/facade/migrations.d.ts
+type Migration = {
+  readonly version: number;
+  readonly statements: readonly string[];
+};
+/**
+ * Apply all pending migrations atomically, tracking their version in the named metadata table.
+ *
+ * The bookkeeping SQL runs unchanged on SQLite and Postgres: no `STRICT` table, `ON CONFLICT DO NOTHING`
+ * instead of `INSERT OR IGNORE`, and the version written as a checked integer rather than a binding,
+ * since the two dialects spell placeholders differently.
+ */
+declare function applyMigrations(database: Db, migrations: readonly Migration[], options: {
+  readonly table: string;
+}): Promise<void>;
+//#endregion
+//#region ../../plugins/acryl-db/src/facade/schema.d.ts
+/** Validate a prefix before using it as part of a SQL identifier. */
+declare function validateSchemaPrefix(prefix: string): void;
+//#endregion
+//#region ../../plugins/acryl-db/src/migration-files.d.ts
+/**
+ * Read every `NNN-name.sql` file of a folder, in number order.
+ * @throws when a `.sql` file is not named `NNN-name.sql`, or the numbers do not run 1, 2, 3, ... without gaps or repeats.
+ */
+declare function readMigrationFiles(folder: string | URL): Promise<Migration[]>;
+//#endregion
+//#region ../../plugins/acryl-db/src/index.d.ts
+/**
+ * The `db` port: what an app's code sees of its relational database, whichever provider (`acryl-db-sqlite`, `acryl-db-postgres`) serves
+ * it. Plain code (an acrylblends app) opens a database with a provider's `openDb`; a Cordis plugin declares `inject: ['db']`, imports
+ * `acryl-db/cordis` for the `ctx.db` type, and never imports a driver.
+ *
+ * Bindings are positional `?` placeholders on every provider; a provider whose database spells them differently translates them.
+ * This entry imports nothing from Cordis, at runtime or in its types.
+ */
+/** The service name every `db` provider registers. */
+declare const DB_SERVICE = "db";
+/** The table that records an app's migration version. */
+declare const MIGRATIONS_TABLE = "_migrations";
+//#endregion
 export { DB_SERVICE, type Db, type DbExecutor, MIGRATIONS_TABLE, type Migration, type SqlValue, applyMigrations, readMigrationFiles, validateSchemaPrefix };

package/lib/kv/db.d.ts

@@ -0,0 +1,12 @@
+import { t as Db } from "../database-D_UN6We8.js";
+import { t as Kv } from "../kv-DWDm0Lja.js";
+
+//#region ../../plugins/acryl-kv-db/src/open.d.ts
+interface KvOnDbOptions {
+  /** The table that holds the documents. Defaults to `kv`; a plain SQL identifier. */
+  readonly table?: string;
+}
+/** The `kv` port over a `db`. It does not own the database: whoever opened it closes it, and calls after that reject. */
+declare function kvOnDb(db: Db, options?: KvOnDbOptions): Kv;
+//#endregion
+export { type Kv, KvOnDbOptions, kvOnDb };

package/lib/kv/db.js

@@ -0,0 +1,57 @@
+import { a as compareKeys, c as runChange, i as codePoints, o as decodeValue, r as checkKey, s as encodeValue } from "../src-DRFVEQQb.js";
+//#region ../../plugins/acryl-kv-db/src/open.ts
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/u;
+/** The `kv` port over a `db`. It does not own the database: whoever opened it closes it, and calls after that reject. */
+function kvOnDb(db, options = {}) {
+	const table = options.table ?? "kv";
+	if (!IDENTIFIER.test(table)) throw new TypeError(`acryl-kv-db: the table name must be a plain lower case SQL identifier, got ${JSON.stringify(table)}`);
+	let ready;
+	const ensure = () => {
+		ready ??= db.exec(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL)`).catch((error) => {
+			ready = void 0;
+			throw error;
+		});
+		return ready;
+	};
+	/**
+	* Run a statement after the table exists. The table's statement and this one are both handed to the database at once (its queue keeps
+	* their order), so a `close()` called right after a write cannot slip between them and leave the write on a closed database.
+	*/
+	const after = async (work) => {
+		const created = ensure();
+		const result = work();
+		const [, value] = await Promise.all([created, result]);
+		return value;
+	};
+	const upsert = `INSERT INTO ${table} (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`;
+	return {
+		async get(key) {
+			checkKey(key);
+			const row = await after(() => db.get(`SELECT value FROM ${table} WHERE key = ?`, key));
+			return row === void 0 ? void 0 : decodeValue(row.value);
+		},
+		async set(key, value) {
+			checkKey(key);
+			const text = encodeValue(value);
+			await after(() => db.run(upsert, key, text));
+		},
+		async update(key, change) {
+			checkKey(key);
+			return after(() => db.transaction(async (tx) => {
+				const row = await tx.get(`SELECT value FROM ${table} WHERE key = ?`, key);
+				const text = encodeValue(runChange(change, row === void 0 ? void 0 : decodeValue(row.value)));
+				await tx.run(upsert, key, text);
+				return decodeValue(text);
+			}));
+		},
+		async delete(key) {
+			checkKey(key);
+			await after(() => db.run(`DELETE FROM ${table} WHERE key = ?`, key));
+		},
+		async list(prefix = "") {
+			return (await after(() => prefix === "" ? db.all(`SELECT key FROM ${table}`) : db.all(`SELECT key FROM ${table} WHERE substr(key, 1, ?) = ?`, codePoints(prefix), prefix))).map((row) => row.key).sort(compareKeys);
+		}
+	};
+}
+//#endregion
+export { kvOnDb };

package/lib/kv/json.d.ts

@@ -0,0 +1,11 @@
+import { n as KvOpened, t as Kv } from "../kv-DWDm0Lja.js";
+
+//#region ../../plugins/acryl-kv-json/src/open.d.ts
+interface OpenKvOptions {
+  /** The JSON file; its folder is created if missing. */
+  readonly path: string;
+}
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+declare function openKv(options: OpenKvOptions): Promise<KvOpened>;
+//#endregion
+export { type Kv, type KvOpened, OpenKvOptions, openKv };

package/lib/kv/json.js

@@ -0,0 +1,161 @@
+import { a as compareKeys, c as runChange, o as decodeValue, r as checkKey, s as encodeValue } from "../src-DRFVEQQb.js";
+import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+//#region ../../plugins/acryl-kv-json/src/open.ts
+/**
+* The plain way to open the JSON-file provider, for code without Cordis (an acrylblends app): `openKv({ path })` reads one JSON file into
+* memory and resolves the `kv` 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.
+*
+* Every write queues behind the writes before it and persists the whole map: serialize to a temporary file in the same folder, flush it,
+* rename it over the file, and flush the folder where the platform allows. The call resolves after the rename, so a crash leaves the old file
+* or the new one, never half of one. One process owns the file: two writers would overwrite each other.
+*/
+/** The file's own format version, for a later change of layout. */
+const FORMAT = 1;
+/** Stray temporary files from a crash end in `.tmp` and start with the file's name. */
+const tempPrefix = (file) => `${basename(file)}.`;
+/** The file content for a map of key to JSON text, keys in code point order, so the same data is the same bytes. */
+function serialize(entries) {
+	const body = [...entries.keys()].sort(compareKeys).map((key) => `${JSON.stringify(key)}:${entries.get(key)}`).join(",");
+	return `{"version":${FORMAT},"entries":{${body}}}\n`;
+}
+function unreadable(file, reason) {
+	return /* @__PURE__ */ new Error(`acryl-kv-json: ${file} is not a readable kv file (${reason}); it was not changed`);
+}
+/** The entries of a file, or none when it does not exist. A file that exists and does not parse is an error: it is never started over. */
+async function load(file) {
+	let text;
+	try {
+		text = await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+		throw error;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw unreadable(file, error.message);
+	}
+	if (typeof parsed !== "object" || parsed === null || parsed.version !== FORMAT) throw unreadable(file, "not a version 1 kv file");
+	const entries = parsed.entries;
+	if (typeof entries !== "object" || entries === null || Array.isArray(entries)) throw unreadable(file, "no entries object");
+	return new Map(Object.entries(entries).map(([key, value]) => [key, JSON.stringify(value)]));
+}
+/** Remove the temporary files an earlier crash left beside the file. */
+async function removeStrays(file) {
+	const prefix = tempPrefix(file);
+	for (const name of await readdir(dirname(file))) if (name.startsWith(prefix) && name.endsWith(".tmp")) await rm(join(dirname(file), name), { force: true });
+}
+const RENAME_RETRIES = 8;
+/** Rename over the target. Windows refuses while a scanner or an indexer holds the target for a moment, so it is retried briefly. */
+async function replace(from, to) {
+	for (let attempt = 0;; attempt += 1) try {
+		await rename(from, to);
+		return;
+	} catch (error) {
+		const code = error.code;
+		if (attempt >= RENAME_RETRIES || code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw error;
+		await new Promise((resolveWait) => setTimeout(resolveWait, 10 * (attempt + 1)));
+	}
+}
+/** Flush the folder entry of a renamed file (POSIX); Windows cannot open a folder, and a filesystem that refuses is no worse than before. */
+async function flushFolder(folder) {
+	if (process.platform === "win32") return;
+	try {
+		const handle = await open(folder, "r");
+		try {
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+	} catch {}
+}
+/** Open (and create, when missing) a JSON-file store. @throws when the file exists and is not a readable kv file. */
+async function openKv(options) {
+	const file = resolve(options.path);
+	await mkdir(dirname(file), { recursive: true });
+	await removeStrays(file);
+	let state = await load(file);
+	let closed = false;
+	let sequence = 0;
+	let tail = Promise.resolve();
+	const guard = () => {
+		if (closed) throw new Error(`acryl-kv-json: ${file} is closed`);
+	};
+	/** Persist a map: the file is the old one or this one, never between. */
+	const persist = async (next) => {
+		sequence += 1;
+		const temp = join(dirname(file), `${tempPrefix(file)}${process.pid}.${sequence}.tmp`);
+		try {
+			const handle = await open(temp, "w");
+			try {
+				await handle.writeFile(serialize(next), "utf8");
+				await handle.sync();
+			} finally {
+				await handle.close();
+			}
+			await replace(temp, file);
+		} catch (error) {
+			await rm(temp, { force: true });
+			throw error;
+		}
+		await flushFolder(dirname(file));
+	};
+	/** Run a change after every earlier one; the map it works on becomes the state only once it is on disk. */
+	const write = (change) => {
+		guard();
+		const task = tail.then(async () => {
+			const draft = new Map(state);
+			const result = change(draft);
+			await persist(draft);
+			state = draft;
+			return result;
+		});
+		tail = task.catch(() => void 0);
+		return task;
+	};
+	return {
+		kv: {
+			async get(key) {
+				guard();
+				checkKey(key);
+				const text = state.get(key);
+				return text === void 0 ? void 0 : decodeValue(text);
+			},
+			async set(key, value) {
+				checkKey(key);
+				const text = encodeValue(value);
+				await write((draft) => {
+					draft.set(key, text);
+				});
+			},
+			async update(key, change) {
+				checkKey(key);
+				return write((draft) => {
+					const text = draft.get(key);
+					const encoded = encodeValue(runChange(change, text === void 0 ? void 0 : decodeValue(text)));
+					draft.set(key, encoded);
+					return decodeValue(encoded);
+				});
+			},
+			async delete(key) {
+				checkKey(key);
+				await write((draft) => {
+					draft.delete(key);
+				});
+			},
+			async list(prefix = "") {
+				guard();
+				return [...state.keys()].filter((key) => key.startsWith(prefix)).sort(compareKeys);
+			}
+		},
+		close: async () => {
+			closed = true;
+			await tail;
+		}
+	};
+}
+//#endregion
+export { openKv };

package/lib/kv-DWDm0Lja.d.ts

@@ -0,0 +1,39 @@
+//#region ../../plugins/acryl-kv/lib/types/kv.d.ts
+/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
+type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
+/** Anything JSON can hold. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Named JSON documents. Every call returns a promise, so a file, SQLite and Postgres answer alike.
+ *
+ * Keys are non-empty strings. Values are JSON: `undefined`, functions, symbols, bigints and non-finite numbers are refused with a
+ * `TypeError` before anything is written, and a value read back is a copy.
+ *
+ * There is no `close`: the code that opened a store closes it (see {@link KvOpened}), so a plugin cannot close the store another uses.
+ */
+interface Kv {
+  /** The value stored under the key, or `undefined`. */
+  get<T = JsonValue>(key: string): Promise<T | undefined>;
+  /** Store a value under the key, replacing any. Resolves once it is durable. */
+  set<T = JsonValue>(key: string, value: T): Promise<void>;
+  /**
+   * Replace the value under the key by `change(current)`, atomically: `current` is `undefined` when the key is missing, `change` is
+   * synchronous (an `async` function is a type error, and a returned promise is rejected at run time: read what you need first, then update), and no other write to the key happens between reading it and writing the result. Resolves the new value. A `change` that
+   * throws, or returns something that is not JSON, leaves the value as it was and rejects with its error.
+   */
+  update<T = JsonValue>(key: string, change: (current: T | undefined) => NotPromise<T>): Promise<T>;
+  /** Remove the key. A missing key is not an error. */
+  delete(key: string): Promise<void>;
+  /** The keys that start with the prefix (all of them without one), sorted by code point (the order of their UTF-8 bytes, not of UTF-16 units). */
+  list(prefix?: string): Promise<string[]>;
+}
+/** An open store and the one function that closes it. */
+interface KvOpened {
+  readonly kv: Kv;
+  /** Waits for the writes in flight, then releases the storage. Calling it again does nothing; calls on `kv` after it reject. */
+  close(): Promise<void>;
+}
+//#endregion
+export { KvOpened as n, Kv as t };

package/lib/kv.d.ts

@@ -0,0 +1,93 @@
+//#region ../../plugins/acryl-kv/src/kv.d.ts
+/** `T`, except a promise: the callback of `update` is synchronous, and an async one is a type error. */
+type NotPromise<T> = T extends PromiseLike<unknown> ? never : T;
+/** Anything JSON can hold. */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Named JSON documents. Every call returns a promise, so a file, SQLite and Postgres answer alike.
+ *
+ * Keys are non-empty strings. Values are JSON: `undefined`, functions, symbols, bigints and non-finite numbers are refused with a
+ * `TypeError` before anything is written, and a value read back is a copy.
+ *
+ * There is no `close`: the code that opened a store closes it (see {@link KvOpened}), so a plugin cannot close the store another uses.
+ */
+interface Kv {
+  /** The value stored under the key, or `undefined`. */
+  get<T = JsonValue>(key: string): Promise<T | undefined>;
+  /** Store a value under the key, replacing any. Resolves once it is durable. */
+  set<T = JsonValue>(key: string, value: T): Promise<void>;
+  /**
+   * Replace the value under the key by `change(current)`, atomically: `current` is `undefined` when the key is missing, `change` is
+   * synchronous (an `async` function is a type error, and a returned promise is rejected at run time: read what you need first, then update), and no other write to the key happens between reading it and writing the result. Resolves the new value. A `change` that
+   * throws, or returns something that is not JSON, leaves the value as it was and rejects with its error.
+   */
+  update<T = JsonValue>(key: string, change: (current: T | undefined) => NotPromise<T>): Promise<T>;
+  /** Remove the key. A missing key is not an error. */
+  delete(key: string): Promise<void>;
+  /** The keys that start with the prefix (all of them without one), sorted by code point (the order of their UTF-8 bytes, not of UTF-16 units). */
+  list(prefix?: string): Promise<string[]>;
+}
+/** An open store and the one function that closes it. */
+interface KvOpened {
+  readonly kv: Kv;
+  /** Waits for the writes in flight, then releases the storage. Calling it again does nothing; calls on `kv` after it reject. */
+  close(): Promise<void>;
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/check.d.ts
+/**
+ * What every `kv` provider checks the same way, so a bad call fails alike on a file and on SQL: the key, the value, and the order of keys.
+ */
+/** A key is a non-empty string. */
+declare function checkKey(key: unknown): asserts key is string;
+/**
+ * The JSON text of a value. `undefined`, functions, symbols, bigints, circular structures and non-finite numbers (which JSON would turn
+ * into `null`) are refused with a `TypeError`; nothing is stored for them.
+ */
+declare function encodeValue(value: unknown): string;
+/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
+declare function decodeValue<T>(text: string): T;
+/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
+declare function compareKeys(a: string, b: string): number;
+/** The number of code points in a string (what SQL's `substr` counts). */
+declare function codePoints(text: string): number;
+/**
+ * Call an `update` callback and check what it returns: the callback is synchronous, so a promise (an `async` function the types should have
+ * refused) is rejected with a message that says what to do, instead of being stored as `{}`.
+ */
+declare function runChange<T>(change: (current: T | undefined) => T, current: T | undefined): T;
+//#endregion
+//#region ../../plugins/acryl-kv/src/copy.d.ts
+interface CopyKvOptions {
+  /** Replace keys the target already has. Without it, a shared key stops the copy before anything is written. */
+  readonly overwrite?: boolean;
+  /** Copy only the keys that start with this. */
+  readonly prefix?: string;
+}
+interface CopyKvResult {
+  /** Keys written to the target. */
+  readonly copied: number;
+  /** Of those, keys the target already had. */
+  readonly overwritten: number;
+}
+/**
+ * Copy every key of one store into another: the import when an app moves from a JSON file to SQL (the file opened with
+ * `acryl-kv-json` is the source, `kvOnDb` the target). The source is not changed.
+ * @throws when the target has a key the source has and `overwrite` is not set; nothing is written then.
+ */
+declare function copyKv(source: Kv, target: Kv, options?: CopyKvOptions): Promise<CopyKvResult>;
+//#endregion
+//#region ../../plugins/acryl-kv/src/index.d.ts
+/**
+ * The `kv` port: named JSON documents for an app too small for SQL, whichever provider serves it (`acryl-kv-json` for one file,
+ * `acryl-kv-db` over the `db` port). Plain code opens a store with a provider's `openKv`; a Cordis plugin declares `inject: ['kv']`, imports
+ * `acryl-kv/cordis` for the `ctx.kv` type, and never imports a provider.
+ *
+ * This entry imports nothing from Cordis, at runtime or in its types.
+ */
+/** The service name every `kv` provider registers. */
+declare const KV_SERVICE = "kv";
+//#endregion
+export { type CopyKvOptions, type CopyKvResult, type JsonValue, KV_SERVICE, type Kv, type KvOpened, type NotPromise, checkKey, codePoints, compareKeys, copyKv, decodeValue, encodeValue, runChange };

package/lib/kv.js

@@ -0,0 +1,2 @@
+import { a as compareKeys, c as runChange, i as codePoints, n as copyKv, o as decodeValue, r as checkKey, s as encodeValue, t as KV_SERVICE } from "./src-DRFVEQQb.js";
+export { KV_SERVICE, checkKey, codePoints, compareKeys, copyKv, decodeValue, encodeValue, runChange };

package/lib/src-DRFVEQQb.js

@@ -0,0 +1,90 @@
+//#region ../../plugins/acryl-kv/src/check.ts
+/**
+* What every `kv` provider checks the same way, so a bad call fails alike on a file and on SQL: the key, the value, and the order of keys.
+*/
+/** A key is a non-empty string. */
+function checkKey(key) {
+	if (typeof key !== "string" || key === "") throw new TypeError(`a kv key is a non-empty string, got ${typeof key === "string" ? "an empty string" : typeof key}`);
+}
+/**
+* The JSON text of a value. `undefined`, functions, symbols, bigints, circular structures and non-finite numbers (which JSON would turn
+* into `null`) are refused with a `TypeError`; nothing is stored for them.
+*/
+function encodeValue(value) {
+	const text = JSON.stringify(value, (_key, part) => {
+		if (typeof part === "number" && !Number.isFinite(part)) throw new TypeError(`a kv value is JSON; ${String(part)} is not`);
+		return part;
+	});
+	if (text === void 0) throw new TypeError(`a kv value is JSON; ${typeof value} is not`);
+	return text;
+}
+/** The value of stored JSON text: a new copy each time, so changing what `get` returned changes nothing stored. */
+function decodeValue(text) {
+	return JSON.parse(text);
+}
+/** Order two keys by code point (the order of UTF-8 bytes, which SQLite's binary collation and Postgres' "C" collation give too). */
+function compareKeys(a, b) {
+	if (a === b) return 0;
+	const rank = (unit) => unit >= 55296 ? unit >= 57344 ? unit - 2048 : unit + 8192 : unit;
+	const length = Math.min(a.length, b.length);
+	for (let index = 0; index < length; index += 1) {
+		const difference = rank(a.charCodeAt(index)) - rank(b.charCodeAt(index));
+		if (difference !== 0) return difference;
+	}
+	return a.length - b.length;
+}
+/** The number of code points in a string (what SQL's `substr` counts). */
+function codePoints(text) {
+	let count = 0;
+	for (const _ of text) count += 1;
+	return count;
+}
+/**
+* Call an `update` callback and check what it returns: the callback is synchronous, so a promise (an `async` function the types should have
+* refused) is rejected with a message that says what to do, instead of being stored as `{}`.
+*/
+function runChange(change, current) {
+	const next = change(current);
+	if (typeof next === "object" && next !== null && typeof next.then === "function") throw new TypeError("the callback of kv.update is synchronous and returned a promise: read what you need first (await kv.get), then update with a plain function");
+	return next;
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/copy.ts
+/**
+* Copy every key of one store into another: the import when an app moves from a JSON file to SQL (the file opened with
+* `acryl-kv-json` is the source, `kvOnDb` the target). The source is not changed.
+* @throws when the target has a key the source has and `overwrite` is not set; nothing is written then.
+*/
+async function copyKv(source, target, options = {}) {
+	const keys = await source.list(options.prefix);
+	const existing = new Set(await target.list(options.prefix));
+	const shared = keys.filter((key) => existing.has(key));
+	if (shared.length > 0 && options.overwrite !== true) {
+		const shown = shared.slice(0, 5).map((key) => JSON.stringify(key)).join(", ");
+		throw new Error(`copyKv: the target already has ${shared.length} of these keys (${shown}${shared.length > 5 ? ", ..." : ""}); pass overwrite to replace them`);
+	}
+	let copied = 0;
+	for (const key of keys) {
+		const value = await source.get(key);
+		if (value === void 0) continue;
+		await target.set(key, value);
+		copied += 1;
+	}
+	return {
+		copied,
+		overwritten: shared.length
+	};
+}
+//#endregion
+//#region ../../plugins/acryl-kv/src/index.ts
+/**
+* The `kv` port: named JSON documents for an app too small for SQL, whichever provider serves it (`acryl-kv-json` for one file,
+* `acryl-kv-db` over the `db` port). Plain code opens a store with a provider's `openKv`; a Cordis plugin declares `inject: ['kv']`, imports
+* `acryl-kv/cordis` for the `ctx.kv` type, and never imports a provider.
+*
+* This entry imports nothing from Cordis, at runtime or in its types.
+*/
+/** The service name every `kv` provider registers. */
+const KV_SERVICE = "kv";
+//#endregion
+export { compareKeys as a, runChange as c, codePoints as i, copyKv as n, decodeValue as o, checkKey as r, encodeValue as s, KV_SERVICE as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -426,6 +426,18 @@
       "types": "./lib/db/sqlite.d.ts",
       "default": "./lib/db/sqlite.js"
     },
+    "./kv": {
+      "types": "./lib/kv.d.ts",
+      "default": "./lib/kv.js"
+    },
+    "./kv/json": {
+      "types": "./lib/kv/json.d.ts",
+      "default": "./lib/kv/json.js"
+    },
+    "./kv/db": {
+      "types": "./lib/kv/db.d.ts",
+      "default": "./lib/kv/db.js"
+    },
     "./package.json": "./package.json",
     "./cli": {
       "types": "./dist/index.d.ts",

package/plugins/acryl-db/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",

package/plugins/acryl-db-sqlite/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db-sqlite",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
   },
   "vendored": [
     "src",