@statewalker/webrun-files-rpc 0.1.1 → 0.2.0

package/README.md

@@ -119,6 +119,12 @@ Every argument and result is a plain value: strings, numbers, booleans, plain ob
 | `stats`, `exists` | as the `FilesApi` |
 | `mkdir(path, {requestId?})`, `remove(path, {requestId?})`, `move(source, target, {requestId?})`, `copy(source, target, {requestId?})` | as the `FilesApi`; with a `requestId`, once (a call delivered again gets the first answer) |
 
+`move` is as atomic as the served backend's `move` (node, mem, sqlite: atomic; s3 or a cross-mount
+composite: copy then delete); the protocol adds no guarantee of its own. A `MoveIncompleteError`
+thrown by the served backend is rebuilt by the client as a `MoveIncompleteError` with the client's
+paths. It is recognised by its message (`move /a -> /b: the target was replaced, but the source
+could not be removed`), since a structured clone keeps an error's message but only standard names.
+
 - **Stream ids:** `streamId` may be chosen by the caller: 16 to 128 characters of `[A-Za-z0-9_-]`,
   random, such as `crypto.randomUUID()` without dashes. Then an open delivered twice opens one
   stream; the client always does this.

package/dist/cjs/index.cjs

@@ -1,5 +1,47 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region src/client.ts
+// ../webrun-files/dist/esm/index.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;
+* }
+*/
+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;
+	}
+};
+/**
+* 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("/")}`;
+}
+// src/client.ts
 const toBytes$1 = (v) => v instanceof Uint8Array ? v : ArrayBuffer.isView(v) ? new Uint8Array(v.buffer, v.byteOffset, v.byteLength) : new Uint8Array(v);
 const newStreamId$1 = () => crypto.randomUUID().replace(/-/g, "");
 /** Cuts any sequence of byte arrays into chunks of exactly `size` bytes (the last may be shorter). */
