@statewalker/webrun-files 0.7.0 → 0.10.0

package/README.md

@@ -13,6 +13,9 @@ 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
 
@@ -110,7 +113,7 @@ await files.write('/large.bin', generateChunks());
 ```typescript
 import { normalizePath, joinPath, dirname, basename, extname } from '@statewalker/webrun-files';
 
-normalizePath('//foo/../bar/./baz/');  // '/bar/baz'
+normalizePath('//foo/./bar//baz/');     // '/foo/bar/baz'
 joinPath('/foo', 'bar', 'baz.txt');    // '/foo/bar/baz.txt'
 dirname('/foo/bar/baz.txt');            // '/foo/bar'
 basename('/foo/bar/baz.txt');           // 'baz.txt'
@@ -129,21 +132,43 @@ if (await files.exists('/config.json')) {
 
 ### Getting Metadata
 
+`FileStats` is a discriminated union on `kind`. A file always reports a `size`
+and a `lastModified`; a directory reports neither, because a directory has no
+size and a modification time for one is unavailable on stores where a directory
+is only a key prefix. Narrow on `kind` and the fields for that kind are then
+known to be present:
+
 ```typescript
 const info = await files.stats('/photo.jpg');
-if (info) {
-  console.log(`Size: ${info.size} bytes`);
+if (info?.kind === 'file') {
+  console.log(`Size: ${info.size} bytes`);          // number, never undefined
   console.log(`Modified: ${new Date(info.lastModified)}`);
-  console.log(`Type: ${info.kind}`); // "file" or "directory"
+} else if (info?.kind === 'directory') {
+  console.log('a directory');                        // nothing else to report
 }
 ```
 
+A zero-byte file is the file variant with `size: 0`, so test the `kind` rather
+than the truthiness of `size`:
+
+```typescript
+// WRONG - reads an empty file as though it had no size
+if (info.size) { /* ... */ }
+
+// RIGHT
+if (info.kind === 'file') { /* info.size may legitimately be 0 */ }
+```
+
 ### Listing Directories
 
+`FileInfo` is the same union plus `name` and `path`, so a listing narrows per
+entry exactly as `stats()` does:
+
 ```typescript
 // List direct children
 for await (const entry of files.list('/documents')) {
-  console.log(`${entry.name} (${entry.kind})`);
+  const size = entry.kind === 'file' ? `${entry.size} bytes` : '';
+  console.log(`${entry.name} (${entry.kind}) ${size}`);
 }
 
 // List recursively
@@ -152,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
@@ -161,19 +213,57 @@ 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
 import type {
-  FilesApi,      // Core interface for backends
-  FileInfo,      // Metadata from list() - includes name, path, kind, size, lastModified
-  FileStats,     // Metadata from stats() - kind, size, lastModified
-  FileKind,      // "file" | "directory"
-  ReadOptions,   // { start?: number, length?: number, signal?: AbortSignal }
-  ListOptions,   // { recursive?: boolean }
+  FilesApi,             // Core interface for backends
+  FileStats,            // Metadata from stats(): FileEntryStats | DirectoryEntryStats
+  FileEntryStats,       // { kind: "file", size: number, lastModified: number }
+  DirectoryEntryStats,  // { kind: "directory" }
+  FileInfo,             // Metadata from list(): FileEntryInfo | DirectoryEntryInfo
+  FileEntryInfo,        // FileEntryStats & { name, path }
+  DirectoryEntryInfo,   // DirectoryEntryStats & { name, path }
+  FileEntryLocation,    // { name: string, path: string }
+  FileKind,             // "file" | "directory"
+  ReadOptions,          // { start?: number, length?: number, signal?: AbortSignal }
+  ListOptions,          // { recursive?: boolean, after?: string }
 } from '@statewalker/webrun-files';
 ```
 
+### Implementing a backend
+
+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` — 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
 
 MIT

package/dist/cjs/index.cjs

@@ -1,4 +1,4 @@
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/file-utils.ts
 /**
 * Collect async iterable chunks into a single Uint8Array.
@@ -10,7 +10,7 @@ async function collectChunks(chunks) {
 		parts.push(chunk);
 		totalLength += chunk.length;
 	}
-	if (parts.length === 0) return new Uint8Array(0);
+	if (parts.length === 0) return /* @__PURE__ */ new Uint8Array(0);
 	if (parts.length === 1) return parts[0];
 	const result = new Uint8Array(totalLength);
 	let offset = 0;
@@ -88,7 +88,129 @@ async function readAt(files, path, buffer, bufferOffset, length, position) {
 async function writeText(files, path, content) {
 	await files.write(path, [new TextEncoder().encode(content)]);
 }
-
+//#endregion
+//#region src/list-order.ts
+/**
+* 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
 /**
@@ -141,12 +263,14 @@ function extname(path) {
 	if (dotIndex <= 0) return "";
 	return name.substring(dotIndex);
 }
-
 //#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;
@@ -154,4 +278,4 @@ exports.readRange = readRange;
 exports.readText = readText;
 exports.tryReadFile = tryReadFile;
 exports.tryReadText = tryReadText;
-exports.writeText = writeText;
+exports.writeText = writeText;

package/dist/esm/index.js

@@ -9,7 +9,7 @@ async function collectChunks(chunks) {
 		parts.push(chunk);
 		totalLength += chunk.length;
 	}
-	if (parts.length === 0) return new Uint8Array(0);
+	if (parts.length === 0) return /* @__PURE__ */ new Uint8Array(0);
 	if (parts.length === 1) return parts[0];
 	const result = new Uint8Array(totalLength);
 	let offset = 0;
@@ -87,7 +87,129 @@ async function readAt(files, path, buffer, bufferOffset, length, position) {
 async function writeText(files, path, content) {
 	await files.write(path, [new TextEncoder().encode(content)]);
 }
-
+//#endregion
+//#region src/list-order.ts
+/**
+* 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
 /**
@@ -140,6 +262,5 @@ function extname(path) {
 	if (dotIndex <= 0) return "";
 	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 { FileInfo, FileKind, FileStats, FilesApi, ListOptions, ReadOptions, } from "./types.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,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,27 +27,79 @@ 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;
 }
 /**
- * File or directory metadata returned by stats().
- * Simplified type without path information.
+ * Metadata of a regular file.
+ *
+ * `size` and `lastModified` are REQUIRED. Every storage that can hold a file
+ * can say how large it is and when it last changed; an implementation that
+ * cannot is claiming less than it must, and the omission must surface as a
+ * failure rather than as an `undefined` a consumer has to defend against.
  */
-export interface FileStats {
-    kind: FileKind;
-    size?: number;
-    lastModified?: number;
+export interface FileEntryStats {
+    kind: "file";
+    /** Length in bytes. A zero-byte file is `0`, never `undefined`. */
+    size: number;
+    /** Modification time as milliseconds since the epoch. */
+    lastModified: number;
 }
 /**
- * File or directory information returned by list().
- * Includes name and path for directory traversal.
+ * Metadata of a directory.
+ *
+ * Deliberately carries nothing else. A directory has no size, and a
+ * modification time is available on some storages (memory, a local
+ * filesystem) and unavailable on others (an object store, where a directory
+ * is a common prefix that exists only as an artefact of key naming). Neither
+ * value may be relied upon, so neither is part of the contract: an
+ * implementation that happens to know one drops it here instead of leaking a
+ * value consumers would have to treat as optional anyway.
  */
-export interface FileInfo {
+export interface DirectoryEntryStats {
+    kind: "directory";
+}
+/**
+ * File or directory metadata returned by `stats()`.
+ *
+ * A DISCRIMINATED UNION on `kind`, not a single shape with optional fields.
+ * The optionality this replaces never expressed what a given implementation
+ * could report — it expressed a property of the entry kind, collapsed into
+ * one type because `kind` was an ordinary field. Narrow on `kind` and the
+ * fields that exist for that kind are then known to be present:
+ *
+ * @example
+ * const stats = await api.stats("/some/path");
+ * if (stats?.kind === "file") {
+ *   console.log(stats.size, stats.lastModified); // both `number`
+ * }
+ */
+export type FileStats = FileEntryStats | DirectoryEntryStats;
+/** Name and path carried by every entry a `list()` yields. */
+export interface FileEntryLocation {
     name: string;
     path: string;
-    kind: FileKind;
-    size?: number;
-    lastModified?: number;
 }
+/** A file yielded by `list()`. */
+export interface FileEntryInfo extends FileEntryStats, FileEntryLocation {
+}
+/** A directory yielded by `list()`. */
+export interface DirectoryEntryInfo extends DirectoryEntryStats, FileEntryLocation {
+}
+/**
+ * File or directory information returned by `list()`.
+ *
+ * The same union as {@link FileStats}, plus `name` and `path`, so a listing
+ * consumer narrows per entry exactly as a `stats()` consumer does.
+ */
+export type FileInfo = FileEntryInfo | DirectoryEntryInfo;
 /**
  * Cross-platform filesystem abstraction interface.
  *
@@ -73,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;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;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.7.0",
+  "version": "0.10.0",
   "private": false,
   "type": "module",
   "description": "FilesApi interface and utilities for cross-platform filesystem abstraction",
@@ -29,10 +29,11 @@
     "src"
   ],
   "devDependencies": {
-    "@types/node": "^24.10.1",
-    "rimraf": "^6.1.2",
-    "rolldown": "^1.0.0-beta.53",
-    "typescript": "^5.6.0"
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -40,6 +41,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,
@@ -33,6 +38,11 @@ export {
 } from "./path-utils.js";
 // Core types
 export type {
+  DirectoryEntryInfo,
+  DirectoryEntryStats,
+  FileEntryInfo,
+  FileEntryLocation,
+  FileEntryStats,
   FileInfo,
   FileKind,
   FileStats,

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,30 +30,85 @@ 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;
 }
 
 /**
- * File or directory metadata returned by stats().
- * Simplified type without path information.
+ * Metadata of a regular file.
+ *
+ * `size` and `lastModified` are REQUIRED. Every storage that can hold a file
+ * can say how large it is and when it last changed; an implementation that
+ * cannot is claiming less than it must, and the omission must surface as a
+ * failure rather than as an `undefined` a consumer has to defend against.
  */
-export interface FileStats {
-  kind: FileKind;
-  size?: number;
-  lastModified?: number;
+export interface FileEntryStats {
+  kind: "file";
+  /** Length in bytes. A zero-byte file is `0`, never `undefined`. */
+  size: number;
+  /** Modification time as milliseconds since the epoch. */
+  lastModified: number;
 }
 
 /**
- * File or directory information returned by list().
- * Includes name and path for directory traversal.
+ * Metadata of a directory.
+ *
+ * Deliberately carries nothing else. A directory has no size, and a
+ * modification time is available on some storages (memory, a local
+ * filesystem) and unavailable on others (an object store, where a directory
+ * is a common prefix that exists only as an artefact of key naming). Neither
+ * value may be relied upon, so neither is part of the contract: an
+ * implementation that happens to know one drops it here instead of leaking a
+ * value consumers would have to treat as optional anyway.
+ */
+export interface DirectoryEntryStats {
+  kind: "directory";
+}
+
+/**
+ * File or directory metadata returned by `stats()`.
+ *
+ * A DISCRIMINATED UNION on `kind`, not a single shape with optional fields.
+ * The optionality this replaces never expressed what a given implementation
+ * could report — it expressed a property of the entry kind, collapsed into
+ * one type because `kind` was an ordinary field. Narrow on `kind` and the
+ * fields that exist for that kind are then known to be present:
+ *
+ * @example
+ * const stats = await api.stats("/some/path");
+ * if (stats?.kind === "file") {
+ *   console.log(stats.size, stats.lastModified); // both `number`
+ * }
  */
-export interface FileInfo {
+export type FileStats = FileEntryStats | DirectoryEntryStats;
+
+/** Name and path carried by every entry a `list()` yields. */
+export interface FileEntryLocation {
   name: string;
   path: string;
-  kind: FileKind;
-  size?: number;
-  lastModified?: number;
 }
 
+/** A file yielded by `list()`. */
+export interface FileEntryInfo extends FileEntryStats, FileEntryLocation {}
+
+/** A directory yielded by `list()`. */
+export interface DirectoryEntryInfo extends DirectoryEntryStats, FileEntryLocation {}
+
+/**
+ * File or directory information returned by `list()`.
+ *
+ * The same union as {@link FileStats}, plus `name` and `path`, so a listing
+ * consumer narrows per entry exactly as a `stats()` consumer does.
+ */
+export type FileInfo = FileEntryInfo | DirectoryEntryInfo;
+
 /**
  * Cross-platform filesystem abstraction interface.
  *
@@ -82,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>;