@statewalker/webrun-files 0.9.0 → 0.10.1

package/README.md

@@ -13,6 +13,8 @@ For actual filesystem implementations, install one of these packages:
 - `@statewalker/webrun-files-node` - Node.js filesystem
 - `@statewalker/webrun-files-browser` - Browser File System Access API
 - `@statewalker/webrun-files-s3` - AWS S3 / S3-compatible storage
+- `@statewalker/webrun-files-sqlite` - SQLite (node:sqlite, Cloudflare Durable Objects, D1)
+- `@statewalker/webrun-files-http` - Serve and consume a `FilesApi` over HTTP (fetch-based stubs)
 - `@statewalker/webrun-files-composite` - Mount multiple backends into a unified filesystem
 
 ## The FilesApi Interface
@@ -175,6 +177,33 @@ for await (const entry of files.list('/project', { recursive: true })) {
 }
 ```
 
+### Listing order and resuming
+
+Every implementation yields `list()` entries in **strictly increasing path order, compared by
+Unicode code point** — the order of UTF-8 bytes, which is also how SQLite and S3 list — for
+recursive and non-recursive listings alike. `ListOptions.after` resumes after any path, whether or
+not it exists:
+
+```typescript
+// Read a big directory in chunks of 256 without keeping an iterator open.
+let after: string | undefined;
+for (;;) {
+  const chunk: FileInfo[] = [];
+  for await (const entry of files.list('/data', { recursive: true, after })) {
+    chunk.push(entry);
+    if (chunk.length === 256) break;
+  }
+  if (chunk.length === 0) break;
+  await handle(chunk);
+  after = chunk[chunk.length - 1].path;
+}
+```
+
+Two consequences of the order: a directory comes before its descendants, but they are not
+contiguous with it (`/a-x` and `/a.txt` sort between `/a` and `/a/b`, because `-` and `.` sort
+before `/`); and JavaScript's `<` is not this order — it misorders characters above U+FFFF — so
+compare paths with `comparePaths`.
+
 ### File Management
 
 ```typescript
@@ -184,6 +213,22 @@ await files.move('/temp/draft.txt', '/documents/final.txt');
 await files.remove('/old-stuff'); // Recursively deletes directories
 ```
 
+### Listing helpers for backends
+
+```typescript
+import { comparePaths, listInPathOrder, mergeInPathOrder } from '@statewalker/webrun-files';
+
+comparePaths(a, b); // the listing order: negative, zero or positive
+
+// A backend that reads one directory at a time: children(dir) returns its direct
+// entries in any order. Reads a directory only when the listing reaches it, and
+// never one whose whole subtree sorts at or before options.after.
+listInPathOrder(dir, children, { recursive, after });
+
+// Merge listings that are each already ordered; the first stream wins a shared path.
+mergeInPathOrder([streamA, streamB]);
+```
+
 ## Type Reference
 
 ```typescript
