@statewalker/webrun-files-node 0.9.0 → 0.10.0

package/README.md

@@ -32,7 +32,11 @@ console.log(content); // {"debug": true}
 
 // List files
 for await (const entry of files.list('/')) {
-  console.log(entry.name, entry.kind, entry.size);
+  if (entry.kind === 'file') {
+    console.log(entry.name, entry.kind, entry.size, entry.lastModified);
+  } else {
+    console.log(entry.name, entry.kind); // directories carry no size or time
+  }
 }
 ```
 
@@ -57,6 +61,9 @@ virtual path: "/users/alice.json"
 real path: "/var/app/data/users/alice.json"
 ```
 
+Paths are appended to `rootDir` without confinement: `..` segments are kept, not resolved, so a
+virtual path such as `/../etc/passwd` reaches outside `rootDir`. Do not pass untrusted paths.
+
 ## API Reference
 
 ### NodeFilesApi
@@ -65,7 +72,7 @@ real path: "/var/app/data/users/alice.json"
 interface NodeFilesApiOptions {
   /**
    * Root directory for file operations.
-   * All paths are resolved relative to this directory.
+   * Virtual paths are appended to this directory (see "Path Mapping" for `..`).
    * Defaults to current working directory if not specified.
    */
   rootDir?: string;
@@ -114,9 +121,17 @@ Parent directories are created automatically when writing files:
 await writeText(files, '/deep/nested/path/file.txt', 'content');
 ```
 
+### Ordered Listings
+
+`readdir` returns names in no guaranteed order, so `list()` reads each directory, stats its entries
+and yields them in path order (as every `FilesApi` does). A recursive listing reads a directory only
+when the listing reaches it, and with `{ after }` skips any directory whose whole subtree sorts at
+or before the cursor.
+
 ### Recursive Operations
 
-Copy and remove work recursively on directories:
+Copy and remove work recursively on directories. `move()` is a single `fs.rename`: when the rename
+fails — for example across devices — it returns `false` rather than falling back to copying.
 
 ```typescript
 // Copy entire directory tree
@@ -133,6 +148,7 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { NodeFilesApi } from '@statewalker/webrun-files-node';
+import { writeText } from '@statewalker/webrun-files';
 
 // Create a temp directory for testing
 const tempDir = await mkdtemp(join(tmpdir(), 'test-'));

package/dist/cjs/index.cjs

@@ -25,6 +25,89 @@ let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises, 1);
 //#region ../webrun-files/dist/esm/index.js
 /**
+* The order every `FilesApi.list()` yields: paths compared by Unicode code
+* point, which is the same as comparing their UTF-8 bytes — the order of
+* SQLite's `BINARY` collation and of S3 key listings.
+*
+* Not JavaScript's `<`, which compares UTF-16 code units and so puts a
+* character above U+FFFF (a surrogate pair) before U+E000–U+FFFF.
+*/
+function comparePaths(a, b) {
+	const length = Math.min(a.length, b.length);
+	for (let i = 0; i < length; i++) {
+		const x = a.charCodeAt(i);
+		const y = b.charCodeAt(i);
+		if (x === y) continue;
+		const xSurrogate = x >= 55296 && x <= 57343;
+		if (xSurrogate !== (y >= 55296 && y <= 57343)) return xSurrogate ? 1 : -1;
+		return x - y;
+	}
+	return a.length - b.length;
+}
+/** Whether a listing resuming after `after` can still yield anything under `dir`. */
+function subtreeMayFollow(dir, after) {
+	return after === void 0 || comparePaths(after, `${dir === "/" ? "" : dir}0`) < 0;
+}
+/**
+* List a tree in path order for backends that read one directory at a time.
+* `children(dir)` returns a directory's direct entries in any order.
+*
+* Pending entries sit in a min-heap keyed by path. A directory's children all
+* sort after it, so pushing them when the directory is taken never yields out
+* of order. Children are read only when the listing reaches their directory,
+* and never for a directory whose whole subtree lies at or before `after`.
+*/
+async function* listInPathOrder(dir, children, options = {}) {
+	const { recursive = false, after } = options;
+	const heap = new PathHeap((entry) => entry.path);
+	if (!subtreeMayFollow(dir, after)) return;
+	for (const entry of await children(dir)) heap.push(entry);
+	for (let entry = heap.pop(); entry; entry = heap.pop()) {
+		if (after === void 0 || comparePaths(entry.path, after) > 0) yield entry;
+		if (recursive && entry.kind === "directory" && subtreeMayFollow(entry.path, after)) for (const child of await children(entry.path)) heap.push(child);
+	}
+}
+/** A binary min-heap ordered by {@link comparePaths}. */
+var PathHeap = class {
+	#items = [];
+	#key;
+	constructor(key) {
+		this.#key = key;
+	}
+	push(item) {
+		const items = this.#items;
+		items.push(item);
+		for (let i = items.length - 1; i > 0;) {
+			const parent = i - 1 >> 1;
+			if (this.#less(items[parent], items[i])) break;
+			[items[parent], items[i]] = [items[i], items[parent]];
+			i = parent;
+		}
+	}
+	pop() {
+		const items = this.#items;
+		const top = items[0];
+		const last = items.pop();
+		if (items.length > 0 && last !== void 0) {
+			items[0] = last;
+			for (let i = 0;;) {
+				const left = 2 * i + 1;
+				const right = left + 1;
+				let smallest = i;
+				if (left < items.length && this.#less(items[left], items[smallest])) smallest = left;
+				if (right < items.length && this.#less(items[right], items[smallest])) smallest = right;
+				if (smallest === i) break;
+				[items[smallest], items[i]] = [items[i], items[smallest]];
+				i = smallest;
+			}
+		}
+		return top;
+	}
+	#less(a, b) {
+		return comparePaths(this.#key(a), this.#key(b)) < 0;
+	}
+};
+/**
 * Path manipulation utilities for virtual filesystem paths.
 * All paths use forward slashes and start with "/".
 */
@@ -123,36 +206,40 @@ var NodeFilesApi = class {
 		const realPath = this.resolvePath(path);
 		await node_fs_promises.mkdir(realPath, { recursive: true });
 	}
+	/** `readdir` order is unspecified, so the tree is walked in `comparePaths` order. */
 	async *list(path, options) {
-		const realPath = this.resolvePath(path);
-		const normalizedPath = normalizePath(path);
+		yield* listInPathOrder(normalizePath(path), (dir) => this.readChildren(dir), options);
+	}
+	/** A directory's direct entries, in `readdir` order; none if it cannot be read. */
+	async readChildren(dir) {
+		let entries;
 		try {
-			const entries = await node_fs_promises.readdir(realPath, { withFileTypes: true });
-			for (const entry of entries) {
-				const entryPath = joinPath(normalizedPath, entry.name);
-				const fullPath = this.resolvePath(entryPath);
-				let stat;
-				try {
-					stat = await node_fs_promises.stat(fullPath);
-				} catch {
-					continue;
-				}
-				yield entry.isDirectory() ? {
-					name: entry.name,
-					path: entryPath,
-					kind: "directory"
-				} : {
-					name: entry.name,
-					path: entryPath,
-					kind: "file",
-					size: stat.size,
-					lastModified: stat.mtimeMs
-				};
-				if (options?.recursive && entry.isDirectory()) yield* this.list(entryPath, options);
-			}
+			entries = await node_fs_promises.readdir(this.resolvePath(dir), { withFileTypes: true });
 		} catch {
-			return;
+			return [];
+		}
+		const infos = [];
+		for (const entry of entries) {
+			const entryPath = joinPath(dir, entry.name);
+			let stat;
+			try {
+				stat = await node_fs_promises.stat(this.resolvePath(entryPath));
+			} catch {
+				continue;
+			}
+			infos.push(entry.isDirectory() ? {
+				name: entry.name,
+				path: entryPath,
+				kind: "directory"
+			} : {
+				name: entry.name,
+				path: entryPath,
+				kind: "file",
+				size: stat.size,
+				lastModified: stat.mtimeMs
+			});
 		}
+		return infos;
 	}
 	async stats(path) {
 		const realPath = this.resolvePath(path);

package/dist/esm/index.js

@@ -1,6 +1,89 @@
 import * as fs from "node:fs/promises";
 //#region ../webrun-files/dist/esm/index.js
 /**
+* The order every `FilesApi.list()` yields: paths compared by Unicode code
+* point, which is the same as comparing their UTF-8 bytes — the order of
+* SQLite's `BINARY` collation and of S3 key listings.
+*
+* Not JavaScript's `<`, which compares UTF-16 code units and so puts a
+* character above U+FFFF (a surrogate pair) before U+E000–U+FFFF.
+*/
+function comparePaths(a, b) {
+	const length = Math.min(a.length, b.length);
+	for (let i = 0; i < length; i++) {
+		const x = a.charCodeAt(i);
+		const y = b.charCodeAt(i);
+		if (x === y) continue;
+		const xSurrogate = x >= 55296 && x <= 57343;
+		if (xSurrogate !== (y >= 55296 && y <= 57343)) return xSurrogate ? 1 : -1;
+		return x - y;
+	}
+	return a.length - b.length;
+}
+/** Whether a listing resuming after `after` can still yield anything under `dir`. */
+function subtreeMayFollow(dir, after) {
+	return after === void 0 || comparePaths(after, `${dir === "/" ? "" : dir}0`) < 0;
+}
+/**
+* List a tree in path order for backends that read one directory at a time.
+* `children(dir)` returns a directory's direct entries in any order.
+*
+* Pending entries sit in a min-heap keyed by path. A directory's children all
+* sort after it, so pushing them when the directory is taken never yields out
+* of order. Children are read only when the listing reaches their directory,
+* and never for a directory whose whole subtree lies at or before `after`.
+*/
+async function* listInPathOrder(dir, children, options = {}) {
+	const { recursive = false, after } = options;
+	const heap = new PathHeap((entry) => entry.path);
+	if (!subtreeMayFollow(dir, after)) return;
+	for (const entry of await children(dir)) heap.push(entry);
+	for (let entry = heap.pop(); entry; entry = heap.pop()) {
+		if (after === void 0 || comparePaths(entry.path, after) > 0) yield entry;
+		if (recursive && entry.kind === "directory" && subtreeMayFollow(entry.path, after)) for (const child of await children(entry.path)) heap.push(child);
+	}
+}
+/** A binary min-heap ordered by {@link comparePaths}. */
+var PathHeap = class {
+	#items = [];
+	#key;
+	constructor(key) {
+		this.#key = key;
+	}
+	push(item) {
+		const items = this.#items;
+		items.push(item);
+		for (let i = items.length - 1; i > 0;) {
+			const parent = i - 1 >> 1;
+			if (this.#less(items[parent], items[i])) break;
+			[items[parent], items[i]] = [items[i], items[parent]];
+			i = parent;
+		}
+	}
+	pop() {
+		const items = this.#items;
+		const top = items[0];
+		const last = items.pop();
+		if (items.length > 0 && last !== void 0) {
+			items[0] = last;
+			for (let i = 0;;) {
+				const left = 2 * i + 1;
+				const right = left + 1;
+				let smallest = i;
+				if (left < items.length && this.#less(items[left], items[smallest])) smallest = left;
+				if (right < items.length && this.#less(items[right], items[smallest])) smallest = right;
+				if (smallest === i) break;
+				[items[smallest], items[i]] = [items[i], items[smallest]];
+				i = smallest;
+			}
+		}
+		return top;
+	}
+	#less(a, b) {
+		return comparePaths(this.#key(a), this.#key(b)) < 0;
+	}
+};
+/**
 * Path manipulation utilities for virtual filesystem paths.
 * All paths use forward slashes and start with "/".
 */
@@ -99,36 +182,40 @@ var NodeFilesApi = class {
 		const realPath = this.resolvePath(path);
 		await fs.mkdir(realPath, { recursive: true });
 	}
+	/** `readdir` order is unspecified, so the tree is walked in `comparePaths` order. */
 	async *list(path, options) {
-		const realPath = this.resolvePath(path);
-		const normalizedPath = normalizePath(path);
+		yield* listInPathOrder(normalizePath(path), (dir) => this.readChildren(dir), options);
+	}
+	/** A directory's direct entries, in `readdir` order; none if it cannot be read. */
+	async readChildren(dir) {
+		let entries;
 		try {
-			const entries = await fs.readdir(realPath, { withFileTypes: true });
-			for (const entry of entries) {
-				const entryPath = joinPath(normalizedPath, entry.name);
-				const fullPath = this.resolvePath(entryPath);
-				let stat;
-				try {
-					stat = await fs.stat(fullPath);
-				} catch {
-					continue;
-				}
-				yield entry.isDirectory() ? {
-					name: entry.name,
-					path: entryPath,
-					kind: "directory"
-				} : {
-					name: entry.name,
-					path: entryPath,
-					kind: "file",
-					size: stat.size,
-					lastModified: stat.mtimeMs
-				};
-				if (options?.recursive && entry.isDirectory()) yield* this.list(entryPath, options);
-			}
+			entries = await fs.readdir(this.resolvePath(dir), { withFileTypes: true });
 		} catch {
-			return;
+			return [];
+		}
+		const infos = [];
+		for (const entry of entries) {
+			const entryPath = joinPath(dir, entry.name);
+			let stat;
+			try {
+				stat = await fs.stat(this.resolvePath(entryPath));
+			} catch {
+				continue;
+			}
+			infos.push(entry.isDirectory() ? {
+				name: entry.name,
+				path: entryPath,
+				kind: "directory"
+			} : {
+				name: entry.name,
+				path: entryPath,
+				kind: "file",
+				size: stat.size,
+				lastModified: stat.mtimeMs
+			});
 		}
+		return infos;
 	}
 	async stats(path) {
 		const realPath = this.resolvePath(path);

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

@@ -17,7 +17,10 @@ export declare class NodeFilesApi implements FilesApi {
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
     mkdir(path: string): Promise<void>;
+    /** `readdir` order is unspecified, so the tree is walked in `comparePaths` order. */
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    /** A directory's direct entries, in `readdir` order; none if it cannot be read. */
+    private readChildren;
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
     remove(path: string): Promise<boolean>;

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

@@ -1 +1 @@
-{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,CAAC,EAAE,mBAAmB,EAExC;IAED,OAAO,CAAC,WAAW;IAKZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuBf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAsCxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAkBxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;CACF"}
+{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,CAAC,EAAE,mBAAmB,EAExC;IAED,OAAO,CAAC,WAAW;IAKZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuBf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED,qFAAqF;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAExE;IAED,mFAAmF;YACrE,YAAY;IAgCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAkBxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-node",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "type": "module",
   "description": "Node.js FilesApi implementation",
@@ -29,7 +29,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "0.9.0"
+    "@statewalker/webrun-files": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -37,7 +37,7 @@
     "rolldown": "^1.2.4",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@statewalker/webrun-files-tests": "2.0.0"
+    "@statewalker/webrun-files-tests": "3.0.0"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/node-files-api.ts

@@ -1,4 +1,4 @@
-import type { Stats } from "node:fs";
+import type { Dirent, Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import type {
   FileInfo,
@@ -7,7 +7,7 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
-import { dirname, joinPath, normalizePath } from "@statewalker/webrun-files";
+import { dirname, joinPath, listInPathOrder, normalizePath } from "@statewalker/webrun-files";
 
 export interface NodeFilesApiOptions {
   /**
@@ -109,25 +109,31 @@ export class NodeFilesApi implements FilesApi {
     await fs.mkdir(realPath, { recursive: true });
   }
 
+  /** `readdir` order is unspecified, so the tree is walked in `comparePaths` order. */
   async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
-    const realPath = this.resolvePath(path);
-    const normalizedPath = normalizePath(path);
+    yield* listInPathOrder(normalizePath(path), (dir) => this.readChildren(dir), options);
+  }
 
+  /** A directory's direct entries, in `readdir` order; none if it cannot be read. */
+  private async readChildren(dir: string): Promise<FileInfo[]> {
+    let entries: Dirent[];
     try {
-      const entries = await fs.readdir(realPath, { withFileTypes: true });
-
-      for (const entry of entries) {
-        const entryPath = joinPath(normalizedPath, entry.name);
-        const fullPath = this.resolvePath(entryPath);
-
-        let stat: Stats;
-        try {
-          stat = await fs.stat(fullPath);
-        } catch {
-          continue;
-        }
-
-        const info: FileInfo = entry.isDirectory()
+      entries = await fs.readdir(this.resolvePath(dir), { withFileTypes: true });
+    } catch {
+      // Directory doesn't exist or can't be read
+      return [];
+    }
+    const infos: FileInfo[] = [];
+    for (const entry of entries) {
+      const entryPath = joinPath(dir, entry.name);
+      let stat: Stats;
+      try {
+        stat = await fs.stat(this.resolvePath(entryPath));
+      } catch {
+        continue;
+      }
+      infos.push(
+        entry.isDirectory()
           ? { name: entry.name, path: entryPath, kind: "directory" }
           : {
               name: entry.name,
@@ -135,18 +141,10 @@ export class NodeFilesApi implements FilesApi {
               kind: "file",
               size: stat.size,
               lastModified: stat.mtimeMs,
-            };
-
-        yield info;
-
-        if (options?.recursive && entry.isDirectory()) {
-          yield* this.list(entryPath, options);
-        }
-      }
-    } catch {
-      // Directory doesn't exist or can't be read
-      return;
+            },
+      );
     }
+    return infos;
   }
 
   async stats(path: string): Promise<FileStats | undefined> {