acrylblends 0.7.6 → 0.7.8

package/docs/framework/helpers/streaming.md

@@ -86,7 +86,7 @@ app.get('/sse', async (c) => {
 A reader that closes the tab, loses the network or presses a Stop button should not leave your server working for nobody (a request to a paid model, a database scan). There are two signals, and they are not the same:
 
 - **`c.req.raw.signal`** is the request's `AbortSignal`. It aborts when the client goes away. Pass it to anything that takes a `signal`, such as `fetch`, and the work stops with the client. This is the one to use for cancelling work.
-- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled. Measured: when you call `app.request()` with a `signal` and abort it, `c.req.raw.signal` aborts and `stream.aborted` stays `false`; when the reader of the response body is cancelled, `stream.onAbort` fires and `c.req.raw.signal` does not. On a real connection the request signal is what fired when a browser aborted its `fetch`. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
+- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled, and they are set when the response body is cancelled, which is what the Node adapter does when the connection closes. Over a real connection, a browser that aborts its `fetch` (or closes the tab) fires both: the request signal and `stream.onAbort`. Under `app.request()` (in-process, no socket) they come apart, and this is how the upstream behaves too: aborting the `signal` you passed to `app.request()` fires `c.req.raw.signal` while `stream.aborted` stays `false`, and cancelling the reader of the response body fires `stream.onAbort` while `c.req.raw.signal` does not. A test that simulates the client leaving therefore aborts the request signal (for work cancelled through the signal) or cancels the body reader (for `stream.onAbort`), whichever the handler listens to. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
 
 An abort event that has already fired does not fire again, so check `signal.aborted` before you wait for it:
 
@@ -160,31 +160,10 @@ app.post('/api/chat', async (c) => {
 
 ## Reading a POST event stream in the browser
 
-`EventSource` can only send a GET request. For a POST (a chat message), read the response body yourself; this function calls `on` for each event as it arrives:
+`EventSource` can only send a GET request. For a POST (a chat message), call `fetch` and read the events with `readSSE` from `acrylblends/read-sse`. It is an async iterator over the events of a `text/event-stream` response, parsed by the rules of the SSE standard (LF, CRLF and CR line ends, several `data` lines joined with a line feed, comments, UTF-8 split across chunks):
 
 ```ts
-async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string, data: string) => void): Promise<void> {
-  const reader = body.getReader()
-  const decoder = new TextDecoder()
-  let buffer = ''
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) return
-    // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
-    buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
-    const blocks = buffer.split('\n\n')
-    buffer = blocks.pop() ?? ''
-    for (const block of blocks) {
-      let event = 'message'
-      const data: string[] = []
-      for (const line of block.split('\n')) {
-        if (line.startsWith('event:')) event = line.slice(6).trim()
-        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
-      }
-      on(event, data.join('\n'))
-    }
-  }
-}
+import { readSSE } from 'acrylblends/read-sse'
 
 const controller = new AbortController() // controller.abort() is the Stop button
 const response = await fetch('/api/chat', {
@@ -193,13 +172,19 @@ const response = await fetch('/api/chat', {
   body: JSON.stringify({ message: 'Hello' }),
   signal: controller.signal,
 })
+
 let answer = ''
-await readEvents(response.body!, (event, data) => {
+for await (const { event, data } of readSSE(response)) {
   if (event === 'token') answer += JSON.parse(data) as string
-})
+}
 ```
 
-A complete chat component built on this is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
+- Each event is `{ event, data, id?, retry? }`; `event` is `message` when the server named none, and `data` is a string (parse it yourself when the server sends JSON).
+- Leaving the loop early (a `break`, a thrown error) cancels the response body, so the request to the server ends. Abort the `fetch` with its own `signal` for a Stop button; `readSSE(response, { signal })` also stops reading when a signal aborts.
+- A response that is not `ok` throws with its status (the body is not parsed as events), and a response without a body throws.
+- A client module served by `clientModules` can import it as it is (`import { readSSE } from 'acrylblends/read-sse'`): the import is pointed at a browser file the same app serves, like `acrylblends/client`. With a bundler it is an ordinary import.
+
+A complete chat component is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
 
 ## Error Handling
 

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "8e23e14336647943d4232047e3ea253e434535d3"
+    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
   },
   "files": 99,
-  "digest": "sha256:2ff7cb6e36f1a04caece3bc14736ff23fd6eb2f86752453255973344e3344a0a"
+  "digest": "sha256:9b0fe3329319398ce1108a015a99247c001b02cfb30a953b4b180a73674e2aec"
 }

package/lib/browser/read-sse.js

@@ -0,0 +1,84 @@
+//#region ../../plugins/acryl-router/src/helpers/read-sse.ts
+/**
+* Read the events of a `text/event-stream` response as they arrive. Leaving the loop early (`break`, a thrown error) cancels the body, so the
+* request to the server ends.
+* @throws when the response is not `ok` (the status is in the message; the body is cancelled, not parsed), has no body, or fails while it is read.
+*/
+async function* readSSE(response, options = {}) {
+	if (!response.ok) {
+		await response.body?.cancel().catch(() => void 0);
+		throw new Error(`readSSE: the request failed with ${String(response.status)}${response.statusText === "" ? "" : ` ${response.statusText}`}`);
+	}
+	if (response.body === null) throw new Error("readSSE: the response has no body to read");
+	const { signal } = options;
+	if (signal?.aborted === true) {
+		await response.body.cancel().catch(() => void 0);
+		return;
+	}
+	const reader = response.body.getReader();
+	const onAbort = () => {
+		reader.cancel().catch(() => void 0);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	const decoder = new TextDecoder("utf-8");
+	let buffer = "";
+	let skipLineFeed = false;
+	let name = "";
+	let data = [];
+	let id;
+	let retry;
+	/** Apply one line; returns the event when this line completes one. */
+	const apply = (line) => {
+		if (line === "") {
+			const event = data.length === 0 ? void 0 : {
+				event: name === "" ? "message" : name,
+				data: data.join("\n"),
+				...id === void 0 ? {} : { id },
+				...retry === void 0 ? {} : { retry }
+			};
+			name = "";
+			data = [];
+			id = void 0;
+			retry = void 0;
+			return event;
+		}
+		if (line.startsWith(":")) return void 0;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		if (field === "event") name = value;
+		else if (field === "data") data.push(value);
+		else if (field === "id") {
+			if (!value.includes("\0")) id = value;
+		} else if (field === "retry" && /^\d+$/u.test(value)) retry = Number(value);
+	};
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			let text = decoder.decode(value, { stream: true });
+			if (skipLineFeed && text.startsWith("\n")) text = text.slice(1);
+			if (text !== "") skipLineFeed = false;
+			buffer += text;
+			let start = 0;
+			for (let index = 0; index < buffer.length; index += 1) {
+				const code = buffer.charCodeAt(index);
+				if (code !== 10 && code !== 13) continue;
+				const line = buffer.slice(start, index);
+				if (code === 13) if (index + 1 < buffer.length) {
+					if (buffer.charCodeAt(index + 1) === 10) index += 1;
+				} else skipLineFeed = true;
+				start = index + 1;
+				const event = apply(line);
+				if (event !== void 0) yield event;
+			}
+			buffer = buffer.slice(start);
+		}
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		await reader.cancel().catch(() => void 0);
+	}
+}
+//#endregion
+export { readSSE };

package/lib/index-BLTYsyc1.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 { checkKey as a, decodeValue as c, JsonValue as d, Kv as f, copyKv as i, encodeValue as l, NotPromise as m, CopyKvOptions as n, codePoints as o, KvOpened as p, CopyKvResult as r, compareKeys as s, KV_SERVICE as t, runChange as u };

package/lib/kv/db.d.ts

@@ -0,0 +1,12 @@
+import { s as Db } from "../index-D4FAsBZu.js";
+import { f as Kv } from "../index-BLTYsyc1.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 { f as Kv, p as KvOpened } from "../index-BLTYsyc1.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,224 @@
+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 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.
+* Writes are grouped: the calls made in one turn of the event loop, and those that queue while a file write is in flight, are applied in
+* call order and persisted together by one write, so a burst of calls costs one flush and one rename, not one each (on Windows each costs
+* tens of milliseconds). 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;
+	/** Calls waiting for the next file write, in call order. */
+	let queue = [];
+	/** Whether the loop that writes the queue runs; cleared by the loop itself, so a call queued after it ends starts a new one. */
+	let draining = false;
+	/** The latest loop, for `close` to wait on. */
+	let drained = 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));
+	};
+	/**
+	* Write the queue until it is empty. Each round takes every call queued so far and applies them in order to one copy of the state. A call
+	* whose change throws rejects with its error and changes nothing, and the others in the round still apply. The copy becomes the state
+	* only once it is on disk. A failed file write rejects every call in its round and leaves the state as it was.
+	*/
+	const drain = async () => {
+		try {
+			await Promise.resolve();
+			await rounds();
+		} finally {
+			draining = false;
+		}
+	};
+	const rounds = async () => {
+		while (queue.length > 0) {
+			const round = queue;
+			queue = [];
+			const draft = new Map(state);
+			const applied = [];
+			for (const call of round) {
+				let change;
+				try {
+					change = call.change((key) => draft.get(key));
+				} catch (error) {
+					call.reject(error);
+					continue;
+				}
+				if (change.text === void 0) draft.delete(change.key);
+				else draft.set(change.key, change.text);
+				applied.push({
+					call,
+					result: change.result
+				});
+			}
+			if (applied.length === 0) continue;
+			try {
+				await persist(draft);
+			} catch (error) {
+				for (const { call } of applied) call.reject(error);
+				continue;
+			}
+			state = draft;
+			for (const { call, result } of applied) call.resolve(result);
+		}
+	};
+	/** Queue one change behind every earlier call; it resolves once a file write that contains it is on disk. */
+	const write = (change) => {
+		guard();
+		const done = new Promise((resolveCall, rejectCall) => {
+			queue.push({
+				change,
+				resolve: resolveCall,
+				reject: rejectCall
+			});
+		});
+		if (!draining) {
+			draining = true;
+			drained = drain();
+		}
+		return done;
+	};
+	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(() => ({
+					key,
+					text,
+					result: void 0
+				}));
+			},
+			async update(key, change) {
+				checkKey(key);
+				return write((read) => {
+					const text = read(key);
+					const encoded = encodeValue(runChange(change, text === void 0 ? void 0 : decodeValue(text)));
+					return {
+						key,
+						text: encoded,
+						result: decodeValue(encoded)
+					};
+				});
+			},
+			async delete(key) {
+				checkKey(key);
+				await write(() => ({
+					key,
+					text: void 0,
+					result: void 0
+				}));
+			},
+			async list(prefix = "") {
+				guard();
+				return [...state.keys()].filter((key) => key.startsWith(prefix)).sort(compareKeys);
+			}
+		},
+		close: async () => {
+			closed = true;
+			await drained;
+		}
+	};
+}
+//#endregion
+export { openKv };