@@ -198,7 +243,7 @@ import type {
   FileEntryLocation,    // { name: string, path: string }
   FileKind,             // "file" | "directory"
   ReadOptions,          // { start?: number, length?: number, signal?: AbortSignal }
-  ListOptions,          // { recursive?: boolean }
+  ListOptions,          // { recursive?: boolean, after?: string }
 } from '@statewalker/webrun-files';
 ```
 
@@ -208,8 +253,16 @@ An implementation must return **exactly** one variant: a file with both numbers
 present, a directory with nothing but its `kind`. An implementation that knows a
 directory's modification time drops it rather than offering a value that would
 be present on one backend and missing on the next. The parametrized suite in
-`@statewalker/webrun-files-tests` checks this at runtime, and
-`createFilesApiTests` runs it for you.
+`@statewalker/webrun-files-tests` — a workspace package of this monorepo, not
+published to npm — checks this at runtime: `createFilesApiTests` runs it (as
+`createFileStatsConformanceTests`) for you.
+
+A listing must also follow 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. `createFilesApiTests` checks that too
+(`createListOrderTests`), against a fixture of names chosen to break naive
+orderings. `listInPathOrder` gives both properties to a backend that can read
+one directory at a time.
 
 ## License
 

package/dist/cjs/index.cjs

@@ -89,6 +89,129 @@ async function writeText(files, path, content) {
 	await files.write(path, [new TextEncoder().encode(content)]);
 }
 //#endregion
+//#region 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
+* 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;
+	}
+};
+//#endregion
 //#region src/path-utils.ts
 /**
 * Path manipulation utilities for virtual filesystem paths.
@@ -142,9 +265,12 @@ function extname(path) {
 }
 //#endregion
 exports.basename = basename;
+exports.comparePaths = comparePaths;
 exports.dirname = dirname;
 exports.extname = extname;
 exports.joinPath = joinPath;
+exports.listInPathOrder = listInPathOrder;
+exports.mergeInPathOrder = mergeInPathOrder;
 exports.normalizePath = normalizePath;
 exports.readAt = readAt;
 exports.readFile = readFile;

package/dist/esm/index.js

@@ -88,6 +88,129 @@ async function writeText(files, path, content) {
 	await files.write(path, [new TextEncoder().encode(content)]);
 }
 //#endregion
+//#region 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
+* 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;
+	}
+};
+//#endregion
 //#region src/path-utils.ts
 /**
 * Path manipulation utilities for virtual filesystem paths.
@@ -140,4 +263,4 @@ function extname(path) {
 	return name.substring(dotIndex);
 }
 //#endregion
-export { basename, dirname, extname, joinPath, normalizePath, readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText };
+export { basename, comparePaths, dirname, extname, joinPath, listInPathOrder, mergeInPathOrder, normalizePath, readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText };

package/dist/index.d.ts

@@ -11,8 +11,12 @@
  * - @statewalker/webrun-files-node (Node.js)
  * - @statewalker/webrun-files-browser (browser)
  * - @statewalker/webrun-files-s3 (S3)
+ * - @statewalker/webrun-files-sqlite (SQLite: node:sqlite, Durable Objects, D1)
+ * - @statewalker/webrun-files-http (a FilesApi served and consumed over HTTP)
+ * - @statewalker/webrun-files-composite (mount several backends as one tree)
  */
 export { readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText, } from "./file-utils.js";
+export { comparePaths, listInPathOrder, mergeInPathOrder } from "./list-order.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;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACX,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,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,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/list-order.d.ts

@@ -0,0 +1,28 @@
+import type { FileInfo, ListOptions } from "./types.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.
+ */
+export declare function comparePaths(a: string, b: string): number;
+/**
+ * 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`.
+ */
+export declare function listInPathOrder(dir: string, children: (dir: string) => Promise<Iterable<FileInfo>> | Iterable<FileInfo>, options?: ListOptions): AsyncGenerator<FileInfo>;
+/**
+ * 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.
+ */
+export declare function mergeInPathOrder(streams: AsyncIterable<FileInfo>[]): AsyncGenerator<FileInfo>;
+//# sourceMappingURL=list-order.d.ts.map

package/dist/list-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-order.d.ts","sourceRoot":"","sources":["../src/list-order.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAczD;AAQD;;;;;;;;GAQG;AACH,wBAAuB,eAAe,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,EAC3E,OAAO,GAAE,WAAgB,GACxB,cAAc,CAAC,QAAQ,CAAC,CAY1B;AAED;;;;;GAKG;AACH,wBAAuB,gBAAgB,CACrC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,GACjC,cAAc,CAAC,QAAQ,CAAC,CAoC1B"}

package/dist/types.d.ts

