@statewalker/webrun-files 0.10.4 → 0.11.0

package/README.md

@@ -107,6 +107,86 @@ for (;;) {
 }
 ```
 
+### Take a lock: create a file only if it is absent
+
+```typescript
+const lock = '/repo/.git/index.lock';
+if (!files.createExclusive) throw new Error('this storage cannot hold a lock');
+
+if (!(await files.createExclusive(lock, [new TextEncoder().encode(String(Date.now()))]))) {
+  throw new Error('index.lock exists: another writer holds the lock');
+}
+try {
+  await files.write('/repo/.git/index.new', newIndex);
+  await files.move('/repo/.git/index.new', '/repo/.git/index');
+} finally {
+  await files.remove(lock);
+}
+```
+
+`createExclusive(path, content)` creates the file and returns `true` only if nothing exists at
+the path; of several concurrent calls for one path at most one wins (none, if the winner's source
+fails). It returns `false`, writing no file, for an existing file, directory or link. Parent
+directories are created, and may stay created even when the call returns `false`; a source that
+fails part way leaves no file and rethrows. Checking `exists()` and then calling `write()` cannot
+do this: another process, tab or connection can create the file between the two calls.
+
+Only the creation is atomic, not the content. On some backends (node) the file is visible while
+its content is written, so a reader can see it empty or partial until the call completes. When
+readers must see the whole content at once, create a temporary file and `move` it into place.
+
+The method is optional, because not every storage can create atomically. Feature-detect it as
+above and decide what to do without it: refuse, or fall back to check-then-write where a single
+writer is guaranteed anyway. How far the exclusion reaches is the implementation's:
+
+| Package | Mechanism | Excludes |
+| --- | --- | --- |
+| `webrun-files-mem` | synchronous check and reservation | callers sharing the instance |
+| `webrun-files-node` | `open(path, "wx")` (`O_CREAT \| O_EXCL`) | every process on the filesystem |
+| `webrun-files-browser` | Web Lock around check and create | every tab and worker of the origin |
+| `webrun-files-sqlite` | `INSERT ... ON CONFLICT DO NOTHING` | every connection to the database |
+| `webrun-files-s3` | `PutObject` with `If-None-Match: *` | every client of the bucket |
+| `webrun-files-composite` | the owning backend's method | as far as that backend's does |
+
+`webrun-files-http` and `webrun-files-rpc` do not offer it yet: neither protocol has a
+conditional create.
+
+### Replace a file atomically: write a temporary, then `move` it
+
+```typescript
+await files.write('/repo/.git/index.lock', newIndex);
+await files.move('/repo/.git/index.lock', '/repo/.git/index'); // replaces the old index
+```
+
+`move(source, target)` replaces an existing file at the target and creates the target's parent
+directories. It returns `false` when the move did not happen: the source is missing, or the
+backend refused the target. Source and target are then unchanged, though parent directories
+created for the target (node, browser) may be left. Moving onto an existing directory differs
+between backends: node, mem, the browser and `cow` follow `rename(2)` (a directory replaces an empty directory; anything else returns
+`false`), while the sqlite backends replace the target's whole subtree. Portable code does not
+move onto directories.
+
+Where the storage allows it, the move is atomic: readers see the old file or the new one, never
+a missing or partial target, and a failed move changes nothing.
+
+| Package | Mechanism | Atomic |
+| --- | --- | --- |
+| `webrun-files-node` | `fs.rename` | yes |
+| `webrun-files-mem` | one synchronous re-keying of the entries | yes |
+| `webrun-files-sqlite` | one transaction renaming rows by prefix | yes |
+| `webrun-files-browser` | native `FileSystemHandle.move()` (Chromium, OPFS) | yes |
+| `webrun-files-browser` | copy, then delete, without native `move()` | no |
+| `webrun-files-s3` | `CopyObject`, then `DeleteObject` | no |
+| `webrun-files-composite` | the backend's `move` within a mount; copy, then delete, across mounts | as the backend; no across mounts |
+| `webrun-files-composite` `cow` | copy into the writable layer, then remove or hide the source | no |
+| `webrun-files-http`, `webrun-files-rpc` | the server's backend | as the server's backend |
+
+A copy-then-delete move that copied but cannot remove its source retries the removal once, then
+throws a `MoveIncompleteError` (exported here, with `source` and `target`): the target already
+holds the new content and the source still exists. Backends built on copy-then-delete call
+`removeMovedSource(files, source, target)` to get this behaviour. The http and rpc clients rebuild
+a server-side `MoveIncompleteError` as one.
+
 ### Paths
 
 ```typescript