@@ -155,8 +197,18 @@ var FilesRpcClient = class {
 	remove(path) {
 		return this.#rpc.remove(path, { requestId: newStreamId$1() });
 	}
-	move(source, target) {
-		return this.#rpc.move(source, target, { requestId: newStreamId$1() });
+	/**
+	* One `move` call: the server's backend does the move, so it is exactly as atomic as
+	* that backend's `move` (node, mem, sqlite: atomic; s3 or a cross-mount composite:
+	* copy then delete). The client adds no guarantee, and a call that fails in transit
+	* leaves it unknown whether the move happened.
+	*/
+	async move(source, target) {
+		try {
+			return await this.#rpc.move(source, target, { requestId: newStreamId$1() });
+		} catch (error) {
+			throw moveIncomplete(error, source, target);
+		}
 	}
 	copy(source, target) {
 		return this.#rpc.copy(source, target, { requestId: newStreamId$1() });
@@ -166,8 +218,17 @@ var FilesRpcClient = class {
 function newFilesRpcClient(options) {
 	return new FilesRpcClient(options);
 }
-//#endregion
-//#region src/errors.ts
+/**
+* A server-side `MoveIncompleteError` arrives as a plain error: over http with its name and
+* message, through a structured clone (rpc transports) with its message only. Recognised by
+* either, it is rebuilt with the client's paths, the original kept as its cause.
+*/
+function moveIncomplete(error, source, target) {
+	const { name, message } = error ?? {};
+	return name === "MoveIncompleteError" || typeof message === "string" && MOVE_INCOMPLETE_MESSAGE.test(message) ? new MoveIncompleteError(normalizePath(source), normalizePath(target), { cause: error }) : error;
+}
+const MOVE_INCOMPLETE_MESSAGE = /^move .* -> .*: the target was replaced, but the source could not be removed$/s;
+// src/errors.ts
 /**
 * An error of the protocol itself. The code also leads the message (`UNKNOWN_STREAM: …`), since
 * a structured clone keeps an error's name and message but not its other properties:
@@ -196,8 +257,7 @@ const CODES = /* @__PURE__ */ new Set([
 ]);
 /** A message led by a code, as FilesRpcError writes it (`CODE: …`). */
 const LEADING_CODE = new RegExp(`^(${[...CODES].join("|")}):`);
-//#endregion
-//#region src/keyed.ts
+// src/keyed.ts
 /**
 * Values kept by key, and waiters for keys that have no value yet: what both ends of a stream
 * use to keep chunks by chunkId and wait for the ones still on their way.
@@ -260,8 +320,7 @@ var Keyed = class {
 		this.#waiters.clear();
 	}
 };
-//#endregion
-//#region src/server.ts
+// src/server.ts
 /**
 * Whether a write's outcome is the FilesApi's alone: every chunk was handed to it (an emulated
 * append, until its write-back starts, can still be cancelled).
@@ -788,7 +847,6 @@ function newFilesRpcServer(options) {
 	timer?.unref?.();
 	return server;
 }
-//#endregion
 exports.FilesRpcClient = FilesRpcClient;
 exports.FilesRpcError = FilesRpcError;
 exports.errorCode = errorCode;

package/dist/client.d.ts

@@ -37,6 +37,12 @@ export declare class FilesRpcClient implements FilesApi {
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
     remove(path: string): Promise<boolean>;
+    /**
+     * One `move` call: the server's backend does the move, so it is exactly as atomic as
+     * that backend's `move` (node, mem, sqlite: atomic; s3 or a cross-mount composite:
+     * copy then delete). The client adds no guarantee, and a call that fails in transit
+     * leaves it unknown whether the move happened.
+     */
     move(source: string, target: string): Promise<boolean>;
     copy(source: string, target: string): Promise<boolean>;
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,GAAG,EAAE,QAAQ,CAAC;IACd,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyCD,0FAA0F;AAC1F,qBAAa,cAAe,YAAW,QAAQ;;IAO7C,YAAY,OAAO,EAAE,qBAAqB,EAMzC;IAED;;;OAGG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CA4C9E;IAED;;;OAGG;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;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAEf;IAsCK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;IAED,6EAA6E;IACtE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAY5E;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAElD;IACD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErC;IACD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErC;IACD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErD;IACD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErD;CACF;AAED,kCAAkC;AAClC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAEhF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,GAAG,EAAE,QAAQ,CAAC;IACd,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyCD,0FAA0F;AAC1F,qBAAa,cAAe,YAAW,QAAQ;;IAO7C,YAAY,OAAO,EAAE,qBAAqB,EAMzC;IAED;;;OAGG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CA4C9E;IAED;;;OAGG;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;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAEf;IAsCK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;IAED,6EAA6E;IACtE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CAY5E;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAElD;IACD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErC;IACD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErC;IACD;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM3D;IACD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAErD;CACF;AAED,kCAAkC;AAClC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAEhF"}

package/dist/esm/index.js

@@ -1,4 +1,46 @@
-//#region src/client.ts
+// ../webrun-files/dist/esm/index.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;
+* }
+*/
+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;
+	}
+};
+/**
+* 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("/")}`;
+}
+// src/client.ts
 const toBytes$1 = (v) => v instanceof Uint8Array ? v : ArrayBuffer.isView(v) ? new Uint8Array(v.buffer, v.byteOffset, v.byteLength) : new Uint8Array(v);
 const newStreamId$1 = () => crypto.randomUUID().replace(/-/g, "");
 /** Cuts any sequence of byte arrays into chunks of exactly `size` bytes (the last may be shorter). */
@@ -154,8 +196,18 @@ var FilesRpcClient = class {
 	remove(path) {
 		return this.#rpc.remove(path, { requestId: newStreamId$1() });
 	}
-	move(source, target) {
-		return this.#rpc.move(source, target, { requestId: newStreamId$1() });
+	/**
+	* One `move` call: the server's backend does the move, so it is exactly as atomic as
+	* that backend's `move` (node, mem, sqlite: atomic; s3 or a cross-mount composite:
+	* copy then delete). The client adds no guarantee, and a call that fails in transit
+	* leaves it unknown whether the move happened.
+	*/
+	async move(source, target) {
+		try {
+			return await this.#rpc.move(source, target, { requestId: newStreamId$1() });
+		} catch (error) {
+			throw moveIncomplete(error, source, target);
+		}
 	}
 	copy(source, target) {
 		return this.#rpc.copy(source, target, { requestId: newStreamId$1() });
@@ -165,8 +217,17 @@ var FilesRpcClient = class {
 function newFilesRpcClient(options) {
 	return new FilesRpcClient(options);
 }
-//#endregion
-//#region src/errors.ts
+/**
+* A server-side `MoveIncompleteError` arrives as a plain error: over http with its name and
+* message, through a structured clone (rpc transports) with its message only. Recognised by
+* either, it is rebuilt with the client's paths, the original kept as its cause.
+*/
+function moveIncomplete(error, source, target) {
+	const { name, message } = error ?? {};
+	return name === "MoveIncompleteError" || typeof message === "string" && MOVE_INCOMPLETE_MESSAGE.test(message) ? new MoveIncompleteError(normalizePath(source), normalizePath(target), { cause: error }) : error;
+}
+const MOVE_INCOMPLETE_MESSAGE = /^move .* -> .*: the target was replaced, but the source could not be removed$/s;
+// src/errors.ts
 /**
 * An error of the protocol itself. The code also leads the message (`UNKNOWN_STREAM: …`), since
 * a structured clone keeps an error's name and message but not its other properties:
@@ -195,8 +256,7 @@ const CODES = /* @__PURE__ */ new Set([
 ]);
 /** A message led by a code, as FilesRpcError writes it (`CODE: …`). */
 const LEADING_CODE = new RegExp(`^(${[...CODES].join("|")}):`);
-//#endregion
-//#region src/keyed.ts
+// src/keyed.ts
 /**
 * Values kept by key, and waiters for keys that have no value yet: what both ends of a stream
 * use to keep chunks by chunkId and wait for the ones still on their way.
@@ -259,8 +319,7 @@ var Keyed = class {
 		this.#waiters.clear();
 	}
 };
-//#endregion
-//#region src/server.ts
+// src/server.ts
 /**
 * Whether a write's outcome is the FilesApi's alone: every chunk was handed to it (an emulated
 * append, until its write-back starts, can still be cancelled).
@@ -787,5 +846,4 @@ function newFilesRpcServer(options) {
 	timer?.unref?.();
 	return server;
 }
-//#endregion
 export { FilesRpcClient, FilesRpcError, errorCode, newFilesRpcClient, newFilesRpcServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-rpc",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "FilesApi over any RPC: streamed reads and writes as chunks kept and awaited by (streamId, chunkId)",
@@ -34,7 +34,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.4"
+    "@statewalker/webrun-files": "^0.11.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
@@ -42,7 +42,7 @@
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.4 || ^5.0.3",
-    "@statewalker/webrun-files-mem": "^0.10.4",
+    "@statewalker/webrun-files-mem": "^0.11.0",
     "@statewalker/webrun-files-tests": "^3.0.0"
   },
   "sideEffects": false,

package/src/client.ts

@@ -5,6 +5,7 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
+import { MoveIncompleteError, normalizePath } from "@statewalker/webrun-files";
 import type { FilesRpc, ReadResult } from "./types.js";
 
 export interface FilesRpcClientOptions {
@@ -211,8 +212,18 @@ export class FilesRpcClient implements FilesApi {
   remove(path: string): Promise<boolean> {
     return this.#rpc.remove(path, { requestId: newStreamId() });
   }
-  move(source: string, target: string): Promise<boolean> {
-    return this.#rpc.move(source, target, { requestId: newStreamId() });
+  /**
+   * One `move` call: the server's backend does the move, so it is exactly as atomic as
+   * that backend's `move` (node, mem, sqlite: atomic; s3 or a cross-mount composite:
+   * copy then delete). The client adds no guarantee, and a call that fails in transit
+   * leaves it unknown whether the move happened.
+   */
+  async move(source: string, target: string): Promise<boolean> {
+    try {
+      return await this.#rpc.move(source, target, { requestId: newStreamId() });
+    } catch (error) {
+      throw moveIncomplete(error, source, target);
+    }
   }
   copy(source: string, target: string): Promise<boolean> {
     return this.#rpc.copy(source, target, { requestId: newStreamId() });
@@ -223,3 +234,21 @@ export class FilesRpcClient implements FilesApi {
 export function newFilesRpcClient(options: FilesRpcClientOptions): FilesRpcClient {
   return new FilesRpcClient(options);
 }
+
+/**
+ * A server-side `MoveIncompleteError` arrives as a plain error: over http with its name and
+ * message, through a structured clone (rpc transports) with its message only. Recognised by
+ * either, it is rebuilt with the client's paths, the original kept as its cause.
+ */
+function moveIncomplete(error: unknown, source: string, target: string): unknown {
+  const { name, message } = (error ?? {}) as { name?: unknown; message?: unknown };
+  const recognised =
+    name === "MoveIncompleteError" ||
+    (typeof message === "string" && MOVE_INCOMPLETE_MESSAGE.test(message));
+  return recognised
+    ? new MoveIncompleteError(normalizePath(source), normalizePath(target), { cause: error })
+    : error;
+}
+
+const MOVE_INCOMPLETE_MESSAGE =
+  /^move .* -> .*: the target was replaced, but the source could not be removed$/s;