@statewalker/webrun-files-sqlite 0.11.1 → 0.12.0

package/README.md

@@ -109,6 +109,24 @@ await files.init();
 const removed = await files.sweep({ olderThan: 60 * 60_000 }); // contents untouched for an hour
 ```
 
+### A lock row, shared by every connection
+
+```typescript
+const locked = await files.createExclusive('/jobs/nightly.lock', [new TextEncoder().encode(worker)]);
+if (!locked) return; // another connection, in this process or another, holds it
+try {
+  // ...
+} finally {
+  await files.remove('/jobs/nightly.lock');
+}
+```
+
+Both classes implement `createExclusive` with an `INSERT` that does nothing on a conflict, and
+read whether a row was inserted. SQLite runs the statement atomically and serializes writers, so
+every connection to the database file is excluded, in any process. An existing file, directory
+or (in `SqlarFilesApi`) symlink makes it return `false`, as does a name that only exists as the
+prefix of others. Nothing is visible until the content is complete.
+
 ### A portable archive with `SqlarFilesApi`
 
 ```typescript
@@ -187,9 +205,16 @@ page starts.
 Streaming happens outside transactions. Every step that changes what a path shows is one
 transaction: storing each block, finishing a write, `remove`, `copy` and `move`. A failure inside
 any of them leaves the database as it was; `move` onto an existing target never loses the target.
+`move` renames the path rows by prefix and keeps their content ids, so no content is copied, and
+the content of a replaced target is collected in the same transaction when no other path shares it.
 A write stays invisible until it finishes: if it fails, the path keeps its previous content and the
 partial content is deleted.
 
+`createExclusive` streams exactly like a write, and turns an existing path away before reading
+the content. Its last transaction inserts the path with `ON CONFLICT(path) DO NOTHING`: when
+another writer created the path while the content streamed, the insert changes nothing, the call
+returns `false`, and the unused content is deleted in that same transaction.
+
 If the process dies mid-stream, the partial content is left behind, unreferenced. `sweep` deletes
 contents that no path references and that have not been updated for `olderThan` milliseconds, with
 their blocks. A write refreshes its content with every block, so only a write stalled longer than
@@ -226,14 +251,26 @@ does. A dangling link, or a chain longer than 8, behaves as a missing path. `rem
 
 ### `SqlarFilesApi` limits
 
-- A file is one blob: `write` buffers it, `read` inflates it whole and yields one chunk.
+- A file is one blob: `write` and `createExclusive` buffer it, `read` inflates it whole and
+  yields one chunk. `createExclusive` compresses before its single
+  `INSERT ... SELECT ... WHERE NOT EXISTS (names below) ON CONFLICT(name) DO NOTHING RETURNING name`,
+  so the check for an implicit directory and the insert are one statement.
 - On Durable Objects the stored (possibly compressed) size of one file must stay under 2 MB, since
   SQLAR keeps each file in one row. A larger file fails the `write` with `string or blob too big`
   — a value limit, not corruption. Store big files with `SqliteFilesApi`, whose blocks stay under
   the limit.
-- Multi-row mutations (`copy`, `move`, `remove` of a tree) are not wrapped in a transaction: a
-  failure part-way leaves the rows already changed in place, and a `move` can leave the entry under
-  both paths.
+- `move` is one transaction through `inTransaction` (so the `Db` must carry db-sqlite's hook, as
+  for `SqliteFilesApi`): it deletes the target's subtree, creates the target's parents and renames
+  the source row and every row under it by rewriting the name prefix. The stored data is never
+  copied; mode, mtime and data stay as they were. Readers see the old state or the new one, and a
+  failure leaves source and target unchanged. Like `SqliteFilesApi`, it replaces the target's
+  subtree rather than merging into it, and throws
+  `sqlar: cannot move /a to /a/b: one contains the other` when one path contains the other. A
+  target below a file or a symlink returns `false` and changes nothing. A `Db` without the hook
+  (a wrapper that does not forward it) makes `move` reject with `inTransaction`'s
+  `this Db has no SQLite transaction hook` error.
+- The other multi-row mutations (`copy`, `remove` of a tree) are not wrapped in a transaction: a
+  failure part-way leaves the rows already changed in place.
 - `list` loads every row under the directory, then sorts the entries into path order before
   applying `after`.
 

package/dist/blocks/sqlite-files-api.d.ts

@@ -38,12 +38,27 @@ export declare class SqliteFilesApi implements FilesApi {
      * removes the pending content; a crash leaves it for {@link sweep}.
      */
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /**
+     * Streams the content exactly as {@link write} does, into a content no path shows, then
+     * points the path at it in one transaction with `INSERT ... ON CONFLICT DO NOTHING`:
+     * exclusive against every connection to the database, since SQLite serializes write
+     * transactions. Nothing is visible until the content is complete. A path that already
+     * exists is turned away before the content is read; one created meanwhile makes the
+     * final insert change nothing, and the content is collected in that same transaction.
+     */
+    createExclusive(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     mkdir(path: string): Promise<void>;
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
     remove(path: string): Promise<boolean>;
     copy(source: string, target: string): Promise<boolean>;
+    /**
+     * One transaction (see the private `#transfer`): the target's subtree is removed, its
+     * contents collected when no other path shares them, and the source's path rows are
+     * renamed by prefix, keeping their content ids, so no content is copied. Atomic for
+     * readers on every connection; a failure leaves source and target unchanged.
+     */
     move(source: string, target: string): Promise<boolean>;
     /**
      * Deletes, in one transaction, every content not updated for `olderThan`

package/dist/blocks/sqlite-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-files-api.d.ts","sourceRoot":"","sources":["../../src/blocks/sqlite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAE9C,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AAOtE,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,QAAQ;;IAS7C,YAAY,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,qBAA0B,EAqBnD;IAED,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B1B;IAIM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CA8C9E;IAID;;;;OAIG;IACG,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuEf;IA8CK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvC;IAIK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAKxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CA4B5E;IAIK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAgCK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IA6CD;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB3D;CAqEF"}
+{"version":3,"file":"sqlite-files-api.d.ts","sourceRoot":"","sources":["../../src/blocks/sqlite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAE9C,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AAOtE,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,QAAQ;;IAS7C,YAAY,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,qBAA0B,EAqBnD;IAED,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B1B;IAIM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CA8C9E;IAID;;;;OAIG;IACG,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAEf;IAED;;;;;;;OAOG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CAIlB;IAuIK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvC;IAIK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAKxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CA6B5E;IAIK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAgCK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IAED;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IA+CD;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB3D;CAqEF"}

package/dist/cjs/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region ../../node_modules/.pnpm/@statewalker+db-sqlite@0.1.0/node_modules/@statewalker/db-sqlite/dist/index.mjs
+// ../../node_modules/.pnpm/@statewalker+db-sqlite@0.1.0/node_modules/@statewalker/db-sqlite/dist/index.mjs
 /** Key under which a SQLite Db carries its transaction hook. Shared across bundles via Symbol.for. */
 const SQLITE_TRANSACTION = Symbol.for("@statewalker/db-sqlite:transaction");
 const NO_HOOK = "inTransaction: this Db has no SQLite transaction hook. It is not a @statewalker/db-sqlite* Db, or it wraps one (a wrapper object loses the hook - pass the driver's Db itself), or it is the handle of a running transaction (nesting is not supported).";