@@ -186,8 +266,11 @@ Two consequences:
 - Return exactly one metadata variant: a file with both numbers, a directory with only `kind`.
 - List in the order above and honour `after` exactly: the entries after a path are the same, in
   the same order, as the matching suffix of the full listing.
+- Define `createExclusive` only if the storage can keep its promise, and document how far the
+  exclusion reaches. A wrapper defines it only when what it wraps does, so feature detection on
+  the wrapper stays truthful.
 
-The shared suites in `@statewalker/webrun-files-tests` (a private workspace package) check both at
+The shared suites in `@statewalker/webrun-files-tests` (a private workspace package) check these at
 runtime. `listInPathOrder` gives both properties to a backend that can read one directory at a
 time.
 

package/dist/cjs/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/file-utils.ts
+// src/file-utils.ts
 /**
 * Collect async iterable chunks into a single Uint8Array.
 */
@@ -88,8 +88,7 @@ async function readAt(files, path, buffer, bufferOffset, length, position) {
 async function writeText(files, path, content) {
 	await files.write(path, [new TextEncoder().encode(content)]);
 }
-//#endregion
-//#region src/list-order.ts
+// src/list-order.ts
 /**
 * 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
@@ -211,8 +210,48 @@ var PathHeap = class {
 		return comparePaths(this.#key(a), this.#key(b)) < 0;
 	}
 };
-//#endregion
-//#region src/path-utils.ts
+// src/move-utils.ts
+/**
+* Thrown by a `move` done as copy-then-delete when the copy succeeded but the source
+* could not be removed, even on a second attempt. The move is half done: the target
+* already holds the moved content (an existing target was replaced), and the source
+* still exists. A `false` would wrongly say that nothing happened, so this is thrown
+* instead.
+*
+* @example
+* try {
+*   await files.move("/repo/index.lock", "/repo/index");
+* } catch (error) {
+*   if (error instanceof MoveIncompleteError) await files.remove(error.source);
+*   else throw error;
+* }
+*/
+var MoveIncompleteError = class extends Error {
+	source;
+	target;
+	name = "MoveIncompleteError";
+	constructor(source, target, options) {
+		super(`move ${source} -> ${target}: the target was replaced, but the source could not be removed`, options);
+		this.source = source;
+		this.target = target;
+	}
+};
+/**
+* The second half of a copy-then-delete `move`: remove `source` after it has been copied
+* to `target`. A failed removal (an error, or `false` while the source still exists) is
+* retried once; should that fail too, {@link MoveIncompleteError} is thrown, carrying the
+* last error as its cause. A source that is already gone counts as removed.
+*/
+async function removeMovedSource(files, source, target) {
+	let cause;
+	for (let attempt = 0; attempt < 2; attempt++) try {
+		if (await files.remove(source) || !await files.exists(source)) return;
+	} catch (error) {
+		cause = error;
+	}
+	throw new MoveIncompleteError(source, target, { cause });
+}
+// src/path-utils.ts
 /**
 * Path manipulation utilities for virtual filesystem paths.
 * All paths use forward slashes and start with "/".
@@ -263,7 +302,7 @@ function extname(path) {
 	if (dotIndex <= 0) return "";
 	return name.substring(dotIndex);
 }
-//#endregion
+exports.MoveIncompleteError = MoveIncompleteError;
 exports.basename = basename;
 exports.comparePaths = comparePaths;
 exports.dirname = dirname;
@@ -276,6 +315,7 @@ exports.readAt = readAt;
 exports.readFile = readFile;
 exports.readRange = readRange;
 exports.readText = readText;
+exports.removeMovedSource = removeMovedSource;
 exports.tryReadFile = tryReadFile;
 exports.tryReadText = tryReadText;
 exports.writeText = writeText;

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-//#region src/file-utils.ts
+// src/file-utils.ts
 /**
 * Collect async iterable chunks into a single Uint8Array.
 */
@@ -87,8 +87,7 @@ async function readAt(files, path, buffer, bufferOffset, length, position) {
 async function writeText(files, path, content) {
 	await files.write(path, [new TextEncoder().encode(content)]);
 }
-//#endregion
-//#region src/list-order.ts
+// src/list-order.ts
 /**
 * 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
@@ -210,8 +209,48 @@ var PathHeap = class {
 		return comparePaths(this.#key(a), this.#key(b)) < 0;
 	}
 };
-//#endregion
-//#region src/path-utils.ts
+// src/move-utils.ts
+/**
+* Thrown by a `move` done as copy-then-delete when the copy succeeded but the source
+* could not be removed, even on a second attempt. The move is half done: the target
+* already holds the moved content (an existing target was replaced), and the source
+* still exists. A `false` would wrongly say that nothing happened, so this is thrown
+* instead.
+*
+* @example
+* try {
+*   await files.move("/repo/index.lock", "/repo/index");
+* } catch (error) {
+*   if (error instanceof MoveIncompleteError) await files.remove(error.source);
+*   else throw error;
+* }
+*/
+var MoveIncompleteError = class extends Error {
+	source;
+	target;
+	name = "MoveIncompleteError";
+	constructor(source, target, options) {
+		super(`move ${source} -> ${target}: the target was replaced, but the source could not be removed`, options);
+		this.source = source;
+		this.target = target;
+	}
+};
+/**
+* The second half of a copy-then-delete `move`: remove `source` after it has been copied
+* to `target`. A failed removal (an error, or `false` while the source still exists) is
+* retried once; should that fail too, {@link MoveIncompleteError} is thrown, carrying the
+* last error as its cause. A source that is already gone counts as removed.
+*/
+async function removeMovedSource(files, source, target) {
+	let cause;
+	for (let attempt = 0; attempt < 2; attempt++) try {
+		if (await files.remove(source) || !await files.exists(source)) return;
+	} catch (error) {
+		cause = error;
+	}
+	throw new MoveIncompleteError(source, target, { cause });
+}
+// src/path-utils.ts
 /**
 * Path manipulation utilities for virtual filesystem paths.
 * All paths use forward slashes and start with "/".
@@ -262,5 +301,4 @@ function extname(path) {
 	if (dotIndex <= 0) return "";
 	return name.substring(dotIndex);
 }
-//#endregion
-export { basename, comparePaths, dirname, extname, joinPath, listInPathOrder, mergeInPathOrder, normalizePath, readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText };
+export { MoveIncompleteError, basename, comparePaths, dirname, extname, joinPath, listInPathOrder, mergeInPathOrder, normalizePath, readAt, readFile, readRange, readText, removeMovedSource, tryReadFile, tryReadText, writeText };

package/dist/index.d.ts

@@ -17,6 +17,7 @@
  */
 export { readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText, } from "./file-utils.js";
 export { comparePaths, listInPathOrder, mergeInPathOrder } from "./list-order.js";
+export { MoveIncompleteError, removeMovedSource } from "./move-utils.js";
 export { basename, dirname, extname, joinPath, normalizePath, } from "./path-utils.js";
 export type { DirectoryEntryInfo, DirectoryEntryStats, FileEntryInfo, FileEntryLocation, FileEntryStats, FileInfo, FileKind, FileStats, FilesApi, ListOptions, ReadOptions, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElF,OAAO,EACL,QAAQ,EACR,OAAO,EACP,OAAO,EACP,QAAQ,EACR,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,OAAO,EACL,QAAQ,EACR,OAAO,EACP,OAAO,EACP,QAAQ,EACR,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/move-utils.d.ts

@@ -0,0 +1,38 @@
+import type { FilesApi } from "./types.js";
+/**
+ * Thrown by a `move` done as copy-then-delete when the copy succeeded but the source
+ * could not be removed, even on a second attempt. The move is half done: the target
+ * already holds the moved content (an existing target was replaced), and the source
+ * still exists. A `false` would wrongly say that nothing happened, so this is thrown
+ * instead.
+ *
+ * @example
+ * try {
+ *   await files.move("/repo/index.lock", "/repo/index");
+ * } catch (error) {
+ *   if (error instanceof MoveIncompleteError) await files.remove(error.source);
+ *   else throw error;
+ * }
+ */
+export declare class MoveIncompleteError extends Error {
+    /** The path that still exists and could not be removed. */
+    readonly source: string;
+    /** The path that now holds the moved content. */
+    readonly target: string;
+    readonly name = "MoveIncompleteError";
+    constructor(
+    /** The path that still exists and could not be removed. */
+    source: string, 
+    /** The path that now holds the moved content. */
+    target: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The second half of a copy-then-delete `move`: remove `source` after it has been copied
+ * to `target`. A failed removal (an error, or `false` while the source still exists) is
+ * retried once; should that fail too, {@link MoveIncompleteError} is thrown, carrying the
+ * last error as its cause. A source that is already gone counts as removed.
+ */
+export declare function removeMovedSource(files: Pick<FilesApi, "remove" | "exists">, source: string, target: string): Promise<void>;
+//# sourceMappingURL=move-utils.d.ts.map

package/dist/move-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-utils.d.ts","sourceRoot":"","sources":["../src/move-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAI1C,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM;IANzB,SAAkB,IAAI,yBAAyB;IAE/C;IACE,2DAA2D;IAClD,MAAM,EAAE,MAAM;IACvB,iDAAiD;IACxC,MAAM,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAM9B;CACF;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAAC,EAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/types.d.ts

@@ -117,6 +117,39 @@ export interface FilesApi {
      * Overwrites existing file content.
      */
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /**
+     * Create `path` with `content` only if nothing exists there, atomically: of two
+     * concurrent calls for one path, at most one returns true. Returns false, and writes no
+     * file, when the path already exists, whether as a file, a directory or a link.
+     * Parent directories are created as needed, and may be left created even when the call
+     * returns false. If the content fails part way, the file is removed again and the
+     * error is thrown.
+     *
+     * Only the creation is atomic, not the content: on some backends (node) the file is
+     * visible while its content is written, so a reader can see it empty or partial until
+     * the call completes. Callers that need readers to see the whole content at once
+     * should create a temporary file and `move` it into place.
+     *
+     * This is the primitive behind lock files (git's `index.lock`, `refs/heads/main.lock`):
+     * take the lock by creating the file, release it by removing or renaming it.
+     *
+     * OPTIONAL. Storages that cannot create atomically leave it out, so code written
+     * against an older `FilesApi` keeps compiling and an implementation never claims a
+     * guarantee it cannot keep. Callers feature-detect it and choose their own fallback:
+     *
+     * @example
+     * if (!api.createExclusive) throw new Error("this storage cannot hold a lock");
+     * const locked = await api.createExclusive("/repo/.git/index.lock", [bytes]);
+     * if (!locked) throw new Error("index.lock exists: another process holds the lock");
+     *
+     * How far the exclusion reaches depends on the implementation, and each one
+     * documents it: an in-memory store excludes callers sharing that instance, a local
+     * filesystem every process on the machine, the browser every tab and worker of the
+     * origin, a database every connection to it, an object store every client of the
+     * bucket. Two different `FilesApi` instances over the same storage exclude each other
+     * only as far as that reach extends.
+     */
+    createExclusive?(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     /**
      * Create a directory and all parent directories.
      * No-op if directory already exists.
@@ -146,8 +179,45 @@ export interface FilesApi {
      */
     remove(path: string): Promise<boolean>;
     /**
-     * Move/rename a file or directory.
-     * Returns true on success, false if source doesn't exist.
+     * Move/rename a file or directory, with everything under it, creating the target's
+     * parent directories as needed. Returns true on success, and false when the move did
+     * not happen: the source does not exist, or the backend refused the target (below).
+     * Source and target are then unchanged, but parent directories created for the target
+     * may be left behind even when `move` returns false (node and the browser create them
+     * before moving).
+     *
+     * @example
+     * // Publish a new index: write a lock file, then move it over the real one.
+     * await files.write("/repo/.git/index.lock", [bytes]);
+     * await files.move("/repo/.git/index.lock", "/repo/.git/index");
+     *
+     * An existing FILE at the target is replaced. That is the pattern above, and every
+     * implementation supports it.
+     *
+     * An existing DIRECTORY at the target is backend specific. Filesystem-like backends
+     * follow POSIX `rename(2)`: node, mem, the browser and `cow` replace an EMPTY directory with
+     * a directory, and return false, changing nothing, for a directory onto a non-empty
+     * directory, a file onto a directory, a directory onto a file, or a directory into
+     * its own subtree. The sqlite backends replace the target's whole subtree, and throw
+     * when one path contains the other (Sqlar returns false for a target below a file).
+     * Portable callers do not move onto directories.
+     *
+     * ATOMICITY. Where the backend allows it, a move is atomic: a reader sees the old
+     * state or the new one, never the target missing or partial, and a failed move
+     * changes nothing. That holds for node (`rename(2)`), mem (one synchronous step),
+     * sqlite (one transaction) and the browser where the native `FileSystemHandle.move()`
+     * exists (Chromium, OPFS). It does NOT hold where the move is a copy then a delete:
+     * s3 (no rename), the browser without native move, a `CompositeFilesApi` move across
+     * mounts, the copy-on-write layer (`cow` from webrun-files-composite, which copies into
+     * its writable layer, then removes or hides the source), and http/rpc clients, which
+     * inherit whatever the server's backend does.
+     *
+     * PARTIAL FAILURE of a copy-then-delete move: if the copy fails, the error is thrown
+     * and the source is kept (the target may hold part of a directory copy; a single file
+     * is replaced whole or not at all on the browser). If the copy succeeds but deleting
+     * the source fails, the delete is retried once and then a `MoveIncompleteError` is
+     * thrown: the target already holds the new content and the source still exists.
+     * False is never returned for a half-done move.
      */
     move(source: string, target: string): Promise<boolean>;
     /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAE7D,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAc,SAAQ,cAAc,EAAE,iBAAiB;CAAG;AAE3E,uCAAuC;AACvC,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB,EAAE,iBAAiB;CAAG;AAErF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAErE;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9F;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAEnE;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAEpD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvD;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAE7D,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAc,SAAQ,cAAc,EAAE,iBAAiB;CAAG;AAE3E,uCAAuC;AACvC,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB,EAAE,iBAAiB;CAAG;AAErF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAErE;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,eAAe,CAAC,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAEnE;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAEpD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvD;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "private": false,
   "type": "module",
   "description": "FilesApi interface and utilities for cross-platform filesystem abstraction",

package/src/index.ts

@@ -28,6 +28,8 @@ export {
 } from "./file-utils.js";
 // Listing order
 export { comparePaths, listInPathOrder, mergeInPathOrder } from "./list-order.js";
+// Moves done as copy-then-delete
+export { MoveIncompleteError, removeMovedSource } from "./move-utils.js";
 // Path utilities
 export {
   basename,

package/src/move-utils.ts

@@ -0,0 +1,55 @@
+import type { FilesApi } from "./types.js";
+
+/**
+ * Thrown by a `move` done as copy-then-delete when the copy succeeded but the source
+ * could not be removed, even on a second attempt. The move is half done: the target
+ * already holds the moved content (an existing target was replaced), and the source
+ * still exists. A `false` would wrongly say that nothing happened, so this is thrown
+ * instead.
+ *
+ * @example
+ * try {
+ *   await files.move("/repo/index.lock", "/repo/index");
+ * } catch (error) {
+ *   if (error instanceof MoveIncompleteError) await files.remove(error.source);
+ *   else throw error;
+ * }
+ */
+export class MoveIncompleteError extends Error {
+  override readonly name = "MoveIncompleteError";
+
+  constructor(
+    /** The path that still exists and could not be removed. */
+    readonly source: string,
+    /** The path that now holds the moved content. */
+    readonly target: string,
+    options?: { cause?: unknown },
+  ) {
+    super(
+      `move ${source} -> ${target}: the target was replaced, but the source could not be removed`,
+      options,
+    );
+  }
+}
+
+/**
+ * The second half of a copy-then-delete `move`: remove `source` after it has been copied
+ * to `target`. A failed removal (an error, or `false` while the source still exists) is
+ * retried once; should that fail too, {@link MoveIncompleteError} is thrown, carrying the
+ * last error as its cause. A source that is already gone counts as removed.
+ */
+export async function removeMovedSource(
+  files: Pick<FilesApi, "remove" | "exists">,
+  source: string,
+  target: string,
+): Promise<void> {
+  let cause: unknown;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      if ((await files.remove(source)) || !(await files.exists(source))) return;
+    } catch (error) {
+      cause = error;
+    }
+  }
+  throw new MoveIncompleteError(source, target, { cause });
+}

package/src/types.ts

@@ -128,6 +128,43 @@ export interface FilesApi {
    */
   write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
 
+  /**
+   * Create `path` with `content` only if nothing exists there, atomically: of two
+   * concurrent calls for one path, at most one returns true. Returns false, and writes no
+   * file, when the path already exists, whether as a file, a directory or a link.
+   * Parent directories are created as needed, and may be left created even when the call
+   * returns false. If the content fails part way, the file is removed again and the
+   * error is thrown.
+   *
+   * Only the creation is atomic, not the content: on some backends (node) the file is
+   * visible while its content is written, so a reader can see it empty or partial until
+   * the call completes. Callers that need readers to see the whole content at once
+   * should create a temporary file and `move` it into place.
+   *
+   * This is the primitive behind lock files (git's `index.lock`, `refs/heads/main.lock`):
+   * take the lock by creating the file, release it by removing or renaming it.
+   *
+   * OPTIONAL. Storages that cannot create atomically leave it out, so code written
+   * against an older `FilesApi` keeps compiling and an implementation never claims a
+   * guarantee it cannot keep. Callers feature-detect it and choose their own fallback:
+   *
+   * @example
+   * if (!api.createExclusive) throw new Error("this storage cannot hold a lock");
+   * const locked = await api.createExclusive("/repo/.git/index.lock", [bytes]);
+   * if (!locked) throw new Error("index.lock exists: another process holds the lock");
+   *
+   * How far the exclusion reaches depends on the implementation, and each one
+   * documents it: an in-memory store excludes callers sharing that instance, a local
+   * filesystem every process on the machine, the browser every tab and worker of the
+   * origin, a database every connection to it, an object store every client of the
+   * bucket. Two different `FilesApi` instances over the same storage exclude each other
+   * only as far as that reach extends.
+   */
+  createExclusive?(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean>;
+
   /**
    * Create a directory and all parent directories.
    * No-op if directory already exists.
@@ -162,8 +199,45 @@ export interface FilesApi {
   remove(path: string): Promise<boolean>;
 
   /**
-   * Move/rename a file or directory.
-   * Returns true on success, false if source doesn't exist.
+   * Move/rename a file or directory, with everything under it, creating the target's
+   * parent directories as needed. Returns true on success, and false when the move did
+   * not happen: the source does not exist, or the backend refused the target (below).
+   * Source and target are then unchanged, but parent directories created for the target
+   * may be left behind even when `move` returns false (node and the browser create them
+   * before moving).
+   *
+   * @example
+   * // Publish a new index: write a lock file, then move it over the real one.
+   * await files.write("/repo/.git/index.lock", [bytes]);
+   * await files.move("/repo/.git/index.lock", "/repo/.git/index");
+   *
+   * An existing FILE at the target is replaced. That is the pattern above, and every
+   * implementation supports it.
+   *
+   * An existing DIRECTORY at the target is backend specific. Filesystem-like backends
+   * follow POSIX `rename(2)`: node, mem, the browser and `cow` replace an EMPTY directory with
+   * a directory, and return false, changing nothing, for a directory onto a non-empty
+   * directory, a file onto a directory, a directory onto a file, or a directory into
+   * its own subtree. The sqlite backends replace the target's whole subtree, and throw
+   * when one path contains the other (Sqlar returns false for a target below a file).
+   * Portable callers do not move onto directories.
+   *
+   * ATOMICITY. Where the backend allows it, a move is atomic: a reader sees the old
+   * state or the new one, never the target missing or partial, and a failed move
+   * changes nothing. That holds for node (`rename(2)`), mem (one synchronous step),
+   * sqlite (one transaction) and the browser where the native `FileSystemHandle.move()`
+   * exists (Chromium, OPFS). It does NOT hold where the move is a copy then a delete:
+   * s3 (no rename), the browser without native move, a `CompositeFilesApi` move across
+   * mounts, the copy-on-write layer (`cow` from webrun-files-composite, which copies into
+   * its writable layer, then removes or hides the source), and http/rpc clients, which
+   * inherit whatever the server's backend does.
+   *
+   * PARTIAL FAILURE of a copy-then-delete move: if the copy fails, the error is thrown
+   * and the source is kept (the target may hold part of a directory copy; a single file
+   * is replaced whole or not at all on the browser). If the copy succeeds but deleting
+   * the source fails, the delete is retried once and then a `MoveIncompleteError` is
+   * thrown: the target already holds the new content and the source still exists.
+   * False is never returned for a half-done move.
    */
   move(source: string, target: string): Promise<boolean>;