package/lib/kv.d.ts

@@ -0,0 +1,2 @@
+import { a as checkKey, c as decodeValue, d as JsonValue, f as Kv, i as copyKv, l as encodeValue, m as NotPromise, n as CopyKvOptions, o as codePoints, p as KvOpened, r as CopyKvResult, s as compareKeys, t as KV_SERVICE, u as runChange } from "./index-BLTYsyc1.js";
+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/node-server.d.ts

@@ -136,7 +136,7 @@ interface ClientModulesOptions {
   readonly compiled?: string | undefined;
   /** At most this many bytes of compiled modules are kept in memory (least recently served first out); 16 MiB when not given. */
   readonly cacheBytes?: number | undefined;
-  /** The folder holding `jsx-dom.js` and `client.js`; the framework's own when not given. */
+  /** The folder holding `jsx-dom.js`, `client.js` and `read-sse.js`; the framework's own when not given. */
   readonly runtimeDir?: string | undefined;
 }
 /** Options of {@link buildClientModules}. */
@@ -145,7 +145,7 @@ interface BuildClientModulesOptions {
   readonly root: string;
   /** Where the compiled modules go, at the same relative paths and file names; it must not lie inside `root`. */
   readonly outDir: string;
-  /** The folder holding `jsx-dom.js` and `client.js`; the framework's own when not given. */
+  /** The folder holding `jsx-dom.js`, `client.js` and `read-sse.js`; the framework's own when not given. */
   readonly runtimeDir?: string | undefined;
 }
 /**
@@ -159,7 +159,7 @@ interface BuildClientModulesOptions {
 declare function clientModules(options: ClientModulesOptions): Acryl;
 /**
  * Compile a folder of client modules once, for a production that has no `typescript`: each module is written to `outDir` at the same
- * relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the two
+ * relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the three
  * browser files are copied to `outDir/@acrylblends/`. Files already in `outDir` that no source produces are left there.
  * @param options - the source folder and the output folder.
  * @returns the paths written, relative to `outDir`.

package/lib/node-server.js

@@ -1330,14 +1330,14 @@ function serve(options, listeningListener) {
 /**
 * Client components without a bundler. `clientModules({ root: 'src/client' })` is an app that serves the TypeScript and JSX modules of a
 * folder to the browser as ES modules: a `.tsx`/`.ts`/`.jsx` file compiled with the app's own `typescript` (JSX for `acrylblends/jsx/dom`),
-* a `.js`/`.mjs` file as it is. The framework's own browser imports (`acrylblends/jsx/dom` with its runtimes and `client`, and
-* `acrylblends/client`) are rewritten to two self-contained files the same app serves, at a URL relative to each module, so a page needs
+* a `.js`/`.mjs` file as it is. The framework's own browser imports (`acrylblends/jsx/dom` with its runtimes and `client`,
+* `acrylblends/client` and `acrylblends/read-sse`) are rewritten to three self-contained files the same app serves, at a URL relative to each module, so a page needs
 * one `<script type="module" src="/client/counter.tsx">` and no import map, under whatever path the app is routed at.
 *
 * Production runs without `typescript` (a deploy that leaves out devDependencies): `buildClientModules` writes the same compiled modules
-* and the two browser files into a folder, and with `NODE_ENV=production` and `compiled` set, only that folder is served.
+* and the three browser files into a folder, and with `NODE_ENV=production` and `compiled` set, only that folder is served.
 */