@@ -27,6 +27,15 @@ export interface ReadOptions {
 export interface ListOptions {
     /** If true, lists all descendants recursively. Defaults to false. */
     recursive?: boolean;
+    /**
+     * Yield only entries whose path sorts strictly after this one, in
+     * `comparePaths` order. The path need not exist, and may lie outside
+     * the listed directory: before it, everything is yielded; past it, nothing.
+     *
+     * Resuming with the last path yielded continues a listing exactly where it
+     * stopped, without holding an iterator open between the calls.
+     */
+    after?: string;
 }
 /**
  * Metadata of a regular file.
@@ -116,6 +125,10 @@ export interface FilesApi {
     /**
      * List directory contents.
      * Returns empty iterable for non-existent or non-directory paths.
+     *
+     * Entries are yielded in strictly increasing path order, compared by
+     * Unicode code point (`comparePaths`) — the same for recursive and
+     * non-recursive listings. `options.after` resumes after a given path.
      */
     list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
     /**

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;CACrB;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;;;OAGG;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;;;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "private": false,
   "type": "module",
   "description": "FilesApi interface and utilities for cross-platform filesystem abstraction",
@@ -19,6 +19,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.cjs"
@@ -29,10 +30,11 @@
     "src"
   ],
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.6.4",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
-    "typescript": "^7.0.2"
+    "rolldown": "^1.2.12",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -40,6 +42,7 @@
   },
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
-    "lint": "biome lint src"
+    "lint": "biome lint src",
+    "test": "vitest run"
   }
 }

package/src/index.ts

@@ -11,6 +11,9 @@
  * - @statewalker/webrun-files-node (Node.js)
  * - @statewalker/webrun-files-browser (browser)
  * - @statewalker/webrun-files-s3 (S3)
+ * - @statewalker/webrun-files-sqlite (SQLite: node:sqlite, Durable Objects, D1)
+ * - @statewalker/webrun-files-http (a FilesApi served and consumed over HTTP)
+ * - @statewalker/webrun-files-composite (mount several backends as one tree)
  */
 
 // File utilities
@@ -23,6 +26,8 @@ export {
   tryReadText,
   writeText,
 } from "./file-utils.js";
+// Listing order
+export { comparePaths, listInPathOrder, mergeInPathOrder } from "./list-order.js";
 // Path utilities
 export {
   basename,

package/src/list-order.ts

@@ -0,0 +1,149 @@
+import type { FileInfo, ListOptions } from "./types.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.
+ */
+export function comparePaths(a: string, b: string): number {
+  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 >= 0xd800 && x <= 0xdfff;
+    const ySurrogate = y >= 0xd800 && y <= 0xdfff;
+    // A surrogate stands for a code point above U+FFFF, so it outranks any
+    // other unit; two surrogates compare in code point order as they are.
+    if (xSurrogate !== ySurrogate) 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: string, after: string | undefined): boolean {
+  // Every descendant of `dir` lies between `dir + "/"` and `dir + "0"`.
+  return after === undefined || 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`.
+ */
+export async function* listInPathOrder(
+  dir: string,
+  children: (dir: string) => Promise<Iterable<FileInfo>> | Iterable<FileInfo>,
+  options: ListOptions = {},
+): AsyncGenerator<FileInfo> {
+  const { recursive = false, after } = options;
+  const heap = new PathHeap<FileInfo>((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 === undefined || 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.
+ */
+export async function* mergeInPathOrder(
+  streams: AsyncIterable<FileInfo>[],
+): AsyncGenerator<FileInfo> {
+  const iterators = streams.map((stream) => stream[Symbol.asyncIterator]());
+  const heads: (FileInfo | undefined)[] = [];
+  const done: boolean[] = [];
+  const pull = async (i: number) => {
+    const next = await iterators[i].next();
+    done[i] = next.done === true;
+    heads[i] = next.done ? undefined : 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 ? undefined : heads[min];
+        if (!current || comparePaths(head.path, current.path) < 0) min = i;
+      }
+      if (min === -1) return;
+      const entry = heads[min] as FileInfo;
+      // Drop the same path from later streams before yielding.
+      for (let i = min + 1; i < heads.length; i++) {
+        while (heads[i] && heads[i]?.path === entry.path) await pull(i);
+      }
+      heads[min] = undefined;
+      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}. */
+class PathHeap<T> {
+  readonly #items: T[] = [];
+  readonly #key: (item: T) => string;
+
+  constructor(key: (item: T) => string) {
+    this.#key = key;
+  }
+
+  push(item: T): void {
+    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(): T | undefined {
+    const items = this.#items;
+    const top = items[0];
+    const last = items.pop();
+    if (items.length > 0 && last !== undefined) {
+      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: T, b: T): boolean {
+    return comparePaths(this.#key(a), this.#key(b)) < 0;
+  }
+}

package/src/types.ts

@@ -30,6 +30,15 @@ export interface ReadOptions {
 export interface ListOptions {
   /** If true, lists all descendants recursively. Defaults to false. */
   recursive?: boolean;
+  /**
+   * Yield only entries whose path sorts strictly after this one, in
+   * `comparePaths` order. The path need not exist, and may lie outside
+   * the listed directory: before it, everything is yielded; past it, nothing.
+   *
+   * Resuming with the last path yielded continues a listing exactly where it
+   * stopped, without holding an iterator open between the calls.
+   */
+  after?: string;
 }
 
 /**
@@ -128,6 +137,10 @@ export interface FilesApi {
   /**
    * List directory contents.
    * Returns empty iterable for non-existent or non-directory paths.
+   *
+   * Entries are yielded in strictly increasing path order, compared by
+   * Unicode code point (`comparePaths`) — the same for recursive and
+   * non-recursive listings. `options.after` resumes after a given path.
    */
   list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;