@statewalker/webrun-files-composite 0.9.0 → 0.10.0

package/README.md

@@ -4,7 +4,7 @@
 
 A small toolkit of `FilesApi` decorators that lets you build a layered
 virtual filesystem on top of any existing `FilesApi` implementation. It
-ships three building blocks:
+ships three decorator classes and three layering helpers:
 
 - **`CompositeFilesApi`** — mounts multiple `FilesApi` backends at different
   composite-namespace prefixes (longest-prefix wins), with optional
@@ -13,6 +13,19 @@ ships three building blocks:
   per-operation policies that can deny access by throwing.
 - **`FilteredFilesApi`** — hides selected paths so that the wrapped API
   behaves as if they did not exist.
+- **`readOnly(api)`** — a read-only view: every mutating call (`write`,
+  `mkdir`, `remove`, `move`, `copy`) throws `"read-only: <path>"`.
+- **`overlay(top, ...lower)`** — a read-only union of layers: reads resolve
+  top → bottom, `list` merges and dedupes with the upper layer winning, and
+  every mutation throws.
+- **`cow(base, writable, opts?)`** — copy-on-write: all changes go to
+  `writable` and `base` is never mutated; deletions persist as whiteout
+  (`.wh.<name>`) and opaque (`.wh..opq`) marker files, whose names
+  `CowOptions` can change.
+
+`globToRegExp(glob, { extended?, globstar?, flags? })` is exported too, with
+the types `PathFilter`, `FileGuard`, `FileOperation`, `CowOptions` and
+`GlobToRegExpOptions`.
 
 ## Why it exists
 
@@ -26,7 +39,9 @@ This package keeps each backend pure and pushes composition / access /
 visibility into orthogonal decorators that can be stacked in any order. The
 three concerns are deliberately split across separate classes:
 
-- **mounting** is structural and never throws — `CompositeFilesApi`.
+- **mounting** is structural and never denies access — `CompositeFilesApi`.
+  (It throws only on invalid mount operations: mounting at `/`, removing a
+  mount point.)
 - **access control** must throw to stay safe by default — `GuardedFilesApi`.
 - **visibility** must silently lie to keep the consumer model simple —
   `FilteredFilesApi`.
@@ -152,15 +167,18 @@ const guarded = new GuardedFilesApi(fs, [
 ```
 
 Guards are evaluated in the order they were passed. The first denying
-guard throws `Error("<message>: <normalized-path>")`. A guard that lists
+guard throws `Error("<message>: <normalized-path>")`, where `message`
+defaults to `"Access denied"`. A guard that lists
 `"read"` also fires on the source side of `move`/`copy` and on every
 `exists` call; one that lists `"write"` fires on the target side of
 `move`/`copy`; one that lists `"list"` also fires on `stats`.
 
 ### Cross-mount move/copy
 
-`CompositeFilesApi` resolves `move` and `copy` across mounts by performing
-a recursive copy and (for `move`) deleting the source. Use guards/filters
+When source and target resolve to different backend instances,
+`CompositeFilesApi` performs a recursive copy and (for `move`) then removes the
+source; when both resolve to the same backend instance — even through two
+different mounts — the call is delegated to that backend's own `move`/`copy`. Use guards/filters
 to gate these flows by composite path:
 
 ```ts
@@ -190,12 +208,23 @@ filter to that mount only).
 
 ### CompositeFilesApi — path resolution
 
-1. Input paths are normalized (forward slashes, leading `/`, no trailing `/`).
+1. Input paths are normalized (leading `/`, no trailing `/`, repeated slashes
+   and `.` segments collapsed; `..` is kept as a segment, and backslashes are
+   not converted).
 2. The mount with the **longest matching prefix** wins. The implicit `/`
    mount set by the constructor is always last.
 3. The matched prefix is stripped and the mount's `fsPath` is prepended.
 4. Mount points themselves appear as synthetic directories in `list()` and
-   `stats()`, and `remove()` on a mount point throws.
+   `stats()`, and `remove()` on a mount point throws. In a listing, a mount
+   point replaces any entry the parent backend has at the same path.
+5. `list()` merges the owning backend's listing (minus the subtrees of mounts
+   inside the listed directory), each such mount's listing (recursive listings
+   include nested mounts), and the mount points, into one path-ordered stream.
+   `{ after }` is translated into each backend's own paths, and a mount whose
+   whole subtree sorts at or before it is not listed at all.
+
+`overlay` and `cow` list their merged directories in the same path order, and
+`FilteredFilesApi` and `GuardedFilesApi` pass `after` through unchanged.
 
 ### GuardedFilesApi — effective operation matrix
 