-/** The folder the two browser files are served from, below the app's mount. A source folder of this name is not served. */
+/** The folder the three browser files are served from, below the app's mount. A source folder of this name is not served. */
 const RUNTIME_DIR = "@acrylblends";
 /** The framework's browser imports and the browser file that provides each. */
 const BROWSER_IMPORTS = {
@@ -1345,9 +1345,14 @@ const BROWSER_IMPORTS = {
 	"acrylblends/jsx/dom/jsx-runtime": "jsx-dom.js",
 	"acrylblends/jsx/dom/jsx-dev-runtime": "jsx-dom.js",
 	"acrylblends/jsx/dom/client": "jsx-dom.js",
-	"acrylblends/client": "client.js"
+	"acrylblends/client": "client.js",
+	"acrylblends/read-sse": "read-sse.js"
 };
-const RUNTIME_FILES = ["jsx-dom.js", "client.js"];
+const RUNTIME_FILES = [
+	"jsx-dom.js",
+	"client.js",
+	"read-sse.js"
+];
 const COMPILED = /* @__PURE__ */ new Set([
 	".ts",
 	".tsx",
@@ -1362,7 +1367,7 @@ const SERVED = /* @__PURE__ */ new Set([
 const JS_TYPE = "text/javascript; charset=utf-8";
 /** The cache bound when `cacheBytes` is not given. */
 const DEFAULT_CACHE_BYTES = 16 * 1024 * 1024;
-/** The framework's two browser files, next to the built module that contains this code. */
+/** The framework's three browser files, next to the built module that contains this code. */
 const defaultRuntimeDir = () => fileURLToPath(new URL("./browser/", import.meta.url));
 /** A module path below the root (`widgets/counter.tsx`) with the URL prefix that reaches the browser files from it. */
 const runtimePrefix = (relativePath) => {
@@ -1551,7 +1556,7 @@ function sourceFiles(root, dir = root) {
 }
 /**
 * Compile a folder of client modules once, for a production that has no `typescript`: each module is written to `outDir` at the same
-* relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the two
+* relative path and file name (so the page's URLs stay the same), compiled exactly as {@link clientModules} compiles it, and the three
 * browser files are copied to `outDir/@acrylblends/`. Files already in `outDir` that no source produces are left there.
 * @param options - the source folder and the output folder.
 * @returns the paths written, relative to `outDir`.