@statewalker/webrun-files 0.7.0 → 0.9.0

package/README.md

@@ -13,6 +13,7 @@ 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-composite` - Mount multiple backends into a unified filesystem
 
 ## The FilesApi Interface
 
@@ -110,7 +111,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 +130,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
@@ -165,15 +188,29 @@ await files.remove('/old-stuff'); // Recursively deletes directories
 
 ```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 }
 } 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` checks this at runtime, and
+`createFilesApiTests` runs it for you.
+
 ## 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,6 @@ 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/path-utils.ts
 /**
@@ -141,7 +140,6 @@ function extname(path) {
 	if (dotIndex <= 0) return "";
 	return name.substring(dotIndex);
 }
-
 //#endregion
 exports.basename = basename;
 exports.dirname = dirname;
@@ -154,4 +152,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,6 @@ 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/path-utils.ts
 /**
@@ -140,6 +139,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, dirname, extname, joinPath, normalizePath, readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText };

package/dist/index.d.ts

@@ -14,5 +14,5 @@
  */
 export { readAt, readFile, readRange, readText, tryReadFile, tryReadText, writeText, } from "./file-utils.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;;;;;;;;;;;;;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"}

package/dist/types.d.ts

@@ -29,25 +29,68 @@ export interface ListOptions {
     recursive?: boolean;
 }
 /**
- * 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.
  *

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "FilesApi interface and utilities for cross-platform filesystem abstraction",
@@ -29,10 +29,10 @@
     "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"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/index.ts

@@ -33,6 +33,11 @@ export {
 } from "./path-utils.js";
 // Core types
 export type {
+  DirectoryEntryInfo,
+  DirectoryEntryStats,
+  FileEntryInfo,
+  FileEntryLocation,
+  FileEntryStats,
   FileInfo,
   FileKind,
   FileStats,

package/src/types.ts

@@ -33,27 +33,73 @@ export interface ListOptions {
 }
 
 /**
- * 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 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;
+}
+
+/**
+ * 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 FileStats {
-  kind: FileKind;
-  size?: number;
-  lastModified?: number;
+export interface DirectoryEntryStats {
+  kind: "directory";
 }
 
 /**
- * File or directory information returned by list().
- * Includes name and path for directory traversal.
+ * 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.
  *