@@ -13,8 +13,7 @@ function inTransaction(db, cb) {
 	if (typeof hook !== "function") return Promise.reject(/* @__PURE__ */ new Error(NO_HOOK));
 	return hook(cb);
 }
-//#endregion
-//#region ../webrun-files/dist/esm/index.js
+// ../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
@@ -51,16 +50,14 @@ function normalizePath(filePath) {
 	if (segments.length === 0) return "/";
 	return `/${segments.join("/")}`;
 }
-//#endregion
-//#region src/bytes.ts
+// src/bytes.ts
 /** BLOBs arrive as Uint8Array from every @statewalker/db-sqlite driver; SQLAR may hold TEXT. */
 function toBytes(value) {
 	if (value instanceof Uint8Array) return value;
 	if (typeof value === "string") return new TextEncoder().encode(value);
 	return /* @__PURE__ */ new Uint8Array(0);
 }
-//#endregion
-//#region src/run-statements.ts
+// src/run-statements.ts
 /**
 * Runs the statements in order on a transaction's Db and returns, per
 * statement, the rows it changed — zero exactly when it changed nothing. The
@@ -77,8 +74,7 @@ async function runStatements(tx, statements) {
 	}
 	return counts;
 }
-//#endregion
-//#region src/blocks/byte-reader.ts
+// src/blocks/byte-reader.ts
 /**
 * Pull bytes from a chunk source in bounded pieces.
 *
@@ -134,8 +130,7 @@ async function collectBlock(chunks) {
 	}
 	return out;
 }
-//#endregion
-//#region src/blocks/sha256.ts
+// 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.
@@ -294,8 +289,7 @@ var Sha256 = class {
 		h[7] += k;
 	}
 };
-//#endregion
-//#region src/blocks/stream-codec.ts
+// 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
@@ -381,8 +375,7 @@ async function* iterate(stream) {
 		reader.releaseLock();
 	}
 }
-//#endregion
-//#region src/blocks/sqlite-files-api.ts
+// src/blocks/sqlite-files-api.ts
 const MiB = 1048576;
 /** Rows on Durable Objects are capped at 2 MB; leave room for deflate's worst case. */
 const MAX_BLOCK_SIZE_LIMIT = 1.5 * MiB;