package/dist/cjs/index.cjs

@@ -1,6 +1,127 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#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);
+	}
+}
+/**
+* Merge streams that are each already in path order into one. When several
+* streams yield the same path, the entry from the earliest stream wins and
+* the others are dropped. At most one entry per stream is pulled ahead, and
+* every stream is closed when the consumer stops.
+*/
+async function* mergeInPathOrder(streams) {
+	const iterators = streams.map((stream) => stream[Symbol.asyncIterator]());
+	const heads = [];
+	const done = [];
+	const pull = async (i) => {
+		const next = await iterators[i].next();
+		done[i] = next.done === true;
+		heads[i] = next.done ? void 0 : next.value;
+	};
+	try {
+		await Promise.all(iterators.map((_, i) => pull(i)));
+		for (;;) {
+			let min = -1;
+			for (let i = 0; i < heads.length; i++) {
+				const head = heads[i];
+				if (!head) continue;
+				const current = min === -1 ? void 0 : heads[min];
+				if (!current || comparePaths(head.path, current.path) < 0) min = i;
+			}
+			if (min === -1) return;
+			const entry = heads[min];
+			for (let i = min + 1; i < heads.length; i++) while (heads[i] && heads[i]?.path === entry.path) await pull(i);
+			heads[min] = void 0;
+			yield entry;
+			await pull(min);
+		}
+	} finally {
+		await Promise.all(iterators.map(async (iterator, i) => {
+			if (!done[i]) await iterator.return?.();
+		}));
+	}
+}
+/** 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 "/".
 */
@@ -162,56 +283,60 @@ var CompositeFilesApi = class {
 		const { api, resolvedPath } = this.resolve(path);
 		return api.mkdir(resolvedPath);
 	}
