@statewalker/webrun-files-sqlite 0.10.0

package/dist/esm/index.js

@@ -0,0 +1,1253 @@
+//#region ../webrun-files/dist/esm/index.js
+/**
+* The order every `FilesApi.list()` yields: paths compared by Unicode code
+* point, which is the same as comparing their UTF-8 bytes — the order of
+* SQLite's `BINARY` collation and of S3 key listings.
+*
+* Not JavaScript's `<`, which compares UTF-16 code units and so puts a
+* character above U+FFFF (a surrogate pair) before U+E000–U+FFFF.
+*/
+function comparePaths(a, b) {
+	const length = Math.min(a.length, b.length);
+	for (let i = 0; i < length; i++) {
+		const x = a.charCodeAt(i);
+		const y = b.charCodeAt(i);
+		if (x === y) continue;
+		const xSurrogate = x >= 55296 && x <= 57343;
+		if (xSurrogate !== (y >= 55296 && y <= 57343)) return xSurrogate ? 1 : -1;
+		return x - y;
+	}
+	return a.length - b.length;
+}
+/**
+* Path manipulation utilities for virtual filesystem paths.
+* All paths use forward slashes and start with "/".
+*/
+/**
+* Normalizes a file path to a consistent format.
+* - Adds leading slash if missing
+* - Removes trailing slash
+* - Removes `.` segments
+* - Collapses multiple slashes
+*/
+function normalizePath(filePath) {
+	const segments = filePath.split("/").filter((s) => !!s && s !== ".");
+	if (segments.length === 0) return "/";
+	return `/${segments.join("/")}`;
+}
+//#endregion
+//#region src/bytes.ts
+/** Blobs arrive as Uint8Array (node:sqlite), ArrayBuffer (Durable Objects) or number[] (D1). */
+function toBytes(value) {
+	if (value instanceof Uint8Array) return value;
+	if (value instanceof ArrayBuffer) return new Uint8Array(value);
+	if (Array.isArray(value)) return Uint8Array.from(value);
+	if (typeof value === "string") return new TextEncoder().encode(value);
+	return /* @__PURE__ */ new Uint8Array(0);
+}
+//#endregion
+//#region src/blocks/byte-reader.ts
+/**
+* Pull bytes from a chunk source in bounded pieces.
+*
+* `read(max)` hands out at most `max` bytes as a zero-copy view of the current
+* source chunk, and pulls the next chunk only when the current one is spent.
+* The source is therefore never read ahead of its consumer: this is the
+* backpressure boundary between a caller's stream and block storage.
+*/
+var ByteReader = class {
+	#iterator;
+	#chunk;
+	#done = false;
+	constructor(source) {
+		this.#iterator = Symbol.asyncIterator in source ? source[Symbol.asyncIterator]() : source[Symbol.iterator]();
+	}
+	/** At most `max` bytes, or `undefined` once the source is exhausted. */
+	async read(max) {
+		while (!this.#chunk || this.#chunk.length === 0) {
+			if (this.#done) return void 0;
+			const next = await this.#iterator.next();
+			if (next.done) {
+				this.#done = true;
+				this.#chunk = void 0;
+				return;
+			}
+			this.#chunk = next.value;
+		}
+		const piece = this.#chunk.subarray(0, max);
+		this.#chunk = this.#chunk.subarray(piece.length);
+		return piece;
+	}
+	/** Release the source early, as `break` in a `for await` would. */
+	async close() {
+		if (this.#done) return;
+		this.#done = true;
+		this.#chunk = void 0;
+		await this.#iterator.return?.();
+	}
+};
+/** One Uint8Array from a stream's chunks — only ever used on a single block's worth. */
+async function collectBlock(chunks) {
+	const parts = [];
+	let total = 0;
+	for await (const chunk of chunks) {
+		parts.push(chunk);
+		total += chunk.length;
+	}
+	const out = new Uint8Array(total);
+	let at = 0;
+	for (const part of parts) {
+		out.set(part, at);
+		at += part.length;
+	}
+	return out;
+}
+//#endregion
+//#region src/blocks/sha256.ts
+/**
+* Incremental SHA-256 (FIPS 180-4). WebCrypto only hashes a whole buffer, and
+* content here arrives as a stream it must never be collected from.
+*/
+const K = new Uint32Array([
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+]);
+var Sha256 = class {
+	#state = new Uint32Array([
+		1779033703,
+		3144134277,
+		1013904242,
+		2773480762,
+		1359893119,
+		2600822924,
+		528734635,
+		1541459225
+	]);
+	#buffer = /* @__PURE__ */ new Uint8Array(64);
+	#words = /* @__PURE__ */ new Uint32Array(80);
+	#buffered = 0;
+	#length = 0;
+	#finished = false;
+	update(bytes) {
+		if (this.#finished) throw new Error("Sha256: already digested");
+		this.#length += bytes.length;
+		let at = 0;
+		if (this.#buffered > 0) {
+			const take = Math.min(64 - this.#buffered, bytes.length);
+			this.#buffer.set(bytes.subarray(0, take), this.#buffered);
+			this.#buffered += take;
+			at = take;
+			if (this.#buffered < 64) return this;
+			this.#compress(this.#buffer, 0);
+			this.#buffered = 0;
+		}
+		for (; at + 64 <= bytes.length; at += 64) this.#compress(bytes, at);
+		if (at < bytes.length) {
+			this.#buffer.set(bytes.subarray(at));
+			this.#buffered = bytes.length - at;
+		}
+		return this;
+	}
+	/** Finalises the hash; the instance cannot be used afterwards. */
+	digestHex() {
+		if (this.#finished) throw new Error("Sha256: already digested");
+		const bitLength = this.#length * 8;
+		const padding = new Uint8Array((this.#buffered < 56 ? 56 : 120) - this.#buffered + 8);
+		padding[0] = 128;
+		const view = new DataView(padding.buffer);
+		view.setUint32(padding.length - 8, Math.floor(bitLength / 2 ** 32));
+		view.setUint32(padding.length - 4, bitLength >>> 0);
+		this.update(padding);
+		this.#finished = true;
+		let hex = "";
+		for (const word of this.#state) hex += word.toString(16).padStart(8, "0");
+		return hex;
+	}
+	#compress(bytes, at) {
+		const w = this.#words;
+		for (let i = 0; i < 16; i++) {
+			const j = at + i * 4;
+			w[i] = bytes[j] << 24 | bytes[j + 1] << 16 | bytes[j + 2] << 8 | bytes[j + 3];
+		}
+		for (let i = 16; i < 64; i++) {
+			const a = w[i - 15];
+			const b = w[i - 2];
+			const s0 = (a >>> 7 | a << 25) ^ (a >>> 18 | a << 14) ^ a >>> 3;
+			const s1 = (b >>> 17 | b << 15) ^ (b >>> 19 | b << 13) ^ b >>> 10;
+			w[i] = s1 + w[i - 7] + s0 + w[i - 16] | 0;
+		}
+		const h = this.#state;
+		let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], k = h[7];
+		for (let i = 0; i < 64; i++) {
+			const t1 = k + ((e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7)) + (e & f ^ ~e & g) + K[i] + w[i] | 0;
+			const t2 = ((a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10)) + (a & b ^ a & c ^ b & c) | 0;
+			k = g;
+			g = f;
+			f = e;
+			e = d + t1 | 0;
+			d = c;
+			c = b;
+			b = a;
+			a = t1 + t2 | 0;
+		}
+		h[0] += a;
+		h[1] += b;
+		h[2] += c;
+		h[3] += d;
+		h[4] += e;
+		h[5] += f;
+		h[6] += g;
+		h[7] += k;
+	}
+};
+//#endregion
+//#region src/blocks/stream-codec.ts
+/**
+* zlib-wrapped Deflate over Compression Streams — browsers, Node, Deno, Bun,
+* Workers. The source is wrapped in a pull-only ReadableStream, so the
+* transform asks for input only when it has room, and cancelling the output
+* closes the source.
+*/
+function webDeflateCodec() {
+	if (typeof CompressionStream === "undefined") throw new Error("webDeflateCodec: CompressionStream is not available in this runtime");
+	return {
+		name: "deflate",
+		compress: (input) => iterate(pullStream(input).pipeThrough(asPair(new CompressionStream("deflate")))),
+		decompress: (input) => iterate(pullStream(input).pipeThrough(asPair(new DecompressionStream("deflate"))))
+	};
+}
+/**
+* zlib-wrapped Deflate through pako's incremental classes, for runtimes without
+* Compression Streams. The module is injected, not imported.
+*/
+function pakoDeflateCodec(pako, opts = {}) {
+	const options = opts.level === void 0 ? {} : { level: opts.level };
+	return {
+		name: "deflate",
+		compress: (input) => pakoTransform(new pako.Deflate(options), input, true),
+		decompress: (input) => pakoTransform(new pako.Inflate(), input, false)
+	};
+}
+/**
+* Feed one input chunk at a time and hand on whatever that produced before
+* pulling again. pako's `push` is synchronous, so its output per chunk is
+* bounded by the chunk.
+*/
+async function* pakoTransform(stream, input, compressing) {
+	let pending = [];
+	stream.onData = (chunk) => pending.push(chunk);
+	const check = () => {
+		if (stream.err) throw new Error(`pako: ${stream.msg || `error ${stream.err}`}`);
+	};
+	for await (const chunk of input) {
+		if (chunk.length === 0) continue;
+		stream.push(chunk, false);
+		check();
+		const out = pending;
+		pending = [];
+		yield* out;
+	}
+	if (compressing) {
+		stream.push(/* @__PURE__ */ new Uint8Array(0), true);
+		check();
+	} else if (!stream.ended) throw new Error("pako: truncated deflate stream");
+	yield* pending;
+}
+/** Compression streams accept any BufferSource; this pipe only ever writes Uint8Array. */
+function asPair(transform) {
+	return transform;
+}
+function pullStream(source) {
+	const iterator = source[Symbol.asyncIterator]();
+	return new ReadableStream({
+		async pull(controller) {
+			const next = await iterator.next();
+			if (next.done) controller.close();
+			else controller.enqueue(next.value);
+		},
+		async cancel(reason) {
+			await iterator.return?.(reason);
+		}
+	}, { highWaterMark: 0 });
+}
+async function* iterate(stream) {
+	const reader = stream.getReader();
+	let finished = false;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) {
+				finished = true;
+				return;
+			}
+			yield value;
+		}
+	} finally {
+		if (!finished) await reader.cancel().catch(() => {});
+		reader.releaseLock();
+	}
+}
+//#endregion
+//#region src/blocks/sqlite-files-api.ts
+const MiB = 1048576;
+/** Rows on Durable Objects and D1 are capped at 2 MB; leave room for deflate's worst case. */
+const MAX_BLOCK_SIZE_LIMIT = 1.5 * MiB;
+const LIST_PAGE = 256;
+/**
+* A FilesApi over three SQLite tables: paths point at immutable contents, and
+* a content is a sequence of bounded, optionally compressed blocks. Reads and
+* writes stream one block at a time, so no file is ever held whole and no row
+* outgrows the 2 MB limit of Durable Objects and D1.
+*
+* Streaming happens outside transactions; every step that changes what a path
+* shows is one transaction, so an interruption leaves at most an unreferenced
+* content, which {@link sweep} removes.
+*/
+var SqliteFilesApi = class {
+	#sql;
+	#codec;
+	#blockSize;
+	#paths;
+	#files;
+	#blocks;
+	#prefix;
+	constructor(sql, opts = {}) {
+		const prefix = opts.tablePrefix ?? "fs_";
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) throw new Error(`SqliteFilesApi: tablePrefix must be a plain SQL identifier, got ${prefix}`);
+		this.#blockSize = opts.blockSize ?? MiB;
+		if (!Number.isInteger(this.#blockSize) || this.#blockSize < 1 || this.#blockSize > MAX_BLOCK_SIZE_LIMIT) throw new Error(`SqliteFilesApi: blockSize must be an integer from 1 to ${MAX_BLOCK_SIZE_LIMIT}, got ${this.#blockSize}`);
+		this.#sql = sql;
+		this.#codec = opts.compression === void 0 ? availableWebCodec() : opts.compression;
+		this.#prefix = prefix;
+		this.#paths = `${prefix}paths`;
+		this.#files = `${prefix}files`;
+		this.#blocks = `${prefix}blocks`;
+	}
+	/** Creates the tables and indexes if missing. Await it before any other call. */
+	async init() {
+		const statements = [
+			`CREATE TABLE IF NOT EXISTS ${this.#files}(
+        fid INTEGER PRIMARY KEY,
+        size INTEGER,
+        compression TEXT NOT NULL,
+        block_size INTEGER NOT NULL,
+        hash TEXT,
+        updated INTEGER NOT NULL
+      )`,
+			`CREATE TABLE IF NOT EXISTS ${this.#blocks}(
+        fid INTEGER NOT NULL,
+        shift INTEGER NOT NULL,
+        block BLOB NOT NULL,
+        PRIMARY KEY (fid, shift)
+      ) WITHOUT ROWID`,
+			`CREATE TABLE IF NOT EXISTS ${this.#paths}(
+        pid INTEGER PRIMARY KEY,
+        path TEXT NOT NULL UNIQUE,
+        fid INTEGER,
+        mtime INTEGER NOT NULL
+      )`,
+			`CREATE INDEX IF NOT EXISTS ${this.#prefix}paths_fid ON ${this.#paths}(fid)`,
+			`CREATE INDEX IF NOT EXISTS ${this.#prefix}files_hash ON ${this.#files}(hash, size)`
+		];
+		for (const statement of statements) await this.#sql.run(statement);
+	}
+	async *read(path, options = {}) {
+		options.signal?.throwIfAborted();
+		const name = normalizePath(path);
+		const entry = await this.#entry(name);
+		if (!entry || entry.fid === null || entry.size === null) return;
+		const start = Math.max(0, options.start ?? 0);
+		const end = Math.min(entry.size, options.length === void 0 ? entry.size : start + options.length);
+		if (start >= end) return;
+		const { fid, size } = entry;
+		const blockSize = entry.block_size ?? this.#blockSize;
+		const decoder = this.#decoder(name, entry.compression ?? "none");
+		for (let shift = start - start % blockSize; shift < end; shift += blockSize) {
+			options.signal?.throwIfAborted();
+			const block = await this.#block(fid, shift);
+			if (!block) throw new Error(`sqlite-files: ${name} changed during read`);
+			const expected = Math.min(blockSize, size - shift);
+			const bytes = toBytes(block.block);
+			const chunks = decoder ? decoder.decompress(once(bytes)) : once(bytes);
+			let offset = shift;
+			let stoppedEarly = false;
+			for await (const chunk of chunks) {
+				if (offset + chunk.length - shift > expected) throw corruptBlock(name, shift, `at least ${offset + chunk.length - shift}`, expected);
+				const from = Math.max(0, start - offset);
+				const to = Math.min(chunk.length, end - offset);
+				offset += chunk.length;
+				if (to > from) yield chunk.subarray(from, to);
+				if (offset >= end) {
+					stoppedEarly = true;
+					break;
+				}
+			}
+			if (!stoppedEarly && offset - shift !== expected) throw corruptBlock(name, shift, offset - shift, expected);
+		}
+	}
+	/**
+	* Streams the content into a new, invisible content row, one block per
+	* transaction, then points the path at it in one transaction. Any failure
+	* removes the pending content; a crash leaves it for {@link sweep}.
+	*/
+	async write(path, content) {
+		const name = normalizePath(path);
+		const compression = this.#codec?.name ?? "none";
+		const fid = (await this.#sql.all(`INSERT INTO ${this.#files}(size, compression, block_size, hash, updated)
+       VALUES (NULL, ?, ?, NULL, ?) RETURNING fid`, compression, this.#blockSize, Date.now()))[0].fid;
+		const limit = this.#blockSize;
+		const reader = new ByteReader(content);
+		const hash = new Sha256();
+		try {
+			let size = 0;
+			for (;;) {
+				const first = await reader.read(limit);
+				if (!first) break;
+				let raw = 0;
+				const pieces = async function* () {
+					let piece = first;
+					while (piece) {
+						hash.update(piece);
+						raw += piece.length;
+						yield piece;
+						if (raw === limit) return;
+						piece = await reader.read(limit - raw);
+					}
+				};
+				const block = await collectBlock(this.#codec ? this.#codec.compress(pieces()) : pieces());
+				const [alive] = await this.#sql.transaction([{
+					sql: `UPDATE ${this.#files} SET updated = ? WHERE fid = ? AND size IS NULL`,
+					params: [Date.now(), fid]
+				}, {
+					sql: `INSERT INTO ${this.#blocks}(fid, shift, block)
+                  SELECT ?, ?, ? WHERE EXISTS (${this.#pending("?")})`,
+					params: [
+						fid,
+						size,
+						block,
+						fid
+					]
+				}]);
+				if (alive === 0) throw sweptDuringWrite(name);
+				size += raw;
+			}
+			const previous = await this.#entry(name);
+			const [finished] = await this.#sql.transaction(this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null));
+			if (finished === 0) throw sweptDuringWrite(name);
+		} catch (error) {
+			try {
+				await reader.close();
+			} catch {}
+			try {
+				await this.#sql.transaction([{
+					sql: `DELETE FROM ${this.#files} WHERE fid = ? AND size IS NULL`,
+					params: [fid]
+				}, ...this.#deleteBlocksOfMissing(fid)]);
+			} catch {}
+			throw error;
+		}
+	}
+	/**
+	* One transaction: finish the content, create the parents, point the path at
+	* an identical content if one exists or else at this one, then collect this
+	* content if it ended up unused and the path's previous content. Everything
+	* after the first statement is conditioned on the content still existing, so
+	* a swept write changes nothing.
+	*/
+	#finishWrite(name, fid, size, digest, compression, previous) {
+		const now = Date.now();
+		const exists = `SELECT 1 FROM ${this.#files} WHERE fid = ?`;
+		const statements = [
+			{
+				sql: `UPDATE ${this.#files} SET size = ?, hash = ?, updated = ? WHERE fid = ? AND size IS NULL`,
+				params: [
+					size,
+					digest,
+					now,
+					fid
+				]
+			},
+			...ancestorsAndSelf$1(parentOf(name)).map((dir) => ({
+				sql: `INSERT INTO ${this.#paths}(path, fid, mtime) SELECT ?, NULL, ? WHERE EXISTS (${exists})
+              ON CONFLICT(path) DO NOTHING`,
+				params: [
+					dir,
+					now,
+					fid
+				]
+			})),
+			{
+				sql: `INSERT INTO ${this.#paths}(path, fid, mtime)
+              SELECT ?, COALESCE((
+                SELECT f.fid FROM ${this.#files} f
+                WHERE f.hash = ? AND f.size = ? AND f.compression = ? AND f.block_size = ? AND f.fid <> ?
+                ORDER BY f.fid LIMIT 1
+              ), ?), ?
+              WHERE EXISTS (${exists})
+              ON CONFLICT(path) DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime`,
+				params: [
+					name,
+					digest,
+					size,
+					compression,
+					this.#blockSize,
+					fid,
+					fid,
+					now,
+					fid
+				]
+			},
+			...this.#collect(fid)
+		];
+		if (previous !== null && previous !== fid) statements.push(...this.#collect(previous));
+		return statements;
+	}
+	async mkdir(path) {
+		const now = Date.now();
+		for (const dir of ancestorsAndSelf$1(normalizePath(path))) await this.#sql.run(`INSERT INTO ${this.#paths}(path, fid, mtime) VALUES (?, NULL, ?) ON CONFLICT(path) DO NOTHING`, dir, now);
+	}
+	async stats(path) {
+		const name = normalizePath(path);
+		if (name === "/") return { kind: "directory" };
+		const entry = await this.#entry(name);
+		return entry && toStats$1(entry);
+	}
+	async exists(path) {
+		return await this.stats(path) !== void 0;
+	}
+	async *list(path, options = {}) {
+		const base = normalizePath(path);
+		if ((await this.stats(base))?.kind !== "directory") return;
+		const range = descendants$1(base);
+		const prefixLength = base === "/" ? 1 : base.length + 1;
+		const directOnly = options.recursive ? "" : "AND instr(substr(p.path, ?), '/') = 0";
+		let cursor = options.after ?? "";
+		for (;;) {
+			const params = [...range.params, cursor];
+			if (!options.recursive) params.push(prefixLength + 1);
+			const rows = await this.#sql.all(`SELECT p.path, p.fid, p.mtime, f.size, f.compression, f.block_size
+         FROM ${this.#paths} p LEFT JOIN ${this.#files} f ON f.fid = p.fid
+         WHERE ${range.where} AND p.path > ? ${directOnly}
+         ORDER BY p.path LIMIT ${LIST_PAGE}`, ...params);
+			for (const row of rows) {
+				const stats = toStats$1(row);
+				if (stats) yield {
+					...stats,
+					name: row.path.slice(row.path.lastIndexOf("/") + 1),
+					path: row.path
+				};
+			}
+			if (rows.length < LIST_PAGE) return;
+			cursor = rows[rows.length - 1].path;
+		}
+	}
+	async remove(path) {
+		const counts = await this.#sql.transaction(this.#removeTree(normalizePath(path)));
+		return counts[counts.length - 1] > 0;
+	}
+	/**
+	* Deletes available contents and blocks referenced only from inside the tree, then the tree's
+	* path rows. Set-based, so it needs no ids read beforehand. `guard` conditions every statement.
+	*/
+	#removeTree(path, guard = NO_GUARD) {
+		const inP = selfAndDescendants$1(path, "p");
+		const inQ = selfAndDescendants$1(path, "q");
+		const referenced = `SELECT p.fid FROM ${this.#paths} p WHERE ${inP.where}`;
+		return [
+			{
+				sql: `DELETE FROM ${this.#files} WHERE size IS NOT NULL
+              AND fid IN (${referenced})
+              AND NOT EXISTS (
+                SELECT 1 FROM ${this.#paths} q WHERE q.fid = ${this.#files}.fid AND NOT ${inQ.where}
+              ) ${guard.sql}`,
+				params: [
+					...inP.params,
+					...inQ.params,
+					...guard.params
+				]
+			},
+			{
+				sql: `DELETE FROM ${this.#blocks} WHERE fid IN (${referenced})
+              AND NOT EXISTS (SELECT 1 FROM ${this.#files} f WHERE f.fid = ${this.#blocks}.fid)
+              ${guard.sql}`,
+				params: [...inP.params, ...guard.params]
+			},
+			{
+				sql: `DELETE FROM ${this.#paths} AS p WHERE ${inP.where} ${guard.sql}`,
+				params: [...inP.params, ...guard.params]
+			}
+		];
+	}
+	async copy(source, target) {
+		return this.#transfer(source, target, "copy");
+	}
+	async move(source, target) {
+		return this.#transfer(source, target, "move");
+	}
+	/**
+	* One transaction: replace the target's subtree, create its parents, then copy
+	* or rename. Everything before the last statement is conditioned on the source
+	* existing, so a source that vanished leaves the target untouched.
+	*/
+	async #transfer(source, target, mode) {
+		const from = normalizePath(source);
+		const to = normalizePath(target);
+		if (from === to) return this.exists(from);
+		if (isInside(to, from) || isInside(from, to)) throw new Error(`sqlite-files: cannot ${mode} ${from} to ${to}: one contains the other`);
+		const range = selfAndDescendants$1(from, "p");
+		const inS = selfAndDescendants$1(from, "s");
+		const guard = {
+			sql: `AND EXISTS (SELECT 1 FROM ${this.#paths} s WHERE ${inS.where})`,
+			params: inS.params
+		};
+		const now = Date.now();
+		const statements = [
+			...this.#removeTree(to, guard),
+			...ancestorsAndSelf$1(parentOf(to)).map((dir) => ({
+				sql: `INSERT INTO ${this.#paths}(path, fid, mtime) SELECT ?, NULL, ? WHERE 1 ${guard.sql}
+              ON CONFLICT(path) DO NOTHING`,
+				params: [
+					dir,
+					now,
+					...guard.params
+				]
+			})),
+			mode === "copy" ? {
+				sql: `INSERT INTO ${this.#paths}(path, fid, mtime)
+                  SELECT ? || substr(p.path, ?), p.fid, ? FROM ${this.#paths} p WHERE ${range.where}`,
+				params: [
+					to,
+					from.length + 1,
+					now,
+					...range.params
+				]
+			} : {
+				sql: `UPDATE ${this.#paths} AS p SET path = ? || substr(p.path, ?), mtime = ?
+                  WHERE ${range.where}`,
+				params: [
+					to,
+					from.length + 1,
+					now,
+					...range.params
+				]
+			}
+		];
+		const counts = await this.#sql.transaction(statements);
+		return counts[counts.length - 1] > 0;
+	}
+	/**
+	* Deletes, in one transaction, every content not updated for `olderThan`
+	* milliseconds that is still pending or that no path references, with its
+	* blocks. Returns how many contents were deleted.
+	*
+	* A write refreshes its pending content with every block, so only a write
+	* stalled longer than `olderThan` can be swept — and it then fails instead of
+	* pointing a path at missing content. Never runs on its own.
+	*/
+	async sweep(options) {
+		const { olderThan } = options;
+		if (!(Number.isFinite(olderThan) && olderThan >= 0)) throw new Error(`SqliteFilesApi.sweep: olderThan must be a finite number >= 0, got ${olderThan}`);
+		const cutoff = Date.now() - olderThan;
+		const eligible = `f.updated < ? AND NOT EXISTS (
+      SELECT 1 FROM ${this.#paths} p WHERE p.fid = f.fid
+    )`;
+		const [, contents] = await this.#sql.transaction([{
+			sql: `DELETE FROM ${this.#blocks} WHERE fid IN (SELECT f.fid FROM ${this.#files} f WHERE ${eligible})`,
+			params: [cutoff]
+		}, {
+			sql: `DELETE FROM ${this.#files} AS f WHERE ${eligible}`,
+			params: [cutoff]
+		}]);
+		return contents;
+	}
+	async #entry(name) {
+		return (await this.#sql.all(`SELECT p.fid, p.mtime, f.size, f.compression, f.block_size
+       FROM ${this.#paths} p LEFT JOIN ${this.#files} f ON f.fid = p.fid
+       WHERE p.path = ?`, name))[0];
+	}
+	#decoder(name, compression) {
+		if (compression === "none") return null;
+		if (this.#codec?.name === compression) return this.#codec;
+		if (compression === "deflate") {
+			const web = availableWebCodec();
+			if (web) return web;
+		}
+		throw new Error(`sqlite-files: ${name} is compressed with ${compression}, and no codec reads it`);
+	}
+	async #block(fid, shift) {
+		return (await this.#sql.all(`SELECT shift, block FROM ${this.#blocks} WHERE fid = ? AND shift = ?`, fid, shift))[0];
+	}
+	/** A subquery selecting the content `fid` while it is still pending. */
+	#pending(fid) {
+		return `SELECT 1 FROM ${this.#files} WHERE fid = ${fid} AND size IS NULL`;
+	}
+	/**
+	* Delete a finished content no path references, then its blocks. Inside a
+	* transaction the reference check and the delete cannot be separated by a
+	* write that shares the content.
+	*/
+	#collect(fid) {
+		return [{
+			sql: `DELETE FROM ${this.#files} WHERE fid = ? AND size IS NOT NULL
+              AND NOT EXISTS (SELECT 1 FROM ${this.#paths} WHERE fid = ?)`,
+			params: [fid, fid]
+		}, ...this.#deleteBlocksOfMissing(fid)];
+	}
+	#deleteBlocksOfMissing(fid) {
+		return [{
+			sql: `DELETE FROM ${this.#blocks} WHERE fid = ?
+              AND NOT EXISTS (SELECT 1 FROM ${this.#files} WHERE fid = ?)`,
+			params: [fid, fid]
+		}];
+	}
+};
+const NO_GUARD = {
+	sql: "",
+	params: []
+};
+function sweptDuringWrite(name) {
+	return /* @__PURE__ */ new Error(`sqlite-files: ${name} content was swept during write`);
+}
+function corruptBlock(name, shift, holds, expected) {
+	return /* @__PURE__ */ new Error(`sqlite-files: ${name} block at ${shift} holds ${holds} bytes, expected ${expected}`);
+}
+function availableWebCodec() {
+	return typeof CompressionStream === "undefined" ? null : webDeflateCodec();
+}
+function toStats$1(row) {
+	if (row.fid === null) return { kind: "directory" };
+	if (row.size === null) return void 0;
+	return {
+		kind: "file",
+		size: row.size,
+		lastModified: row.mtime
+	};
+}
+async function* once(bytes) {
+	yield bytes;
+}
+/** Rows strictly under `path` as a range on the unique index (case-sensitive, unlike LIKE). */
+function descendants$1(path, alias = "p") {
+	if (path === "/") return {
+		where: "1",
+		params: []
+	};
+	return {
+		where: `(${alias}.path > ? AND ${alias}.path < ?)`,
+		params: [`${path}/`, `${path}0`]
+	};
+}
+function selfAndDescendants$1(path, alias = "p") {
+	if (path === "/") return descendants$1(path, alias);
+	const range = descendants$1(path, alias);
+	return {
+		where: `(${alias}.path = ? OR ${range.where})`,
+		params: [path, ...range.params]
+	};
+}
+function isInside(path, ancestor) {
+	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
+}
+function parentOf(path) {
+	const i = path.lastIndexOf("/");
+	return i <= 0 ? "/" : path.slice(0, i);
+}
+/** "/a/b" → ["/a", "/a/b"]; the root yields nothing. */
+function ancestorsAndSelf$1(path) {
+	const parts = path.split("/").filter(Boolean);
+	return parts.map((_, i) => `/${parts.slice(0, i + 1).join("/")}`);
+}
+//#endregion
+//#region src/codec.ts
+const MIN_SIZE = 64;
+/** Compression Streams — browsers, Node, Workers. No dependency. */
+function webCodec(opts = {}) {
+	if (typeof CompressionStream === "undefined") throw new Error("webCodec: CompressionStream is not available in this runtime");
+	return {
+		name: "web",
+		minSize: opts.minSize ?? MIN_SIZE,
+		deflate: (bytes) => pipe(bytes, new CompressionStream("deflate")),
+		inflate: (data) => pipe(data, new DecompressionStream("deflate"))
+	};
+}
+/**
+* pako — synchronous, for runtimes without a usable CompressionStream. The
+* module is injected so this package does not depend on it:
+*
+*     import * as pako from "pako";
+*     new SqlarFilesApi(driver, { codec: pakoCodec(pako) });
+*/
+function pakoCodec(pako, opts = {}) {
+	const deflateOptions = opts.level === void 0 ? {} : { level: opts.level };
+	return {
+		name: "pako",
+		minSize: opts.minSize ?? MIN_SIZE,
+		deflate: (bytes) => pako.deflate(bytes, deflateOptions),
+		inflate: (data) => pako.inflate(data)
+	};
+}
+/**
+* No compression — still a valid archive. Reading a compressed row through it
+* throws rather than returning deflate bytes as file content.
+*/
+function rawCodec() {
+	return {
+		name: "raw",
+		minSize: Number.POSITIVE_INFINITY,
+		deflate: (bytes) => bytes,
+		inflate() {
+			throw new Error("rawCodec cannot inflate: this archive holds compressed rows");
+		}
+	};
+}
+/** webCodec where CompressionStream exists, rawCodec elsewhere. */
+function defaultCodec() {
+	return typeof CompressionStream === "undefined" ? rawCodec() : webCodec();
+}
+async function pipe(bytes, transform) {
+	const stream = new Blob([bytes]).stream().pipeThrough(transform);
+	return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+//#endregion
+//#region src/drivers.ts
+/** node:sqlite — local development, tests and any Node deployment. */
+var NodeSqlDriver = class {
+	#db;
+	constructor(db) {
+		this.#db = db;
+	}
+	all(sql, ...params) {
+		return this.#db.prepare(sql).all(...params);
+	}
+	run(sql, ...params) {
+		this.#db.prepare(sql).run(...params);
+	}
+	/** Synchronous from BEGIN to COMMIT, so no other call can interleave on the connection. */
+	transaction(statements) {
+		this.#db.exec("BEGIN IMMEDIATE");
+		try {
+			const counts = statements.map(({ sql, params = [] }) => Number(this.#db.prepare(sql).run(...params).changes));
+			this.#db.exec("COMMIT");
+			return counts;
+		} catch (error) {
+			this.#db.exec("ROLLBACK");
+			throw error;
+		}
+	}
+};
+/**
+* Durable Object SQLite storage: pass `ctx.storage`. Synchronous; BLOBs come
+* back as ArrayBuffer. Transactions use `transactionSync`, since `sql.exec`
+* rejects `BEGIN`.
+*/
+var DoSqlDriver = class {
+	#storage;
+	constructor(storage) {
+		this.#storage = storage;
+	}
+	all(sql, ...params) {
+		return this.#storage.sql.exec(sql, ...params).toArray();
+	}
+	run(sql, ...params) {
+		this.#storage.sql.exec(sql, ...params).toArray();
+	}
+	/**
+	* Counts come from SQLite's `changes()` on the same connection, not from the
+	* cursor's `rowsWritten`, which also counts every index row a write touches.
+	*/
+	transaction(statements) {
+		return this.#storage.transactionSync(() => statements.map(({ sql, params = [] }) => {
+			this.#storage.sql.exec(sql, ...params).toArray();
+			const [row] = this.#storage.sql.exec("SELECT changes() AS n").toArray();
+			return row.n;
+		}));
+	}
+};
+/** Cloudflare D1. Asynchronous; BLOBs come back as number[]; transactions are `batch()`. */
+var D1SqlDriver = class {
+	#db;
+	constructor(db) {
+		this.#db = db;
+	}
+	async all(sql, ...params) {
+		const { results } = await this.#db.prepare(sql).bind(...params).all();
+		return results;
+	}
+	async run(sql, ...params) {
+		await this.#db.prepare(sql).bind(...params).run();
+	}
+	async transaction(statements) {
+		if (statements.length === 0) return [];
+		return (await this.#db.batch(statements.map(({ sql, params = [] }) => this.#db.prepare(sql).bind(...params)))).map((result) => result.meta.changes);
+	}
+};
+//#endregion
+//#region src/sqlar-files-api.ts
+/**
+* The table, verbatim from the SQLite Archive specification. Five columns,
+* `name` as the primary key and nothing more: any extra column, index or table
+* and other SQLAR tools may not recognise the archive.
+*/
+const SCHEMA = `CREATE TABLE IF NOT EXISTS sqlar(
+  name TEXT PRIMARY KEY,  -- name of the file
+  mode INT,               -- access permissions
+  mtime INT,              -- last modification time
+  sz INT,                 -- original file size
+  data BLOB               -- compressed content
+)`;
+const FILE_MODE = 33188;
+const DIR_MODE = 16877;
+const LINK_MODE = 41471;
+/** Links followed before a path counts as unresolvable (POSIX ELOOP territory). */
+const MAX_SYMLINK_HOPS = 8;
+/**
+* A FilesApi whose whole state is one SQLite Archive table.
+*
+* SQLAR can also hold symlinks, which `FileKind` cannot express. The FilesApi
+* view follows them the way POSIX `stat()` does — an unresolvable link is a
+* missing path — and {@link symlink} / {@link readlink} expose the link itself.
+*/
+var SqlarFilesApi = class {
+	#sql;
+	#codec;
+	constructor(sql, opts = {}) {
+		this.#sql = sql;
+		this.#codec = opts.codec ?? defaultCodec();
+	}
+	/** Creates the table if it is missing. Await it before any other call. */
+	async init() {
+		await this.#sql.run(SCHEMA);
+	}
+	/** A missing path or a directory yields nothing; a file yields one chunk. */
+	async *read(path, options = {}) {
+		options.signal?.throwIfAborted();
+		const resolved = await this.#resolve(toName(path));
+		if (resolved?.stats.kind !== "file") return;
+		const rows = await this.#sql.all("SELECT data FROM sqlar WHERE name = ?", resolved.name);
+		const content = await this.#content(resolved.name, resolved.stats.size, toBytes(rows[0]?.data));
+		options.signal?.throwIfAborted();
+		const start = options.start ?? 0;
+		const end = options.length === void 0 ? content.byteLength : start + options.length;
+		const chunk = content.subarray(start, Math.min(end, content.byteLength));
+		if (chunk.byteLength > 0) yield chunk;
+	}
+	async write(path, content) {
+		const name = toName(path);
+		const bytes = await concat(content);
+		await this.mkdir(parentName(name));
+		let data = bytes;
+		if (bytes.byteLength >= this.#codec.minSize) {
+			const deflated = await this.#codec.deflate(bytes);
+			if (deflated.byteLength < bytes.byteLength) data = deflated;
+		}
+		await this.#put(name, FILE_MODE, bytes.byteLength, data);
+	}
+	/** `sz = 0` with `data IS NULL` is the format's only marker for a directory. */
+	async mkdir(path) {
+		const name = toName(path);
+		for (const dir of ancestorsAndSelf(name)) if (!await this.#row(dir)) await this.#put(dir, DIR_MODE, 0, null);
+	}
+	/** Writes a symlink row: `sz = -1`, the target verbatim as TEXT. */
+	async symlink(path, target) {
+		const name = toName(path);
+		await this.mkdir(parentName(name));
+		await this.#put(name, LINK_MODE, -1, target);
+	}
+	/** The stored target of a symlink, or `undefined` for anything else. */
+	async readlink(path) {
+		const row = await this.#row(toName(path));
+		return row && isSymlink(row) ? linkTarget(row) : void 0;
+	}
+	async stats(path) {
+		return (await this.#resolve(toName(path)))?.stats;
+	}
+	async exists(path) {
+		return await this.#resolve(toName(path)) !== void 0;
+	}
+	/**
+	* SQLAR is a flat keyspace, so the tree is derived from names: a path that
+	* only exists as a prefix of other names is yielded as a directory, once,
+	* before anything under it. Link entries report their target's stats; a
+	* recursive listing never descends through one, which rules out cycles.
+	*/
+	/**
+	* Rows come back in name order, but implicit directories and resolved links
+	* do not sit where `comparePaths` puts them, so the entries are collected,
+	* sorted and filtered by `after`. This backend already loads every row of
+	* the directory; sorting them costs no extra reads.
+	*/
+	async *list(path, options = {}) {
+		const entries = [];
+		for await (const entry of this.#listUnordered(path, options)) entries.push(entry);
+		entries.sort((a, b) => comparePaths(a.path, b.path));
+		for (const entry of entries) if (options.after === void 0 || comparePaths(entry.path, options.after) > 0) yield entry;
+	}
+	async *#listUnordered(path, options) {
+		const requested = toName(path);
+		const resolved = await this.#resolve(requested);
+		if (resolved?.stats.kind !== "directory") return;
+		const base = resolved.name;
+		const range = descendants(base);
+		const rows = await this.#sql.all(`SELECT ${ROW_COLUMNS} FROM sqlar WHERE ${range.where} ORDER BY name`, ...range.params);
+		const prefixLength = base === "" ? 0 : base.length + 1;
+		const seen = /* @__PURE__ */ new Set();
+		for (const row of rows) {
+			const relative = row.name.slice(prefixLength);
+			const segments = relative.split("/");
+			const depth = options.recursive ? segments.length : 1;
+			for (let i = 1; i < Math.min(depth + 1, segments.length); i++) {
+				const dir = segments.slice(0, i).join("/");
+				if (seen.has(dir)) continue;
+				seen.add(dir);
+				yield {
+					kind: "directory",
+					name: segments[i - 1],
+					path: `/${joinName(requested, dir)}`
+				};
+			}
+			if (segments.length > depth || seen.has(relative)) continue;
+			seen.add(relative);
+			const stats = isSymlink(row) ? (await this.#resolve(row.name))?.stats : toStats(row);
+			if (!stats) continue;
+			yield {
+				...stats,
+				name: segments[segments.length - 1],
+				path: `/${joinName(requested, relative)}`
+			};
+		}
+	}
+	async remove(path) {
+		const range = selfAndDescendants(toName(path));
+		if ((await this.#sql.all(`SELECT 1 FROM sqlar WHERE ${range.where} LIMIT 1`, ...range.params)).length === 0) return false;
+		await this.#sql.run(`DELETE FROM sqlar WHERE ${range.where}`, ...range.params);
+		return true;
+	}
+	/**
+	* Rows are copied verbatim — mode, sz and the stored data — so a compressed
+	* row is never inflated and deflated again. Only mtime is fresh.
+	*/
+	async copy(source, target) {
+		const from = toName(source);
+		const to = toName(target);
+		const range = selfAndDescendants(from);
+		const rows = await this.#sql.all(`SELECT name, mode, sz, typeof(data) AS dtype, data FROM sqlar WHERE ${range.where}`, ...range.params);
+		if (rows.length === 0) return false;
+		await this.mkdir(parentName(to));
+		for (const row of rows) {
+			const name = joinName(to, row.name.slice(from.length).replace(/^\//, ""));
+			await this.#put(name, row.mode, row.sz, storedData(row.dtype, row.data));
+		}
+		return true;
+	}
+	async move(source, target) {
+		if (!await this.copy(source, target)) return false;
+		await this.remove(source);
+		return true;
+	}
+	/** `length(data) = sz` is plaintext, `< sz` is compressed, `> sz` is corrupt. */
+	async #content(name, sz, data) {
+		if (data.byteLength === sz) return data;
+		if (data.byteLength > sz) throw new Error(`sqlar: ${name} has length(data)=${data.byteLength} > sz=${sz}`);
+		let inflated;
+		try {
+			inflated = await this.#codec.inflate(data);
+		} catch (cause) {
+			const reason = cause instanceof Error && cause.message ? cause.message : String(cause);
+			throw new Error(`sqlar: ${name} cannot be inflated: ${reason}`, { cause });
+		}
+		if (inflated.byteLength !== sz) throw new Error(`sqlar: ${name} inflated ${inflated.byteLength} bytes, sz ${sz}`);
+		return inflated;
+	}
+	/**
+	* The entry a stored name leads to, following symlinks in the final
+	* component. `undefined` for a missing path, a dangling link or a chain
+	* longer than {@link MAX_SYMLINK_HOPS}.
+	*/
+	async #resolve(start) {
+		let name = start;
+		for (let hops = 0;; hops++) {
+			if (name === "") return {
+				name,
+				stats: { kind: "directory" }
+			};
+			const row = await this.#row(name);
+			if (!row) return await this.#hasDescendants(name) ? {
+				name,
+				stats: { kind: "directory" }
+			} : void 0;
+			if (!isSymlink(row)) return {
+				name,
+				stats: toStats(row)
+			};
+			if (hops === MAX_SYMLINK_HOPS) return void 0;
+			name = resolveTarget(row.name, linkTarget(row));
+		}
+	}
+	async #row(name) {
+		return (await this.#sql.all(`SELECT ${ROW_COLUMNS} FROM sqlar WHERE name = ?`, name))[0];
+	}
+	async #hasDescendants(name) {
+		const range = descendants(name);
+		return (await this.#sql.all(`SELECT 1 FROM sqlar WHERE ${range.where} LIMIT 1`, ...range.params)).length > 0;
+	}
+	async #put(name, mode, sz, data) {
+		await this.#sql.run(`INSERT INTO sqlar (name, mode, mtime, sz, data) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(name) DO UPDATE SET
+         mode = excluded.mode, mtime = excluded.mtime, sz = excluded.sz, data = excluded.data`, name, mode, Math.floor(Date.now() / 1e3), sz, data);
+	}
+};
+const ROW_COLUMNS = "name, mode, mtime, sz, typeof(data) AS dtype, CASE WHEN sz = -1 THEN data END AS target";
+/** Classification follows sz and data only: other writers may not set mode's type bits. */
+function isSymlink(row) {
+	return row.sz === -1;
+}
+function toStats(row) {
+	if (row.sz === 0 && row.dtype === "null") return { kind: "directory" };
+	return {
+		kind: "file",
+		size: row.sz,
+		lastModified: row.mtime * 1e3
+	};
+}
+/**
+* Every name strictly under `name`, as a range on the primary key. `LIKE`
+* would be shorter and wrong: it is case-insensitive for ASCII, so "a/%" also
+* matches "A/x", and it cannot use the index. "0" is the character after "/".
+*/
+function descendants(name) {
+	if (name === "") return {
+		where: "1",
+		params: []
+	};
+	return {
+		where: "(name > ? AND name < ?)",
+		params: [`${name}/`, `${name}0`]
+	};
+}
+function selfAndDescendants(name) {
+	if (name === "") return descendants(name);
+	const range = descendants(name);
+	return {
+		where: `(name = ? OR ${range.where})`,
+		params: [name, ...range.params]
+	};
+}
+/** A FilesApi path as a stored name: normalised, without the leading slash. The root is "". */
+function toName(path) {
+	return normalizePath(path).slice(1);
+}
+function joinName(base, rest) {
+	if (base === "") return rest;
+	return rest === "" ? base : `${base}/${rest}`;
+}
+function parentName(name) {
+	const i = name.lastIndexOf("/");
+	return i === -1 ? "" : name.slice(0, i);
+}
+function linkTarget(row) {
+	return typeof row.target === "string" ? row.target : new TextDecoder().decode(toBytes(row.target));
+}
+/**
+* A link target as a stored name: absolute from the root, relative from the
+* link's parent, with "." and ".." collapsed.
+*/
+function resolveTarget(linkName, target) {
+	const out = target.startsWith("/") ? [] : parentName(linkName).split("/").filter(Boolean);
+	for (const segment of target.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") out.pop();
+		else out.push(segment);
+	}
+	return out.join("/");
+}
+/** A selected `data` value, ready to bind again: NULL, TEXT or a byte blob. */
+function storedData(dtype, data) {
+	if (dtype === "null") return null;
+	if (dtype === "text") return typeof data === "string" ? data : new TextDecoder().decode(toBytes(data));
+	return toBytes(data);
+}
+/** "a/b/c" → ["a", "a/b", "a/b/c"]; the root yields nothing. */
+function ancestorsAndSelf(name) {
+	if (name === "") return [];
+	const parts = name.split("/");
+	return parts.map((_, i) => parts.slice(0, i + 1).join("/"));
+}
+async function concat(content) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of content) {
+		chunks.push(chunk);
+		total += chunk.byteLength;
+	}
+	const out = new Uint8Array(total);
+	let at = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, at);
+		at += chunk.byteLength;
+	}
+	return out;
+}
+//#endregion
+export { D1SqlDriver, DoSqlDriver, NodeSqlDriver, SqlarFilesApi, SqliteFilesApi, defaultCodec, pakoCodec, pakoDeflateCodec, rawCodec, webCodec, webDeflateCodec };