@@ -485,7 +478,23 @@ var SqliteFilesApi = class {
 	* removes the pending content; a crash leaves it for {@link sweep}.
 	*/
 	async write(path, content) {
+		await this.#writeContent(normalizePath(path), content, false);
+	}
+	/**
+	* Streams the content exactly as {@link write} does, into a content no path shows, then
+	* points the path at it in one transaction with `INSERT ... ON CONFLICT DO NOTHING`:
+	* exclusive against every connection to the database, since SQLite serializes write
+	* transactions. Nothing is visible until the content is complete. A path that already
+	* exists is turned away before the content is read; one created meanwhile makes the
+	* final insert change nothing, and the content is collected in that same transaction.
+	*/
+	async createExclusive(path, content) {
 		const name = normalizePath(path);
+		if (name === "/" || await this.#entry(name)) return false;
+		return this.#writeContent(name, content, true);
+	}
+	/** {@link write}, or with `exclusive` {@link createExclusive}; whether the path was set. */
+	async #writeContent(name, content, exclusive) {
 		const compression = this.#codec?.name ?? "none";
 		const fid = await inTransaction(this.#db, async (tx) => (await tx.query(`INSERT INTO ${this.#files}(size, compression, block_size, hash, updated)
              VALUES (NULL, ?, ?, NULL, ?) RETURNING fid`, [
@@ -529,9 +538,11 @@ var SqliteFilesApi = class {
 				if (alive === 0) throw sweptDuringWrite(name);
 				size += raw;
 			}
-			const previous = await this.#entry(name);
-			const [finished] = await this.#transaction(this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null));
-			if (finished === 0) throw sweptDuringWrite(name);
+			const previous = exclusive ? void 0 : await this.#entry(name);
+			const statements = this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null, exclusive);
+			const counts = await this.#transaction(statements.statements);
+			if (counts[0] === 0) throw sweptDuringWrite(name);
+			return counts[statements.pathIndex] > 0;
 		} catch (error) {
 			try {
 				await reader.close();
@@ -550,9 +561,10 @@ var SqliteFilesApi = class {
 	* 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.
+	* a swept write changes nothing. With `exclusive` an existing path is left
+	* as it is, and `pathIndex` names the statement whose change count says so.
 	*/
-	#finishWrite(name, fid, size, digest, compression, previous) {
+	#finishWrite(name, fid, size, digest, compression, previous, exclusive) {
 		const now = Date.now();
 		const exists = `SELECT 1 FROM ${this.#files} WHERE fid = ?`;
 		const statements = [
@@ -582,7 +594,7 @@ var SqliteFilesApi = class {
                 ORDER BY f.fid LIMIT 1
               ), ?), ?
               WHERE EXISTS (${exists})
-              ON CONFLICT(path) DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime`,
+              ON CONFLICT(path) ${exclusive ? "DO NOTHING" : "DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime"}`,
 				params: [
 					name,
 					digest,
@@ -597,8 +609,12 @@ var SqliteFilesApi = class {
 			},
 			...this.#collect(fid)
 		];
+		const pathIndex = 1 + ancestorsAndSelf$1(parentOf(name)).length;
 		if (previous !== null && previous !== fid) statements.push(...this.#collect(previous));
-		return statements;
+		return {
+			statements,
+			pathIndex
+		};
 	}
 	async mkdir(path) {
 		const now = Date.now();
@@ -617,7 +633,7 @@ var SqliteFilesApi = class {
 		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 prefixLength = base === "/" ? 1 : [...base].length + 1;
 		const directOnly = options.recursive ? "" : "AND instr(substr(p.path, ?), '/') = 0";
 		let cursor = options.after ?? "";
 		for (;;) {
@@ -679,6 +695,12 @@ var SqliteFilesApi = class {
 	async copy(source, target) {
 		return this.#transfer(source, target, "copy");
 	}
+	/**
+	* One transaction (see the private `#transfer`): the target's subtree is removed, its
+	* contents collected when no other path shares them, and the source's path rows are
+	* renamed by prefix, keeping their content ids, so no content is copied. Atomic for
+	* readers on every connection; a failure leaves source and target unchanged.
+	*/
 	async move(source, target) {
 		return this.#transfer(source, target, "move");
 	}
@@ -691,7 +713,7 @@ var SqliteFilesApi = class {
 		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`);
+		if (isInside$1(to, from) || isInside$1(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 = {
@@ -699,6 +721,7 @@ var SqliteFilesApi = class {
 			params: inS.params
 		};
 		const now = Date.now();
+		const rest = [...from].length + 1;
 		const statements = [
 			...this.#removeTree(to, guard),
 			...ancestorsAndSelf$1(parentOf(to)).map((dir) => ({
@@ -715,7 +738,7 @@ var SqliteFilesApi = class {
                   SELECT ? || substr(p.path, ?), p.fid, ? FROM ${this.#paths} p WHERE ${range.where}`,
 				params: [
 					to,
-					from.length + 1,
+					rest,
 					now,
 					...range.params
 				]
@@ -724,7 +747,7 @@ var SqliteFilesApi = class {
                   WHERE ${range.where}`,
 				params: [
 					to,
-					from.length + 1,
+					rest,
 					now,
 					...range.params
 				]
@@ -847,7 +870,7 @@ function selfAndDescendants$1(path, alias = "p") {
 		params: [path, ...range.params]
 	};
 }
-function isInside(path, ancestor) {
+function isInside$1(path, ancestor) {
 	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
 }
 function parentOf(path) {
@@ -859,8 +882,7 @@ 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
+// src/codec.ts
 const MIN_SIZE = 64;
 /** Compression Streams — browsers, Node, Workers. No dependency. */
 function webCodec(opts = {}) {
@@ -910,8 +932,7 @@ async function pipe(bytes, transform) {
 	const stream = new Blob([bytes]).stream().pipeThrough(transform);
 	return new Uint8Array(await new Response(stream).arrayBuffer());
 }
-//#endregion
-//#region src/sqlar-files-api.ts
+// 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
@@ -964,12 +985,42 @@ var SqlarFilesApi = class {
 		const name = toName(path);
 		const bytes = await concat(content);
 		await this.mkdir(parentName(name));
-		let data = bytes;
+		await this.#put(name, FILE_MODE, bytes.byteLength, await this.#stored(bytes));
+	}
+	/**
+	* One `INSERT ... ON CONFLICT DO NOTHING RETURNING`, which SQLite runs atomically:
+	* exclusive against every connection to the database file, in any process. The
+	* statement inserts nothing when a row has the name — a file, a directory or a
+	* symlink, dangling or not — or when names below it make it an implicit directory.
+	* The content is collected (and compressed) before the statement runs, so nothing is
+	* visible until it is complete and a failing source writes nothing.
+	*/
+	async createExclusive(path, content) {
+		const name = toName(path);
+		if (name === "") return false;
+		const bytes = await concat(content);
+		const data = await this.#stored(bytes);
+		await this.mkdir(parentName(name));
+		const below = descendants(name);
+		return (await this.#db.query(`INSERT INTO sqlar (name, mode, mtime, sz, data)
+       SELECT ?, ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM sqlar WHERE ${below.where})
+       ON CONFLICT(name) DO NOTHING
+       RETURNING name`, [
+			name,
+			FILE_MODE,
+			Math.floor(Date.now() / 1e3),
+			bytes.byteLength,
+			data,
+			...below.params
+		])).length > 0;
+	}
+	/** The `data` stored for `bytes`: deflated when that is strictly shorter. */
+	async #stored(bytes) {
 		if (bytes.byteLength >= this.#codec.minSize) {
 			const deflated = await this.#codec.deflate(bytes);
-			if (deflated.byteLength < bytes.byteLength) data = deflated;
+			if (deflated.byteLength < bytes.byteLength) return deflated;
 		}
-		await this.#put(name, FILE_MODE, bytes.byteLength, data);
+		return bytes;
 	}
 	/** `sz = 0` with `data IS NULL` is the format's only marker for a directory. */
 	async mkdir(path) {
@@ -1068,10 +1119,49 @@ var SqlarFilesApi = class {
 		}
 		return true;
 	}
+	/**
+	* One transaction, through `inTransaction` (so the `Db` must carry db-sqlite's
+	* transaction hook): delete the target's subtree, create the target's parents, then
+	* rename the source row and every row under it by rewriting the name prefix. Content
+	* is never copied, only re-keyed, and mode, mtime and data stay as they were, as with
+	* `rename(2)`. Readers on any connection see the old state or the new one; a failure
+	* rolls everything back, leaving source and target unchanged.
+	*
+	* Like `SqliteFilesApi`, an existing target is replaced with its whole subtree,
+	* not merged into, and a move into the source's own subtree or onto one of its
+	* ancestors throws. A target below a file or a symlink (an ancestor of the target is
+	* one) returns false, changing nothing. A symlink is moved as a link. A move onto
+	* itself is a no-op.
+	*/
 	async move(source, target) {
-		if (!await this.copy(source, target)) return false;
-		await this.remove(source);
-		return true;
+		const from = toName(source);
+		const to = toName(target);
+		if (from === to) return this.exists(source);
+		if (isInside(to, from) || isInside(from, to)) throw new Error(`sqlar: cannot move /${from} to /${to}: one contains the other`);
+		const src = selfAndDescendants(from);
+		const dst = selfAndDescendants(to);
+		const now = Math.floor(Date.now() / 1e3);
+		return inTransaction(this.#db, async (tx) => {
+			if ((await tx.query(`SELECT 1 FROM sqlar WHERE ${src.where} LIMIT 1`, src.params)).length === 0) return false;
+			const ancestors = ancestorsAndSelf(parentName(to));
+			if (ancestors.length > 0) {
+				if ((await tx.query(`SELECT 1 FROM sqlar WHERE name IN (${ancestors.map(() => "?").join(", ")})
+           AND (sz = -1 OR NOT (sz = 0 AND typeof(data) = 'null')) LIMIT 1`, ancestors)).length > 0) return false;
+			}
+			await tx.query(`DELETE FROM sqlar WHERE ${dst.where}`, dst.params);
+			for (const dir of ancestors) await tx.query(`INSERT INTO sqlar (name, mode, mtime, sz, data) VALUES (?, ?, ?, 0, NULL)
+           ON CONFLICT(name) DO NOTHING`, [
+				dir,
+				DIR_MODE,
+				now
+			]);
+			await tx.query(`UPDATE sqlar SET name = ? || substr(name, ?) WHERE ${src.where}`, [
+				to,
+				[...from].length + 1,
+				...src.params
+			]);
+			return true;
+		});
 	}
 	/** `length(data) = sz` is plaintext, `< sz` is compressed, `> sz` is corrupt. */
 	async #content(name, sz, data) {
@@ -1171,6 +1261,10 @@ function selfAndDescendants(name) {
 function toName(path) {
 	return normalizePath(path).slice(1);
 }
+/** Whether `name` lies strictly under `ancestor`; everything lies under the root "". */
+function isInside(name, ancestor) {
+	return ancestor === "" ? name !== "" : name.startsWith(`${ancestor}/`);
+}
 function joinName(base, rest) {
 	if (base === "") return rest;
 	return rest === "" ? base : `${base}/${rest}`;
@@ -1222,7 +1316,6 @@ async function concat(content) {
 	}
 	return out;
 }
-//#endregion
 exports.SqlarFilesApi = SqlarFilesApi;
 exports.SqliteFilesApi = SqliteFilesApi;
 exports.defaultCodec = defaultCodec;

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/@statewalker+db-sqlite@0.1.0/node_modules/@statewalker/db-sqlite/dist/index.mjs
+// ../../node_modules/.pnpm/@statewalker+db-sqlite@0.1.0/node_modules/@statewalker/db-sqlite/dist/index.mjs
 /** Key under which a SQLite Db carries its transaction hook. Shared across bundles via Symbol.for. */
 const SQLITE_TRANSACTION = Symbol.for("@statewalker/db-sqlite:transaction");
 const NO_HOOK = "inTransaction: this Db has no SQLite transaction hook. It is not a @statewalker/db-sqlite* Db, or it wraps one (a wrapper object loses the hook - pass the driver's Db itself), or it is the handle of a running transaction (nesting is not supported).";
@@ -12,8 +12,7 @@ function inTransaction(db, cb) {
 	if (typeof hook !== "function") return Promise.reject(/* @__PURE__ */ new Error(NO_HOOK));
 	return hook(cb);
 }
-//#endregion
-//#region ../webrun-files/dist/esm/index.js
+// ../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
@@ -50,16 +49,14 @@ function normalizePath(filePath) {
 	if (segments.length === 0) return "/";
 	return `/${segments.join("/")}`;
 }
-//#endregion
-//#region src/bytes.ts
+// src/bytes.ts
 /** BLOBs arrive as Uint8Array from every @statewalker/db-sqlite driver; SQLAR may hold TEXT. */
 function toBytes(value) {
 	if (value instanceof Uint8Array) return value;
 	if (typeof value === "string") return new TextEncoder().encode(value);
 	return /* @__PURE__ */ new Uint8Array(0);
 }
-//#endregion
-//#region src/run-statements.ts
+// src/run-statements.ts
 /**
 * Runs the statements in order on a transaction's Db and returns, per
 * statement, the rows it changed — zero exactly when it changed nothing. The
@@ -76,8 +73,7 @@ async function runStatements(tx, statements) {
 	}
 	return counts;
 }
-//#endregion
-//#region src/blocks/byte-reader.ts
+// src/blocks/byte-reader.ts
 /**
 * Pull bytes from a chunk source in bounded pieces.
 *
@@ -133,8 +129,7 @@ async function collectBlock(chunks) {
 	}
 	return out;
 }
-//#endregion
-//#region src/blocks/sha256.ts
+// 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.
@@ -293,8 +288,7 @@ var Sha256 = class {
 		h[7] += k;
 	}
 };
-//#endregion
-//#region src/blocks/stream-codec.ts
+// 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
@@ -380,8 +374,7 @@ async function* iterate(stream) {
 		reader.releaseLock();
 	}
 }
-//#endregion
-//#region src/blocks/sqlite-files-api.ts
+// src/blocks/sqlite-files-api.ts
 const MiB = 1048576;
 /** Rows on Durable Objects are capped at 2 MB; leave room for deflate's worst case. */
 const MAX_BLOCK_SIZE_LIMIT = 1.5 * MiB;
@@ -484,7 +477,23 @@ var SqliteFilesApi = class {
 	* removes the pending content; a crash leaves it for {@link sweep}.
 	*/
 	async write(path, content) {
+		await this.#writeContent(normalizePath(path), content, false);
+	}
+	/**
+	* Streams the content exactly as {@link write} does, into a content no path shows, then
+	* points the path at it in one transaction with `INSERT ... ON CONFLICT DO NOTHING`:
+	* exclusive against every connection to the database, since SQLite serializes write
+	* transactions. Nothing is visible until the content is complete. A path that already
+	* exists is turned away before the content is read; one created meanwhile makes the
+	* final insert change nothing, and the content is collected in that same transaction.
+	*/
+	async createExclusive(path, content) {
 		const name = normalizePath(path);
+		if (name === "/" || await this.#entry(name)) return false;
+		return this.#writeContent(name, content, true);
+	}
+	/** {@link write}, or with `exclusive` {@link createExclusive}; whether the path was set. */
+	async #writeContent(name, content, exclusive) {
 		const compression = this.#codec?.name ?? "none";
 		const fid = await inTransaction(this.#db, async (tx) => (await tx.query(`INSERT INTO ${this.#files}(size, compression, block_size, hash, updated)
              VALUES (NULL, ?, ?, NULL, ?) RETURNING fid`, [
@@ -528,9 +537,11 @@ var SqliteFilesApi = class {
 				if (alive === 0) throw sweptDuringWrite(name);
 				size += raw;
 			}
-			const previous = await this.#entry(name);
-			const [finished] = await this.#transaction(this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null));
-			if (finished === 0) throw sweptDuringWrite(name);
+			const previous = exclusive ? void 0 : await this.#entry(name);
+			const statements = this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null, exclusive);
+			const counts = await this.#transaction(statements.statements);
+			if (counts[0] === 0) throw sweptDuringWrite(name);
+			return counts[statements.pathIndex] > 0;
 		} catch (error) {
 			try {
 				await reader.close();
@@ -549,9 +560,10 @@ var SqliteFilesApi = class {
 	* 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.
+	* a swept write changes nothing. With `exclusive` an existing path is left
+	* as it is, and `pathIndex` names the statement whose change count says so.
 	*/
-	#finishWrite(name, fid, size, digest, compression, previous) {
+	#finishWrite(name, fid, size, digest, compression, previous, exclusive) {
 		const now = Date.now();
 		const exists = `SELECT 1 FROM ${this.#files} WHERE fid = ?`;
 		const statements = [
@@ -581,7 +593,7 @@ var SqliteFilesApi = class {
                 ORDER BY f.fid LIMIT 1
               ), ?), ?
               WHERE EXISTS (${exists})
-              ON CONFLICT(path) DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime`,
+              ON CONFLICT(path) ${exclusive ? "DO NOTHING" : "DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime"}`,
 				params: [
 					name,
 					digest,
@@ -596,8 +608,12 @@ var SqliteFilesApi = class {
 			},
 			...this.#collect(fid)
 		];
+		const pathIndex = 1 + ancestorsAndSelf$1(parentOf(name)).length;
 		if (previous !== null && previous !== fid) statements.push(...this.#collect(previous));
-		return statements;
+		return {
+			statements,
+			pathIndex
+		};
 	}
 	async mkdir(path) {
 		const now = Date.now();
@@ -616,7 +632,7 @@ var SqliteFilesApi = class {
 		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 prefixLength = base === "/" ? 1 : [...base].length + 1;
 		const directOnly = options.recursive ? "" : "AND instr(substr(p.path, ?), '/') = 0";
 		let cursor = options.after ?? "";
 		for (;;) {
@@ -678,6 +694,12 @@ var SqliteFilesApi = class {
 	async copy(source, target) {
 		return this.#transfer(source, target, "copy");
 	}
+	/**
+	* One transaction (see the private `#transfer`): the target's subtree is removed, its
+	* contents collected when no other path shares them, and the source's path rows are
+	* renamed by prefix, keeping their content ids, so no content is copied. Atomic for
+	* readers on every connection; a failure leaves source and target unchanged.
+	*/
 	async move(source, target) {
 		return this.#transfer(source, target, "move");
 	}
@@ -690,7 +712,7 @@ var SqliteFilesApi = class {
 		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`);
+		if (isInside$1(to, from) || isInside$1(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 = {
@@ -698,6 +720,7 @@ var SqliteFilesApi = class {
 			params: inS.params
 		};
 		const now = Date.now();
+		const rest = [...from].length + 1;
 		const statements = [
 			...this.#removeTree(to, guard),
 			...ancestorsAndSelf$1(parentOf(to)).map((dir) => ({
@@ -714,7 +737,7 @@ var SqliteFilesApi = class {
                   SELECT ? || substr(p.path, ?), p.fid, ? FROM ${this.#paths} p WHERE ${range.where}`,
 				params: [
 					to,
-					from.length + 1,
+					rest,
 					now,
 					...range.params
 				]
@@ -723,7 +746,7 @@ var SqliteFilesApi = class {
                   WHERE ${range.where}`,
 				params: [
 					to,
-					from.length + 1,
+					rest,
 					now,
 					...range.params
 				]
@@ -846,7 +869,7 @@ function selfAndDescendants$1(path, alias = "p") {
 		params: [path, ...range.params]
 	};
 }
-function isInside(path, ancestor) {
+function isInside$1(path, ancestor) {
 	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
 }
 function parentOf(path) {
@@ -858,8 +881,7 @@ 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
+// src/codec.ts
 const MIN_SIZE = 64;
 /** Compression Streams — browsers, Node, Workers. No dependency. */
 function webCodec(opts = {}) {
@@ -909,8 +931,7 @@ async function pipe(bytes, transform) {
 	const stream = new Blob([bytes]).stream().pipeThrough(transform);
 	return new Uint8Array(await new Response(stream).arrayBuffer());
 }
-//#endregion
-//#region src/sqlar-files-api.ts
+// 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
@@ -963,12 +984,42 @@ var SqlarFilesApi = class {
 		const name = toName(path);
 		const bytes = await concat(content);
 		await this.mkdir(parentName(name));
-		let data = bytes;
+		await this.#put(name, FILE_MODE, bytes.byteLength, await this.#stored(bytes));
+	}
+	/**
+	* One `INSERT ... ON CONFLICT DO NOTHING RETURNING`, which SQLite runs atomically:
+	* exclusive against every connection to the database file, in any process. The
+	* statement inserts nothing when a row has the name — a file, a directory or a
+	* symlink, dangling or not — or when names below it make it an implicit directory.
+	* The content is collected (and compressed) before the statement runs, so nothing is
+	* visible until it is complete and a failing source writes nothing.
+	*/
+	async createExclusive(path, content) {
+		const name = toName(path);
+		if (name === "") return false;
+		const bytes = await concat(content);
+		const data = await this.#stored(bytes);
+		await this.mkdir(parentName(name));
+		const below = descendants(name);
+		return (await this.#db.query(`INSERT INTO sqlar (name, mode, mtime, sz, data)
+       SELECT ?, ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM sqlar WHERE ${below.where})
+       ON CONFLICT(name) DO NOTHING
+       RETURNING name`, [
+			name,
+			FILE_MODE,
+			Math.floor(Date.now() / 1e3),
+			bytes.byteLength,
+			data,
+			...below.params
+		])).length > 0;
+	}
+	/** The `data` stored for `bytes`: deflated when that is strictly shorter. */
+	async #stored(bytes) {
 		if (bytes.byteLength >= this.#codec.minSize) {
 			const deflated = await this.#codec.deflate(bytes);
-			if (deflated.byteLength < bytes.byteLength) data = deflated;
+			if (deflated.byteLength < bytes.byteLength) return deflated;
 		}
-		await this.#put(name, FILE_MODE, bytes.byteLength, data);
+		return bytes;
 	}
 	/** `sz = 0` with `data IS NULL` is the format's only marker for a directory. */
 	async mkdir(path) {
@@ -1067,10 +1118,49 @@ var SqlarFilesApi = class {
 		}
 		return true;
 	}
+	/**
+	* One transaction, through `inTransaction` (so the `Db` must carry db-sqlite's
+	* transaction hook): delete the target's subtree, create the target's parents, then
+	* rename the source row and every row under it by rewriting the name prefix. Content
+	* is never copied, only re-keyed, and mode, mtime and data stay as they were, as with
+	* `rename(2)`. Readers on any connection see the old state or the new one; a failure
+	* rolls everything back, leaving source and target unchanged.
+	*
+	* Like `SqliteFilesApi`, an existing target is replaced with its whole subtree,
+	* not merged into, and a move into the source's own subtree or onto one of its
+	* ancestors throws. A target below a file or a symlink (an ancestor of the target is
+	* one) returns false, changing nothing. A symlink is moved as a link. A move onto
+	* itself is a no-op.
+	*/
 	async move(source, target) {
-		if (!await this.copy(source, target)) return false;
-		await this.remove(source);
-		return true;
+		const from = toName(source);
+		const to = toName(target);
+		if (from === to) return this.exists(source);
+		if (isInside(to, from) || isInside(from, to)) throw new Error(`sqlar: cannot move /${from} to /${to}: one contains the other`);
+		const src = selfAndDescendants(from);
+		const dst = selfAndDescendants(to);
+		const now = Math.floor(Date.now() / 1e3);
+		return inTransaction(this.#db, async (tx) => {
+			if ((await tx.query(`SELECT 1 FROM sqlar WHERE ${src.where} LIMIT 1`, src.params)).length === 0) return false;
+			const ancestors = ancestorsAndSelf(parentName(to));
+			if (ancestors.length > 0) {
+				if ((await tx.query(`SELECT 1 FROM sqlar WHERE name IN (${ancestors.map(() => "?").join(", ")})
+           AND (sz = -1 OR NOT (sz = 0 AND typeof(data) = 'null')) LIMIT 1`, ancestors)).length > 0) return false;
+			}
+			await tx.query(`DELETE FROM sqlar WHERE ${dst.where}`, dst.params);
+			for (const dir of ancestors) await tx.query(`INSERT INTO sqlar (name, mode, mtime, sz, data) VALUES (?, ?, ?, 0, NULL)
+           ON CONFLICT(name) DO NOTHING`, [
+				dir,
+				DIR_MODE,
+				now
+			]);
+			await tx.query(`UPDATE sqlar SET name = ? || substr(name, ?) WHERE ${src.where}`, [
+				to,
+				[...from].length + 1,
+				...src.params
+			]);
+			return true;
+		});
 	}
 	/** `length(data) = sz` is plaintext, `< sz` is compressed, `> sz` is corrupt. */
 	async #content(name, sz, data) {
@@ -1170,6 +1260,10 @@ function selfAndDescendants(name) {
 function toName(path) {
 	return normalizePath(path).slice(1);
 }
+/** Whether `name` lies strictly under `ancestor`; everything lies under the root "". */
+function isInside(name, ancestor) {
+	return ancestor === "" ? name !== "" : name.startsWith(`${ancestor}/`);
+}
 function joinName(base, rest) {
 	if (base === "") return rest;
 	return rest === "" ? base : `${base}/${rest}`;
@@ -1221,5 +1315,4 @@ async function concat(content) {
 	}
 	return out;
 }
-//#endregion
 export { SqlarFilesApi, SqliteFilesApi, defaultCodec, pakoCodec, pakoDeflateCodec, rawCodec, webCodec, webDeflateCodec };

package/dist/sqlar-files-api.d.ts

@@ -20,6 +20,15 @@ export declare class SqlarFilesApi implements FilesApi {
     /** A missing path or a directory yields nothing; a file yields one chunk. */
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /**
+     * One `INSERT ... ON CONFLICT DO NOTHING RETURNING`, which SQLite runs atomically:
+     * exclusive against every connection to the database file, in any process. The
+     * statement inserts nothing when a row has the name — a file, a directory or a
+     * symlink, dangling or not — or when names below it make it an implicit directory.
+     * The content is collected (and compressed) before the statement runs, so nothing is
+     * visible until it is complete and a failing source writes nothing.
+     */
+    createExclusive(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     /** `sz = 0` with `data IS NULL` is the format's only marker for a directory. */
     mkdir(path: string): Promise<void>;
     /** Writes a symlink row: `sz = -1`, the target verbatim as TEXT. */
@@ -47,6 +56,20 @@ export declare class SqlarFilesApi implements FilesApi {
      * row is never inflated and deflated again. Only mtime is fresh.
      */
     copy(source: string, target: string): Promise<boolean>;
+    /**
+     * One transaction, through `inTransaction` (so the `Db` must carry db-sqlite's
+     * transaction hook): delete the target's subtree, create the target's parents, then
+     * rename the source row and every row under it by rewriting the name prefix. Content
+     * is never copied, only re-keyed, and mode, mtime and data stay as they were, as with
+     * `rename(2)`. Readers on any connection see the old state or the new one; a failure
+     * rolls everything back, leaving source and target unchanged.
+     *
+     * Like `SqliteFilesApi`, an existing target is replaced with its whole subtree,
+     * not merged into, and a move into the source's own subtree or onto one of its
+     * ancestors throws. A target below a file or a symlink (an ancestor of the target is
+     * one) returns false, changing nothing. A symlink is moved as a link. A move onto
+     * itself is a no-op.
+     */
     move(source: string, target: string): Promise<boolean>;
 }
 //# sourceMappingURL=sqlar-files-api.d.ts.map

package/dist/sqlar-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlar-files-api.d.ts","sourceRoot":"","sources":["../src/sqlar-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,KAAK,KAAK,EAAgB,MAAM,YAAY,CAAC;AAuBtD,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,QAAQ;;IAI5C,YAAY,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,oBAAyB,EAGlD;IAED,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;IAED,6EAA6E;IACtE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CAc9E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAYf;IAED,gFAAgF;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvC;IAED,oEAAoE;IAC9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzD;IAED,wEAAwE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGxD;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAExD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED;;;;;OAKG;IACH;;;;;OAKG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAO5E;IAwCK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU3C;IAED;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAsB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;CAoEF"}
+{"version":3,"file":"sqlar-files-api.d.ts","sourceRoot":"","sources":["../src/sqlar-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAE9C,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,KAAK,KAAK,EAAgB,MAAM,YAAY,CAAC;AAuBtD,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;;;;;GAMG;AACH,qBAAa,aAAc,YAAW,QAAQ;;IAI5C,YAAY,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,oBAAyB,EAGlD;IAED,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;IAED,6EAA6E;IACtE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CAc9E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAKf;IAED;;;;;;;OAOG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CAelB;IAYD,gFAAgF;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvC;IAED,oEAAoE;IAC9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIzD;IAED,wEAAwE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGxD;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAExD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAED;;;;;OAKG;IACH;;;;;OAKG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAO5E;IAwCK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU3C;IAED;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAsB3D;IAED;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAuC3D;CAoEF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-sqlite",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "private": false,
   "type": "module",
   "description": "SQLite-backed FilesApi implementations",
@@ -36,7 +36,7 @@
   "dependencies": {
     "@statewalker/db-api": "^0.1.3",
     "@statewalker/db-sqlite": "^0.1.0",
-    "@statewalker/webrun-files": "^0.10.4"
+    "@statewalker/webrun-files": "^0.11.0"
   },
   "devDependencies": {
     "@statewalker/db-sqlite-do": "^0.1.0",

package/src/blocks/sqlite-files-api.ts

@@ -179,7 +179,32 @@ export class SqliteFilesApi implements FilesApi {
     path: string,
     content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
   ): Promise<void> {
+    await this.#writeContent(normalizePath(path), content, false);
+  }
+
+  /**
+   * Streams the content exactly as {@link write} does, into a content no path shows, then
+   * points the path at it in one transaction with `INSERT ... ON CONFLICT DO NOTHING`:
+   * exclusive against every connection to the database, since SQLite serializes write
+   * transactions. Nothing is visible until the content is complete. A path that already
+   * exists is turned away before the content is read; one created meanwhile makes the
+   * final insert change nothing, and the content is collected in that same transaction.
+   */
+  async createExclusive(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean> {
     const name = normalizePath(path);
+    if (name === "/" || (await this.#entry(name))) return false;
+    return this.#writeContent(name, content, true);
+  }
+
+  /** {@link write}, or with `exclusive` {@link createExclusive}; whether the path was set. */
+  async #writeContent(
+    name: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+    exclusive: boolean,
+  ): Promise<boolean> {
     const compression = this.#codec?.name ?? "none";
     // In a transaction too, so a Db without db-sqlite's hook fails before writing anything.
     const fid = await inTransaction(
@@ -230,11 +255,19 @@ export class SqliteFilesApi implements FilesApi {
         size += raw;
       }
 
-      const previous = await this.#entry(name);
-      const [finished] = await this.#transaction(
-        this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null),
+      const previous = exclusive ? undefined : await this.#entry(name);
+      const statements = this.#finishWrite(
+        name,
+        fid,
+        size,
+        hash.digestHex(),
+        compression,
+        previous?.fid ?? null,
+        exclusive,
       );
-      if (finished === 0) throw sweptDuringWrite(name);
+      const counts = await this.#transaction(statements.statements);
+      if (counts[0] === 0) throw sweptDuringWrite(name);
+      return counts[statements.pathIndex] > 0;
     } catch (error) {
       try {
         await reader.close();
@@ -256,7 +289,8 @@ export class SqliteFilesApi implements FilesApi {
    * 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.
+   * a swept write changes nothing. With `exclusive` an existing path is left
+   * as it is, and `pathIndex` names the statement whose change count says so.
    */
   #finishWrite(
     name: string,
@@ -265,7 +299,8 @@ export class SqliteFilesApi implements FilesApi {
     digest: string,
     compression: string,
     previous: number | null,
-  ): SqlStatement[] {
+    exclusive: boolean,
+  ): { statements: SqlStatement[]; pathIndex: number } {
     const now = Date.now();
     const exists = `SELECT 1 FROM ${this.#files} WHERE fid = ?`;
     const statements: SqlStatement[] = [
@@ -286,13 +321,15 @@ export class SqliteFilesApi implements FilesApi {
                 ORDER BY f.fid LIMIT 1
               ), ?), ?
               WHERE EXISTS (${exists})
-              ON CONFLICT(path) DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime`,
+              ON CONFLICT(path) ${exclusive ? "DO NOTHING" : "DO UPDATE SET fid = excluded.fid, mtime = excluded.mtime"}`,
         params: [name, digest, size, compression, this.#blockSize, fid, fid, now, fid],
       },
       ...this.#collect(fid),
     ];
+    // After the content update and the parents.
+    const pathIndex = 1 + ancestorsAndSelf(parentOf(name)).length;
     if (previous !== null && previous !== fid) statements.push(...this.#collect(previous));
-    return statements;
+    return { statements, pathIndex };
   }
 
   async mkdir(path: string): Promise<void> {
@@ -323,7 +360,8 @@ export class SqliteFilesApi implements FilesApi {
     if ((await this.stats(base))?.kind !== "directory") return;
 
     const range = descendants(base);
-    const prefixLength = base === "/" ? 1 : base.length + 1;
+    // SQLite's substr() counts characters (code points), not UTF-16 units.
+    const prefixLength = base === "/" ? 1 : [...base].length + 1;
     const directOnly = options.recursive ? "" : "AND instr(substr(p.path, ?), '/') = 0";
     // The unique index orders paths by UTF-8 bytes, which is `comparePaths` order,
     // so resuming after a path is the keyset cursor's starting point.
@@ -389,6 +427,12 @@ export class SqliteFilesApi implements FilesApi {
     return this.#transfer(source, target, "copy");
   }
 
+  /**
+   * One transaction (see the private `#transfer`): the target's subtree is removed, its
+   * contents collected when no other path shares them, and the source's path rows are
+   * renamed by prefix, keeping their content ids, so no content is copied. Atomic for
+   * readers on every connection; a failure leaves source and target unchanged.
+   */
   async move(source: string, target: string): Promise<boolean> {
     return this.#transfer(source, target, "move");
   }
@@ -413,6 +457,8 @@ export class SqliteFilesApi implements FilesApi {
       params: inS.params,
     };
     const now = Date.now();
+    // SQLite's substr() counts characters (code points), not UTF-16 units.
+    const rest = [...from].length + 1;
     const statements: SqlStatement[] = [
       ...this.#removeTree(to, guard),
       ...ancestorsAndSelf(parentOf(to)).map((dir) => ({
@@ -424,12 +470,12 @@ export class SqliteFilesApi implements FilesApi {
         ? {
             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],
+            params: [to, rest, 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],
+            params: [to, rest, now, ...range.params],
           },
     ];
     const counts = await this.#transaction(statements);

package/src/sqlar-files-api.ts

@@ -1,4 +1,5 @@
 import type { Db } from "@statewalker/db-api";
+import { inTransaction } from "@statewalker/db-sqlite";
 import type {
   FileInfo,
   FileStats,
@@ -81,14 +82,45 @@ export class SqlarFilesApi implements FilesApi {
     const name = toName(path);
     const bytes = await concat(content);
     await this.mkdir(parentName(name));
+    await this.#put(name, FILE_MODE, bytes.byteLength, await this.#stored(bytes));
+  }
 
-    let data: Uint8Array = bytes;
+  /**
+   * One `INSERT ... ON CONFLICT DO NOTHING RETURNING`, which SQLite runs atomically:
+   * exclusive against every connection to the database file, in any process. The
+   * statement inserts nothing when a row has the name — a file, a directory or a
+   * symlink, dangling or not — or when names below it make it an implicit directory.
+   * The content is collected (and compressed) before the statement runs, so nothing is
+   * visible until it is complete and a failing source writes nothing.
+   */
+  async createExclusive(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean> {
+    const name = toName(path);
+    if (name === "") return false; // the root always exists
+    const bytes = await concat(content);
+    const data = await this.#stored(bytes);
+    await this.mkdir(parentName(name));
+    const below = descendants(name);
+    const rows = await this.#db.query(
+      `INSERT INTO sqlar (name, mode, mtime, sz, data)
+       SELECT ?, ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM sqlar WHERE ${below.where})
+       ON CONFLICT(name) DO NOTHING
+       RETURNING name`,
+      [name, FILE_MODE, Math.floor(Date.now() / 1000), bytes.byteLength, data, ...below.params],
+    );
+    return rows.length > 0;
+  }
+
+  /** The `data` stored for `bytes`: deflated when that is strictly shorter. */
+  async #stored(bytes: Uint8Array): Promise<Uint8Array> {
     if (bytes.byteLength >= this.#codec.minSize) {
       const deflated = await this.#codec.deflate(bytes);
       // Strictly shorter only: equal length is the plaintext marker.
-      if (deflated.byteLength < bytes.byteLength) data = deflated;
+      if (deflated.byteLength < bytes.byteLength) return deflated;
     }
-    await this.#put(name, FILE_MODE, bytes.byteLength, data);
+    return bytes;
   }
 
   /** `sz = 0` with `data IS NULL` is the format's only marker for a directory. */
@@ -219,10 +251,59 @@ export class SqlarFilesApi implements FilesApi {
     return true;
   }
 
+  /**
+   * One transaction, through `inTransaction` (so the `Db` must carry db-sqlite's
+   * transaction hook): delete the target's subtree, create the target's parents, then
+   * rename the source row and every row under it by rewriting the name prefix. Content
+   * is never copied, only re-keyed, and mode, mtime and data stay as they were, as with
+   * `rename(2)`. Readers on any connection see the old state or the new one; a failure
+   * rolls everything back, leaving source and target unchanged.
+   *
+   * Like `SqliteFilesApi`, an existing target is replaced with its whole subtree,
+   * not merged into, and a move into the source's own subtree or onto one of its
+   * ancestors throws. A target below a file or a symlink (an ancestor of the target is
+   * one) returns false, changing nothing. A symlink is moved as a link. A move onto
+   * itself is a no-op.
+   */
   async move(source: string, target: string): Promise<boolean> {
-    if (!(await this.copy(source, target))) return false;
-    await this.remove(source);
-    return true;
+    const from = toName(source);
+    const to = toName(target);
+    if (from === to) return this.exists(source);
+    if (isInside(to, from) || isInside(from, to)) {
+      throw new Error(`sqlar: cannot move /${from} to /${to}: one contains the other`);
+    }
+    const src = selfAndDescendants(from);
+    const dst = selfAndDescendants(to);
+    const now = Math.floor(Date.now() / 1000);
+    return inTransaction(this.#db, async (tx) => {
+      const found = await tx.query(`SELECT 1 FROM sqlar WHERE ${src.where} LIMIT 1`, src.params);
+      if (found.length === 0) return false;
+      // A target below a file or a symlink: refuse, changing nothing.
+      const ancestors = ancestorsAndSelf(parentName(to));
+      if (ancestors.length > 0) {
+        const blocking = await tx.query(
+          `SELECT 1 FROM sqlar WHERE name IN (${ancestors.map(() => "?").join(", ")})
+           AND (sz = -1 OR NOT (sz = 0 AND typeof(data) = 'null')) LIMIT 1`,
+          ancestors,
+        );
+        if (blocking.length > 0) return false;
+      }
+      await tx.query(`DELETE FROM sqlar WHERE ${dst.where}`, dst.params);
+      for (const dir of ancestors) {
+        await tx.query(
+          `INSERT INTO sqlar (name, mode, mtime, sz, data) VALUES (?, ?, ?, 0, NULL)
+           ON CONFLICT(name) DO NOTHING`,
+          [dir, DIR_MODE, now],
+        );
+      }
+      // SQLite's substr() counts characters (code points), not UTF-16 units.
+      await tx.query(`UPDATE sqlar SET name = ? || substr(name, ?) WHERE ${src.where}`, [
+        to,
+        [...from].length + 1,
+        ...src.params,
+      ]);
+      return true;
+    });
   }
 
   /** `length(data) = sz` is plaintext, `< sz` is compressed, `> sz` is corrupt. */
@@ -345,6 +426,11 @@ function toName(path: string): string {
   return normalizePath(path).slice(1);
 }
 
+/** Whether `name` lies strictly under `ancestor`; everything lies under the root "". */
+function isInside(name: string, ancestor: string): boolean {
+  return ancestor === "" ? name !== "" : name.startsWith(`${ancestor}/`);
+}
+
 function joinName(base: string, rest: string): string {
   if (base === "") return rest;
   return rest === "" ? base : `${base}/${rest}`;