+	/**
+	* Merges, in `comparePaths` order: a synthetic directory entry for each
+	* mount inside `path`; the owning backend's listing with those mounts'
+	* subtrees removed; and, when recursive, each inner mount's own listing
+	* with its nested mounts removed. Each backend's listing is already ordered
+	* and remapping a subtree's prefix keeps that order, so a k-way merge is
+	* enough. `after` is translated into each backend's namespace, and a mount
+	* whose whole subtree lies at or before it is not listed.
+	*/
 	async *list(path, options) {
 		const normalized = normalizePath(path);
-		const { api, resolvedPath } = this.resolve(path);
-		const childMounts = this.childMountPrefixes(normalized);
-		const yieldedNames = /* @__PURE__ */ new Set();
-		if (options?.recursive) {
-			for await (const entry of api.list(resolvedPath, options)) {
-				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
-				if (this.isUnderChildMount(compositePath, childMounts)) continue;
-				yieldedNames.add(entry.name);
-				yield {
-					...entry,
-					path: compositePath
-				};
-			}
-			for (const mountPrefix of childMounts) {
-				const mount = this.mounts.find((m) => m.prefix === mountPrefix);
-				if (!mount) continue;
-				yield {
-					name: mountPrefix.split("/").pop() ?? "",
-					path: mountPrefix,
-					kind: "directory"
-				};
-				for await (const entry of mount.api.list(mount.basePath, { recursive: true })) {
-					const localPath = this.stripBasePath(entry.path, mount.basePath);
-					yield {
-						...entry,
-						path: `${mountPrefix}${localPath === "/" ? "" : localPath}`
-					};
-				}
-			}
-		} else {
-			for await (const entry of api.list(resolvedPath)) {
-				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
-				yieldedNames.add(entry.name);
-				yield {
-					...entry,
-					path: compositePath
-				};
-			}
-			for (const mountPrefix of childMounts) {
-				const mountName = mountPrefix.split("/").pop() ?? "";
-				if (!yieldedNames.has(mountName)) yield {
-					name: mountName,
-					path: mountPrefix,
-					kind: "directory"
-				};
-			}
+		const recursive = options?.recursive ?? false;
+		const after = options?.after;
+		const owner = this.ownerOf(normalized);
+		const { resolvedPath } = this.resolve(normalized);
+		const inner = this.mounts.filter((m) => m.prefix !== "/" && isStrictlyInside(m.prefix, normalized));
+		const listed = recursive ? inner : this.childMountPrefixes(normalized).map((prefix) => inner.find((m) => m.prefix === prefix));
+		const streams = [];
+		streams.push(fromArray(listed.map((m) => ({
+			kind: "directory",
+			name: m.prefix.slice(m.prefix.lastIndexOf("/") + 1),
+			path: m.prefix
+		})).sort((x, y) => comparePaths(x.path, y.path))));
+		streams.push(this.remappedList(owner.api, resolvedPath, normalized, recursive, after, inner.map((m) => m.prefix)));
+		if (recursive) for (const m of inner) {
+			const nested = inner.filter((n) => isStrictlyInside(n.prefix, m.prefix)).map((n) => n.prefix);
+			streams.push(this.remappedList(m.api, m.basePath, m.prefix, true, after, nested));
+		}
+		for await (const entry of mergeInPathOrder(streams)) if (after === void 0 || comparePaths(entry.path, after) > 0) yield entry;
+	}
+	/**
+	* One backend's listing of `backendDir`, with paths moved to `compositeDir`
+	* and entries at or under any of `excluded` dropped.
+	*/
+	async *remappedList(api, backendDir, compositeDir, recursive, after, excluded) {
+		const translated = translateAfter(after, compositeDir, backendDir);
+		if (translated === SKIP) return;
+		for await (const entry of api.list(backendDir, {
+			recursive,
+			after: translated
+		})) {
+			const compositePath = this.remapPath(compositeDir, backendDir, entry.path);
+			if (this.isUnderChildMount(compositePath, excluded)) continue;
+			yield {
+				...entry,
+				path: compositePath
+			};
 		}
 	}
+	/** The mount that owns `normalized` — the longest matching prefix, else the root. */
+	ownerOf(normalized) {
+		for (const mount of this.mounts) if (mount.prefix === "/" || normalized === mount.prefix || normalized.startsWith(`${mount.prefix}/`)) return mount;
+		return this.mounts[this.mounts.length - 1];
+	}
 	async stats(path) {
 		const normalized = normalizePath(path);
 		if (this.isMountPoint(normalized)) return { kind: "directory" };
@@ -244,12 +369,6 @@ var CompositeFilesApi = class {
 		if (src.api === tgt.api) return src.api.copy(src.resolvedPath, tgt.resolvedPath);
 		return this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
 	}
-	stripBasePath(path, basePath) {
-		if (basePath === "/") return path;
-		if (path === basePath) return "/";
-		if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
-		return path;
-	}
 	async crossCopy(srcApi, srcPath, tgtApi, tgtPath) {
 		const srcStats = await srcApi.stats(srcPath);
 		if (!srcStats) return false;
@@ -276,6 +395,28 @@ var CompositeFilesApi = class {
 		return false;
 	}
 };
+const SKIP = Symbol("skip");
+/**
+* `after`, given in the `from` subtree's namespace, in the `to` subtree's
+* namespace — or {@link SKIP} when the whole `from` subtree lies at or before
+* it. Raw prefix replacement, never normalisation: normalising `"/a/"` to
+* `"/a"` would change which entries sort after it. Under-pruning is harmless
+* (the caller filters again); over-pruning is what this must never do.
+*/
+function translateAfter(after, from, to) {
+	if (after === void 0) return void 0;
+	const fromPrefix = from === "/" ? "" : from;
+	const toPrefix = to === "/" ? "" : to;
+	if (after.startsWith(`${fromPrefix}/`)) return `${toPrefix}${after.slice(fromPrefix.length)}`;
+	if (comparePaths(after, `${fromPrefix}/`) < 0) return void 0;
+	return SKIP;
+}
+function isStrictlyInside(path, ancestor) {
+	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
+}
+async function* fromArray(items) {
+	yield* items;
+}
 //#endregion
 //#region src/cow-files-api.ts
 /**
@@ -368,15 +509,11 @@ var CowFilesApi = class {
 	async exists(path) {
 		return await this.resolveLayer(path) !== "absent";
 	}
+	/** Merged children, walked in `comparePaths` order. */
 	async *list(path, options) {
-		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
-	}
-	async *listDir(dir, recursive) {
+		const dir = normalizePath(path);
 		if ((await this.stats(dir))?.kind !== "directory") return;
-		for (const entry of await this.mergeChildren(dir)) {
-			yield entry;
-			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
-		}
+		yield* listInPathOrder(dir, (d) => this.mergeChildren(d), options);
 	}
 	/** Direct children of `dir`: writable entries win, base entries fill in. */
 	async mergeChildren(dir) {
@@ -880,15 +1017,11 @@ var OverlayFilesApi = class {
 		for (const layer of this.layers) if (await layer.exists(path)) return true;
 		return false;
 	}
+	/** Merged children, walked in `comparePaths` order. */
 	async *list(path, options) {
-		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
-	}
-	async *listDir(dir, recursive) {
+		const dir = normalizePath(path);
 		if ((await this.stats(dir))?.kind !== "directory") return;
-		for (const entry of await this.mergeChildren(dir)) {
-			yield entry;
-			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
-		}
+		yield* listInPathOrder(dir, (d) => this.mergeChildren(d), options);
 	}
 	/** Direct children of `dir`, deduped by name with the topmost layer winning. */
 	async mergeChildren(dir) {

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

@@ -60,13 +60,28 @@ export declare class CompositeFilesApi implements FilesApi {
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
     mkdir(path: string): Promise<void>;
+    /**
+     * Merges, in `comparePaths` order: a synthetic directory entry for each
+     * mount inside `path`; the owning backend's listing with those mounts'
+     * subtrees removed; and, when recursive, each inner mount's own listing
+     * with its nested mounts removed. Each backend's listing is already ordered
+     * and remapping a subtree's prefix keeps that order, so a k-way merge is
+     * enough. `after` is translated into each backend's namespace, and a mount
+     * whose whole subtree lies at or before it is not listed.
+     */
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    /**
+     * One backend's listing of `backendDir`, with paths moved to `compositeDir`
+     * and entries at or under any of `excluded` dropped.
+     */
+    private remappedList;
+    /** The mount that owns `normalized` — the longest matching prefix, else the root. */
+    private ownerOf;
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
     remove(path: string): Promise<boolean>;
     move(source: string, target: string): Promise<boolean>;
     copy(source: string, target: string): Promise<boolean>;
-    private stripBasePath;
     private crossCopy;
     private remapPath;
     private isUnderChildMount;

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

@@ -1 +1 @@
-{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;IACH,YAAY,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAE5C;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CASxD;IAID,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;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,CA4CxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,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,CAW3D;IAID,OAAO,CAAC,aAAa;YAOP,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}
+{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;IACH,YAAY,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAE5C;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CASxD;IAID,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED;;;;;;;;OAQG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAoDxE;IAED;;;OAGG;YACY,YAAY;IAiB3B,qFAAqF;IACrF,OAAO,CAAC,OAAO;IAaT,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,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,CAW3D;YAIa,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}

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

@@ -1 +1 @@
-{"version":3,"file":"cow-files-api.d.ts","sourceRoot":"","sources":["../src/cow-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AAGnC,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,CAEnF"}
+{"version":3,"file":"cow-files-api.d.ts","sourceRoot":"","sources":["../src/cow-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AASnC,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,CAEnF"}

package/dist/esm/index.js

@@ -1,5 +1,126 @@
 //#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);
+	}
+}
+/**
+* Merge streams that are each already in path order into one. When several
+* streams yield the same path, the entry from the earliest stream wins and
+* the others are dropped. At most one entry per stream is pulled ahead, and
+* every stream is closed when the consumer stops.
+*/
+async function* mergeInPathOrder(streams) {
+	const iterators = streams.map((stream) => stream[Symbol.asyncIterator]());
+	const heads = [];
+	const done = [];
+	const pull = async (i) => {
+		const next = await iterators[i].next();
+		done[i] = next.done === true;
+		heads[i] = next.done ? void 0 : next.value;
+	};
+	try {
+		await Promise.all(iterators.map((_, i) => pull(i)));
+		for (;;) {
+			let min = -1;
+			for (let i = 0; i < heads.length; i++) {
+				const head = heads[i];
+				if (!head) continue;
+				const current = min === -1 ? void 0 : heads[min];
+				if (!current || comparePaths(head.path, current.path) < 0) min = i;
+			}
+			if (min === -1) return;
+			const entry = heads[min];
+			for (let i = min + 1; i < heads.length; i++) while (heads[i] && heads[i]?.path === entry.path) await pull(i);
+			heads[min] = void 0;
+			yield entry;
+			await pull(min);
+		}
+	} finally {
+		await Promise.all(iterators.map(async (iterator, i) => {
+			if (!done[i]) await iterator.return?.();
+		}));
+	}
+}
+/** 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 "/".
 */
@@ -161,56 +282,60 @@ var CompositeFilesApi = class {
 		const { api, resolvedPath } = this.resolve(path);
 		return api.mkdir(resolvedPath);
 	}
+	/**
+	* Merges, in `comparePaths` order: a synthetic directory entry for each
+	* mount inside `path`; the owning backend's listing with those mounts'
+	* subtrees removed; and, when recursive, each inner mount's own listing
+	* with its nested mounts removed. Each backend's listing is already ordered
+	* and remapping a subtree's prefix keeps that order, so a k-way merge is
+	* enough. `after` is translated into each backend's namespace, and a mount
+	* whose whole subtree lies at or before it is not listed.
+	*/
 	async *list(path, options) {
 		const normalized = normalizePath(path);
-		const { api, resolvedPath } = this.resolve(path);
-		const childMounts = this.childMountPrefixes(normalized);
-		const yieldedNames = /* @__PURE__ */ new Set();
-		if (options?.recursive) {
-			for await (const entry of api.list(resolvedPath, options)) {
-				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
-				if (this.isUnderChildMount(compositePath, childMounts)) continue;
-				yieldedNames.add(entry.name);
-				yield {
-					...entry,
-					path: compositePath
-				};
-			}
-			for (const mountPrefix of childMounts) {
-				const mount = this.mounts.find((m) => m.prefix === mountPrefix);
-				if (!mount) continue;
-				yield {
-					name: mountPrefix.split("/").pop() ?? "",
-					path: mountPrefix,
-					kind: "directory"
-				};
-				for await (const entry of mount.api.list(mount.basePath, { recursive: true })) {
-					const localPath = this.stripBasePath(entry.path, mount.basePath);
-					yield {
-						...entry,
-						path: `${mountPrefix}${localPath === "/" ? "" : localPath}`
-					};
-				}
-			}
-		} else {
-			for await (const entry of api.list(resolvedPath)) {
-				const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
-				yieldedNames.add(entry.name);
-				yield {
-					...entry,
-					path: compositePath
-				};
-			}
-			for (const mountPrefix of childMounts) {
-				const mountName = mountPrefix.split("/").pop() ?? "";
-				if (!yieldedNames.has(mountName)) yield {
-					name: mountName,
-					path: mountPrefix,
-					kind: "directory"
-				};
-			}
+		const recursive = options?.recursive ?? false;
+		const after = options?.after;
+		const owner = this.ownerOf(normalized);
+		const { resolvedPath } = this.resolve(normalized);
+		const inner = this.mounts.filter((m) => m.prefix !== "/" && isStrictlyInside(m.prefix, normalized));
+		const listed = recursive ? inner : this.childMountPrefixes(normalized).map((prefix) => inner.find((m) => m.prefix === prefix));
+		const streams = [];
+		streams.push(fromArray(listed.map((m) => ({
+			kind: "directory",
+			name: m.prefix.slice(m.prefix.lastIndexOf("/") + 1),
+			path: m.prefix
+		})).sort((x, y) => comparePaths(x.path, y.path))));
+		streams.push(this.remappedList(owner.api, resolvedPath, normalized, recursive, after, inner.map((m) => m.prefix)));
+		if (recursive) for (const m of inner) {
+			const nested = inner.filter((n) => isStrictlyInside(n.prefix, m.prefix)).map((n) => n.prefix);
+			streams.push(this.remappedList(m.api, m.basePath, m.prefix, true, after, nested));
+		}
+		for await (const entry of mergeInPathOrder(streams)) if (after === void 0 || comparePaths(entry.path, after) > 0) yield entry;
+	}
+	/**
+	* One backend's listing of `backendDir`, with paths moved to `compositeDir`
+	* and entries at or under any of `excluded` dropped.
+	*/
+	async *remappedList(api, backendDir, compositeDir, recursive, after, excluded) {
+		const translated = translateAfter(after, compositeDir, backendDir);
+		if (translated === SKIP) return;
+		for await (const entry of api.list(backendDir, {
+			recursive,
+			after: translated
+		})) {
+			const compositePath = this.remapPath(compositeDir, backendDir, entry.path);
+			if (this.isUnderChildMount(compositePath, excluded)) continue;
+			yield {
+				...entry,
+				path: compositePath
+			};
 		}
 	}
+	/** The mount that owns `normalized` — the longest matching prefix, else the root. */
+	ownerOf(normalized) {
+		for (const mount of this.mounts) if (mount.prefix === "/" || normalized === mount.prefix || normalized.startsWith(`${mount.prefix}/`)) return mount;
+		return this.mounts[this.mounts.length - 1];
+	}
 	async stats(path) {
 		const normalized = normalizePath(path);
 		if (this.isMountPoint(normalized)) return { kind: "directory" };
@@ -243,12 +368,6 @@ var CompositeFilesApi = class {
 		if (src.api === tgt.api) return src.api.copy(src.resolvedPath, tgt.resolvedPath);
 		return this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
 	}
-	stripBasePath(path, basePath) {
-		if (basePath === "/") return path;
-		if (path === basePath) return "/";
-		if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
-		return path;
-	}
 	async crossCopy(srcApi, srcPath, tgtApi, tgtPath) {
 		const srcStats = await srcApi.stats(srcPath);
 		if (!srcStats) return false;
@@ -275,6 +394,28 @@ var CompositeFilesApi = class {
 		return false;
 	}
 };
+const SKIP = Symbol("skip");
+/**
+* `after`, given in the `from` subtree's namespace, in the `to` subtree's
+* namespace — or {@link SKIP} when the whole `from` subtree lies at or before
+* it. Raw prefix replacement, never normalisation: normalising `"/a/"` to
+* `"/a"` would change which entries sort after it. Under-pruning is harmless
+* (the caller filters again); over-pruning is what this must never do.
+*/
+function translateAfter(after, from, to) {
+	if (after === void 0) return void 0;
+	const fromPrefix = from === "/" ? "" : from;
+	const toPrefix = to === "/" ? "" : to;
+	if (after.startsWith(`${fromPrefix}/`)) return `${toPrefix}${after.slice(fromPrefix.length)}`;
+	if (comparePaths(after, `${fromPrefix}/`) < 0) return void 0;
+	return SKIP;
+}
+function isStrictlyInside(path, ancestor) {
+	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
+}
+async function* fromArray(items) {
+	yield* items;
+}
 //#endregion
 //#region src/cow-files-api.ts
 /**
@@ -367,15 +508,11 @@ var CowFilesApi = class {
 	async exists(path) {
 		return await this.resolveLayer(path) !== "absent";
 	}
+	/** Merged children, walked in `comparePaths` order. */
 	async *list(path, options) {
-		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
-	}
-	async *listDir(dir, recursive) {
+		const dir = normalizePath(path);
 		if ((await this.stats(dir))?.kind !== "directory") return;
-		for (const entry of await this.mergeChildren(dir)) {
-			yield entry;
-			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
-		}
+		yield* listInPathOrder(dir, (d) => this.mergeChildren(d), options);
 	}
 	/** Direct children of `dir`: writable entries win, base entries fill in. */
 	async mergeChildren(dir) {
@@ -879,15 +1016,11 @@ var OverlayFilesApi = class {
 		for (const layer of this.layers) if (await layer.exists(path)) return true;
 		return false;
 	}
+	/** Merged children, walked in `comparePaths` order. */
 	async *list(path, options) {
-		yield* this.listDir(normalizePath(path), options?.recursive ?? false);
-	}
-	async *listDir(dir, recursive) {
+		const dir = normalizePath(path);
 		if ((await this.stats(dir))?.kind !== "directory") return;
-		for (const entry of await this.mergeChildren(dir)) {
-			yield entry;
-			if (recursive && entry.kind === "directory") yield* this.listDir(entry.path, true);
-		}
+		yield* listInPathOrder(dir, (d) => this.mergeChildren(d), options);
 	}
 	/** Direct children of `dir`, deduped by name with the topmost layer winning. */
 	async mergeChildren(dir) {

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

@@ -1 +1 @@
-{"version":3,"file":"overlay-files-api.d.ts","sourceRoot":"","sources":["../src/overlay-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AA+FnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAErE"}
+{"version":3,"file":"overlay-files-api.d.ts","sourceRoot":"","sources":["../src/overlay-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AAuFnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAErE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-composite",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "type": "module",
   "description": "Composite FilesApi with mount points and access guards",
@@ -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,8 +37,8 @@
     "rolldown": "^1.2.4",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@statewalker/webrun-files-mem": "0.9.0",
-    "@statewalker/webrun-files-tests": "2.0.0"
+    "@statewalker/webrun-files-mem": "0.10.0",
+    "@statewalker/webrun-files-tests": "3.0.0"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/composite-files-api.ts

@@ -5,7 +5,7 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
-import { joinPath, normalizePath } from "@statewalker/webrun-files";
+import { comparePaths, joinPath, mergeInPathOrder, normalizePath } from "@statewalker/webrun-files";
 
 interface MountEntry {
   prefix: string;
@@ -141,50 +141,102 @@ export class CompositeFilesApi implements FilesApi {
     return api.mkdir(resolvedPath);
   }
 
+  /**
+   * Merges, in `comparePaths` order: a synthetic directory entry for each
+   * mount inside `path`; the owning backend's listing with those mounts'
+   * subtrees removed; and, when recursive, each inner mount's own listing
+   * with its nested mounts removed. Each backend's listing is already ordered
+   * and remapping a subtree's prefix keeps that order, so a k-way merge is
+   * enough. `after` is translated into each backend's namespace, and a mount
+   * whose whole subtree lies at or before it is not listed.
+   */
   async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
     const normalized = normalizePath(path);
-    const { api, resolvedPath } = this.resolve(path);
+    const recursive = options?.recursive ?? false;
+    const after = options?.after;
+    const owner = this.ownerOf(normalized);
+    const { resolvedPath } = this.resolve(normalized);
 
-    const childMounts = this.childMountPrefixes(normalized);
-    const yieldedNames = new Set<string>();
-
-    if (options?.recursive) {
-      // Yield entries from the primary mount
-      for await (const entry of api.list(resolvedPath, options)) {
-        // Remap path back to composite namespace
-        const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
-        // Skip if this path falls under a child mount
-        if (this.isUnderChildMount(compositePath, childMounts)) continue;
-        yieldedNames.add(entry.name);
-        yield { ...entry, path: compositePath };
-      }
-      // Recursively yield from child mounts
-      for (const mountPrefix of childMounts) {
-        const mount = this.mounts.find((m) => m.prefix === mountPrefix);
-        if (!mount) continue;
-        const mountName = mountPrefix.split("/").pop() ?? "";
-        // Yield the mount directory entry itself
-        yield { name: mountName, path: mountPrefix, kind: "directory" };
-        for await (const entry of mount.api.list(mount.basePath, { recursive: true })) {
-          const localPath = this.stripBasePath(entry.path, mount.basePath);
-          yield { ...entry, path: `${mountPrefix}${localPath === "/" ? "" : localPath}` };
-        }
-      }
-    } else {
-      // Non-recursive: yield direct children from the primary mount
-      for await (const entry of api.list(resolvedPath)) {
-        const compositePath = this.remapPath(normalized, resolvedPath, entry.path);
-        yieldedNames.add(entry.name);
-        yield { ...entry, path: compositePath };
+    const inner = this.mounts.filter(
+      (m) => m.prefix !== "/" && isStrictlyInside(m.prefix, normalized),
+    );
+    const listed = recursive
+      ? inner
+      : this.childMountPrefixes(normalized).map(
+          (prefix) => inner.find((m) => m.prefix === prefix) as MountEntry,
+        );
+
+    const streams: AsyncIterable<FileInfo>[] = [];
+    // Synthetic mount points come first, so they win over a same-named backend
+    // entry. Mounts are kept longest-prefix first, so this stream is sorted.
+    streams.push(
+      fromArray(
+        listed
+          .map((m) => ({
+            kind: "directory" as const,
+            name: m.prefix.slice(m.prefix.lastIndexOf("/") + 1),
+            path: m.prefix,
+          }))
+          .sort((x, y) => comparePaths(x.path, y.path)),
+      ),
+    );
+    streams.push(
+      this.remappedList(
+        owner.api,
+        resolvedPath,
+        normalized,
+        recursive,
+        after,
+        inner.map((m) => m.prefix),
+      ),
+    );
+    if (recursive) {
+      for (const m of inner) {
+        const nested = inner
+          .filter((n) => isStrictlyInside(n.prefix, m.prefix))
+          .map((n) => n.prefix);
+        streams.push(this.remappedList(m.api, m.basePath, m.prefix, true, after, nested));
       }
-      // Add synthetic directory entries for child mounts not already present
-      for (const mountPrefix of childMounts) {
-        const mountName = mountPrefix.split("/").pop() ?? "";
-        if (!yieldedNames.has(mountName)) {
-          yield { name: mountName, path: mountPrefix, kind: "directory" };
-        }
+    }
+
+    for await (const entry of mergeInPathOrder(streams)) {
+      if (after === undefined || comparePaths(entry.path, after) > 0) yield entry;
+    }
+  }
+
+  /**
+   * One backend's listing of `backendDir`, with paths moved to `compositeDir`
+   * and entries at or under any of `excluded` dropped.
+   */
+  private async *remappedList(
+    api: FilesApi,
+    backendDir: string,
+    compositeDir: string,
+    recursive: boolean,
+    after: string | undefined,
+    excluded: string[],
+  ): AsyncIterable<FileInfo> {
+    const translated = translateAfter(after, compositeDir, backendDir);
+    if (translated === SKIP) return;
+    for await (const entry of api.list(backendDir, { recursive, after: translated })) {
+      const compositePath = this.remapPath(compositeDir, backendDir, entry.path);
+      if (this.isUnderChildMount(compositePath, excluded)) continue;
+      yield { ...entry, path: compositePath };
+    }
+  }
+
+  /** The mount that owns `normalized` — the longest matching prefix, else the root. */
+  private ownerOf(normalized: string): MountEntry {
+    for (const mount of this.mounts) {
+      if (
+        mount.prefix === "/" ||
+        normalized === mount.prefix ||
+        normalized.startsWith(`${mount.prefix}/`)
+      ) {
+        return mount;
       }
     }
+    return this.mounts[this.mounts.length - 1];
   }
 
   async stats(path: string): Promise<FileStats | undefined> {
@@ -246,13 +298,6 @@ export class CompositeFilesApi implements FilesApi {
 
   // --- Helpers ---
 
-  private stripBasePath(path: string, basePath: string): string {
-    if (basePath === "/") return path;
-    if (path === basePath) return "/";
-    if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
-    return path;
-  }
-
   private async crossCopy(
     srcApi: FilesApi,
     srcPath: string,
@@ -305,3 +350,34 @@ export class CompositeFilesApi implements FilesApi {
     return false;
   }
 }
+
+const SKIP = Symbol("skip");
+
+/**
+ * `after`, given in the `from` subtree's namespace, in the `to` subtree's
+ * namespace — or {@link SKIP} when the whole `from` subtree lies at or before
+ * it. Raw prefix replacement, never normalisation: normalising `"/a/"` to
+ * `"/a"` would change which entries sort after it. Under-pruning is harmless
+ * (the caller filters again); over-pruning is what this must never do.
+ */
+function translateAfter(
+  after: string | undefined,
+  from: string,
+  to: string,
+): string | undefined | typeof SKIP {
+  if (after === undefined) return undefined;
+  const fromPrefix = from === "/" ? "" : from;
+  const toPrefix = to === "/" ? "" : to;
+  if (after.startsWith(`${fromPrefix}/`)) return `${toPrefix}${after.slice(fromPrefix.length)}`;
+  // Every descendant of `from` lies between `from + "/"` and `from + "0"`.
+  if (comparePaths(after, `${fromPrefix}/`) < 0) return undefined;
+  return SKIP;
+}
+
+function isStrictlyInside(path: string, ancestor: string): boolean {
+  return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
+}
+
+async function* fromArray<T>(items: T[]): AsyncIterable<T> {
+  yield* items;
+}

package/src/cow-files-api.ts

@@ -5,7 +5,13 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
-import { basename, dirname, joinPath, normalizePath } from "@statewalker/webrun-files";
+import {
+  basename,
+  dirname,
+  joinPath,
+  listInPathOrder,
+  normalizePath,
+} from "@statewalker/webrun-files";
 
 /** Options for {@link cow}. */
 export interface CowOptions {
@@ -142,19 +148,11 @@ class CowFilesApi implements FilesApi {
     return (await this.resolveLayer(path)) !== "absent";
   }
 
+  /** Merged children, walked in `comparePaths` order. */
   async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
-    yield* this.listDir(normalizePath(path), options?.recursive ?? false);
-  }
-
-  private async *listDir(dir: string, recursive: boolean): AsyncIterable<FileInfo> {
-    const stats = await this.stats(dir);
-    if (stats?.kind !== "directory") return;
-    for (const entry of await this.mergeChildren(dir)) {
-      yield entry;
-      if (recursive && entry.kind === "directory") {
-        yield* this.listDir(entry.path, true);
-      }
-    }
+    const dir = normalizePath(path);
+    if ((await this.stats(dir))?.kind !== "directory") return;
+    yield* listInPathOrder(dir, (d) => this.mergeChildren(d), options);
   }
 
   /** Direct children of `dir`: writable entries win, base entries fill in. */

package/src/overlay-files-api.ts

@@ -5,7 +5,7 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
-import { normalizePath } from "@statewalker/webrun-files";
+import { listInPathOrder, normalizePath } from "@statewalker/webrun-files";
 
 /**
  * Read-only union of several `FilesApi` layers. A path is resolved
@@ -51,19 +51,11 @@ class OverlayFilesApi implements FilesApi {
     return false;
   }
 
+  /** Merged children, walked in `comparePaths` order. */
   async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
-    yield* this.listDir(normalizePath(path), options?.recursive ?? false);
-  }
-
-  private async *listDir(dir: string, recursive: boolean): AsyncIterable<FileInfo> {
-    const stats = await this.stats(dir);
-    if (stats?.kind !== "directory") return;
-    for (const entry of await this.mergeChildren(dir)) {
-      yield entry;
-      if (recursive && entry.kind === "directory") {
-        yield* this.listDir(entry.path, true);
-      }
-    }
+    const dir = normalizePath(path);
+    if ((await this.stats(dir))?.kind !== "directory") return;
+    yield* listInPathOrder(dir, (d) => this.mergeChildren(d), options);
   }
 
   /** Direct children of `dir`, deduped by name with the topmost layer winning. */