@statewalker/webrun-files 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,199 @@
+# @statewalker/webrun-files
+
+The core filesystem API for cross-platform file operations. This package provides a clean, minimal interface for reading, writing, and managing files that works consistently whether you're running in Node.js or need an in-memory implementation for browsers and testing.
+
+## Installation
+
+```bash
+npm install @statewalker/webrun-files
+# or
+pnpm add @statewalker/webrun-files
+```
+
+## Quick Start
+
+The fastest way to get going is to create a `FilesApi` instance with one of the built-in backends. Here's an example using the in-memory implementation:
+
+```typescript
+import { FilesApi, MemFilesApi } from '@statewalker/webrun-files';
+
+const files = new FilesApi(new MemFilesApi());
+
+// Write a file
+await files.write('/documents/notes.txt', [
+  new TextEncoder().encode('Remember to water the plants')
+]);
+
+// Read it back
+const content = await files.readFile('/documents/notes.txt');
+console.log(new TextDecoder().decode(content));
+```
+
+For Node.js applications that need to work with the actual filesystem, switch to `NodeFilesApi`:
+
+```typescript
+import { FilesApi, NodeFilesApi } from '@statewalker/webrun-files';
+
+const files = new FilesApi(new NodeFilesApi('/path/to/root'));
+```
+
+The `NodeFilesApi` constructor accepts an optional root directory path. When provided, all file operations will be relative to this directory, effectively sandboxing the API.
+
+## Working with Files
+
+The `FilesApi` class provides everything you need for common file operations. Writing content is straightforward—just pass an array of `Uint8Array` chunks:
+
+```typescript
+const text = new TextEncoder().encode('Hello, World!');
+await files.write('/greeting.txt', [text]);
+```
+
+Reading comes in two flavors. Use `readFile` when you want the entire contents as a single buffer:
+
+```typescript
+const content = await files.readFile('/greeting.txt');
+```
+
+For large files, `read` returns an async generator that yields chunks as they come in, keeping memory usage under control:
+
+```typescript
+for await (const chunk of files.read('/large-file.bin')) {
+  process.stdout.write(chunk);
+}
+```
+
+You can also read specific portions of a file by specifying start and end positions:
+
+```typescript
+for await (const chunk of files.read('/data.bin', { start: 100, end: 200 })) {
+  // Only bytes 100-199
+}
+```
+
+## Managing Files and Directories
+
+Checking whether a file or directory exists is simple:
+
+```typescript
+if (await files.exists('/config.json')) {
+  // Load configuration
+}
+```
+
+To get detailed information about a file, use `stats`:
+
+```typescript
+const info = await files.stats('/photo.jpg');
+if (info) {
+  console.log(`Size: ${info.size} bytes`);
+  console.log(`Modified: ${new Date(info.lastModified)}`);
+  console.log(`Type: ${info.kind}`); // "file" or "directory"
+}
+```
+
+Listing directory contents returns an async generator of file info objects:
+
+```typescript
+for await (const entry of files.list('/documents')) {
+  console.log(`${entry.name} (${entry.kind})`);
+}
+```
+
+Pass `{ recursive: true }` to traverse subdirectories:
+
+```typescript
+for await (const entry of files.list('/project', { recursive: true })) {
+  console.log(entry.path);
+}
+```
+
+Creating directories, copying, moving, and deleting all work as you'd expect:
+
+```typescript
+await files.mkdir('/archive/2024');
+await files.copy('/report.pdf', '/archive/2024/report.pdf');
+await files.move('/temp/draft.txt', '/documents/final.txt');
+await files.remove('/old-stuff'); // Recursively deletes directories
+```
+
+## Low-Level File Handle Operations
+
+When you need fine-grained control over file operations, work directly with file handles. Opening a file gives you a handle that supports reading, writing, and appending at specific positions:
+
+```typescript
+const handle = await files.open('/data.bin');
+
+// Get the current file size
+console.log(`File is ${handle.size} bytes`);
+
+// Read a specific range
+for await (const chunk of handle.createReadStream({ start: 0, end: 100 })) {
+  // First 100 bytes
+}
+
+// Write at a specific position
+await handle.createWriteStream([newData], { start: 50 });
+
+// Append to the end
+await handle.appendFile([moreData]);
+
+// Always close when done
+await handle.close();
+```
+
+## Building Your Own Backend
+
+The `IFilesApi` interface defines the contract that all backends must implement. At minimum, you need four methods:
+
+```typescript
+interface IFilesApi {
+  list(file: FileRef, options?: ListOptions): AsyncGenerator<FileInfo>;
+  stats(file: FileRef): Promise<FileInfo | undefined>;
+  remove(file: FileRef): Promise<boolean>;
+  open(file: FileRef): Promise<FileHandle>;
+}
+```
+
+The `FilesApi` wrapper class builds convenience methods like `read`, `write`, `copy`, and `move` on top of these primitives. Backends can optionally implement native versions of `move`, `copy`, and `mkdir` for better performance.
+
+Take a look at `MemFilesApi` or `NodeFilesApi` in the source code for reference implementations.
+
+## Type Reference
+
+The package exports all the TypeScript types you'll need:
+
+```typescript
+import type {
+  IFilesApi,        // Core interface for backends
+  FilesApi,         // Wrapper class with convenience methods
+  FileInfo,         // Metadata returned by stats() and list()
+  FileHandle,       // Low-level file operations
+  FileRef,          // string | { path: string }
+  FileKind,         // "file" | "directory"
+  BinaryStream,     // AsyncIterable<Uint8Array> | Iterable<Uint8Array>
+  ListOptions,      // { recursive?: boolean }
+  CopyOptions,      // { recursive?: boolean }
+  ReadStreamOptions,  // { start?: number, end?: number, signal?: AbortSignal }
+  WriteStreamOptions, // { start?: number, signal?: AbortSignal }
+} from '@statewalker/webrun-files';
+```
+
+## Utility Functions
+
+The package includes helpful utilities for working with paths and streams:
+
+```typescript
+import {
+  normalizePath,    // Clean up path strings
+  resolveFileRef,   // Convert FileRef to normalized path
+  joinPath,         // Join path segments
+  dirname,          // Get directory portion of path
+  basename,         // Get filename portion
+  extname,          // Get file extension
+  collectGenerator, // Collect async iterable into array
+} from '@statewalker/webrun-files';
+```
+
+## License
+
+MIT

package/dist/cjs/index.cjs

@@ -25,6 +25,21 @@ function toBinaryAsyncIterable(data) {
 	return toAsyncIterable(data);
 }
 
+//#endregion
+//#region src/utils/file-info-utils.ts
+/**
+* Check if FileInfo represents a directory
+*/
+function isDirectory(info) {
+	return info?.kind === "directory";
+}
+/**
+* Check if FileInfo represents a file
+*/
+function isFile(info) {
+	return info?.kind === "file";
+}
+
 //#endregion
 //#region src/utils/normalize-path.ts
 /**
@@ -94,7 +109,7 @@ function extname(path) {
 
 //#endregion
 //#region src/files-api.ts
-const IGNORE_FILE = ".gitkeep";
+const IGNORE_FILE = ".ignore";
 var FilesApi = class {
 	constructor(fs) {
 		this.fs = fs;
@@ -283,6 +298,16 @@ var MemFileHandle = class {
 		file.lastModified = Date.now();
 		return bytesWritten;
 	}
+	async read(buffer, offset, length, position) {
+		const entry = this.store.get(this.path);
+		if (!entry || entry.kind !== "file") return 0;
+		const content = entry.content;
+		const available = content.length - position;
+		if (available <= 0) return 0;
+		const bytesToRead = Math.min(length, available, buffer.length - offset);
+		buffer.set(content.subarray(position, position + bytesToRead), offset);
+		return bytesToRead;
+	}
 };
 var MemFilesApi = class {
 	store = /* @__PURE__ */ new Map();
@@ -447,6 +472,11 @@ var NodeFileHandleWrapper = class {
 	async chown(uid, gid) {
 		await this.handle.chown(uid, gid);
 	}
+	async read(buffer, offset, length, position) {
+		const actualLength = Math.min(length, buffer.length - offset);
+		if (actualLength <= 0) return 0;
+		return (await this.handle.read(buffer, offset, actualLength, position)).bytesRead;
+	}
 };
 var NodeFilesApi = class {
 	fs;
@@ -502,7 +532,10 @@ var NodeFilesApi = class {
 	async remove(file) {
 		const fullPath = this.resolvePath(file);
 		try {
-			if ((await this.fs.stat(fullPath)).isDirectory()) await this.fs.rm(fullPath, { recursive: true });
+			if ((await this.fs.stat(fullPath)).isDirectory()) await this.fs.rm(fullPath, {
+				recursive: true,
+				force: true
+			});
 			else await this.fs.unlink(fullPath);
 			return true;
 		} catch {
@@ -556,6 +589,8 @@ exports.basename = basename;
 exports.collectGenerator = collectGenerator;
 exports.dirname = dirname;
 exports.extname = extname;
+exports.isDirectory = isDirectory;
+exports.isFile = isFile;
 exports.joinPath = joinPath;
 exports.normalizePath = normalizePath;
 exports.resolveFileRef = resolveFileRef;

package/dist/esm/index.js

@@ -24,6 +24,21 @@ function toBinaryAsyncIterable(data) {
 	return toAsyncIterable(data);
 }
 
+//#endregion
+//#region src/utils/file-info-utils.ts
+/**
+* Check if FileInfo represents a directory
+*/
+function isDirectory(info) {
+	return info?.kind === "directory";
+}
+/**
+* Check if FileInfo represents a file
+*/
+function isFile(info) {
+	return info?.kind === "file";
+}
+
 //#endregion
 //#region src/utils/normalize-path.ts
 /**
@@ -93,7 +108,7 @@ function extname(path) {
 
 //#endregion
 //#region src/files-api.ts
-const IGNORE_FILE = ".gitkeep";
+const IGNORE_FILE = ".ignore";
 var FilesApi = class {
 	constructor(fs) {
 		this.fs = fs;
@@ -282,6 +297,16 @@ var MemFileHandle = class {
 		file.lastModified = Date.now();
 		return bytesWritten;
 	}
+	async read(buffer, offset, length, position) {
+		const entry = this.store.get(this.path);
+		if (!entry || entry.kind !== "file") return 0;
+		const content = entry.content;
+		const available = content.length - position;
+		if (available <= 0) return 0;
+		const bytesToRead = Math.min(length, available, buffer.length - offset);
+		buffer.set(content.subarray(position, position + bytesToRead), offset);
+		return bytesToRead;
+	}
 };
 var MemFilesApi = class {
 	store = /* @__PURE__ */ new Map();
@@ -446,6 +471,11 @@ var NodeFileHandleWrapper = class {
 	async chown(uid, gid) {
 		await this.handle.chown(uid, gid);
 	}
+	async read(buffer, offset, length, position) {
+		const actualLength = Math.min(length, buffer.length - offset);
+		if (actualLength <= 0) return 0;
+		return (await this.handle.read(buffer, offset, actualLength, position)).bytesRead;
+	}
 };
 var NodeFilesApi = class {
 	fs;
@@ -501,7 +531,10 @@ var NodeFilesApi = class {
 	async remove(file) {
 		const fullPath = this.resolvePath(file);
 		try {
-			if ((await this.fs.stat(fullPath)).isDirectory()) await this.fs.rm(fullPath, { recursive: true });
+			if ((await this.fs.stat(fullPath)).isDirectory()) await this.fs.rm(fullPath, {
+				recursive: true,
+				force: true
+			});
 			else await this.fs.unlink(fullPath);
 			return true;
 		} catch {
@@ -548,4 +581,4 @@ var NodeFilesApi = class {
 };
 
 //#endregion
-export { FilesApi, MemFilesApi, NodeFilesApi, basename, collectGenerator, dirname, extname, joinPath, normalizePath, resolveFileRef, toAsyncIterable, toBinaryAsyncIterable, toPath };
+export { FilesApi, MemFilesApi, NodeFilesApi, basename, collectGenerator, dirname, extname, isDirectory, isFile, joinPath, normalizePath, resolveFileRef, toAsyncIterable, toBinaryAsyncIterable, toPath };

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

@@ -1 +1 @@
-{"version":3,"file":"files-api.d.ts","sourceRoot":"","sources":["../src/files-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAMpB,qBAAa,QAAS,YAAW,SAAS;IAC5B,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,SAAS;IAMjC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC;IAIpE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAInD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAQxC;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7C;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAAC,UAAU,CAAC;IASvF;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAqBlD;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BzF;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAa9D;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAW1C"}
+{"version":3,"file":"files-api.d.ts","sourceRoot":"","sources":["../src/files-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAOpB,qBAAa,QAAS,YAAW,SAAS;IAC5B,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,SAAS;IAMjC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC;IAIpE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAInD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAQxC;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7C;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAAC,UAAU,CAAC;IASvF;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAShE;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAqBlD;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BzF;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAa9D;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAW1C"}

package/dist/impl/mem-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mem-files-api.d.ts","sourceRoot":"","sources":["../../src/impl/mem-files-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAGV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EAGZ,MAAM,aAAa,CAAC;AA6IrB,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,KAAK,CAA4B;IAElC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC;IAqEzE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IA0CnD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBvC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAKxC,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAS1C"}
+{"version":3,"file":"mem-files-api.d.ts","sourceRoot":"","sources":["../../src/impl/mem-files-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAGV,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EAGZ,MAAM,aAAa,CAAC;AA8JrB,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,KAAK,CAA4B;IAElC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC;IAqEzE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IA0CnD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBvC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAKxC,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAS1C"}

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

@@ -1 +1 @@
-{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../../src/impl/node-files-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAEhD,OAAO,KAAK,EAGV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EAGZ,MAAM,aAAa,CAAC;AAIrB,UAAU,mBAAmB;IAC3B,EAAE,EAAE,OAAO,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkGD,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,mBAAmB;IAKxC,OAAO,CAAC,WAAW;IAKZ,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC;IAsCzE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAkBnD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBvC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAexC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBxD,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBnF,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAI1C"}
+{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../../src/impl/node-files-api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAEhD,OAAO,KAAK,EAGV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EAGZ,MAAM,aAAa,CAAC;AAIrB,UAAU,mBAAmB;IAC3B,EAAE,EAAE,OAAO,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA4GD,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,mBAAmB;IAKxC,OAAO,CAAC,WAAW;IAKZ,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC;IAsCzE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAkBnD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBvC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAexC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBxD,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBnF,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAI1C"}

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export { NodeFilesApi } from "./impl/node-files-api.js";
 export type { AppendOptions, BinaryStream, CopyOptions, FileHandle, FileInfo, FileKind, FileRef, IFilesApi, ListOptions, ReadStreamOptions, WriteStreamOptions, } from "./types.js";
 export { collectGenerator, toAsyncIterable, toBinaryAsyncIterable, } from "./utils/collect-stream.js";
 export { normalizePath, resolveFileRef, toPath, } from "./utils/normalize-path.js";
+export { isDirectory, isFile } from "./utils/file-info-utils.js";
 export { basename, dirname, extname, joinPath } from "./utils/path-utils.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;;GAEG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,YAAY,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,aAAa,EACb,cAAc,EACd,MAAM,GACP,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types.d.ts

@@ -38,6 +38,16 @@ export interface FileHandle {
     appendFile(data: BinaryStream, options?: AppendOptions): Promise<number>;
     createReadStream(options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
     createWriteStream(data: BinaryStream, options?: WriteStreamOptions): Promise<number>;
+    /**
+     * Read bytes from the file at a specific position.
+     *
+     * @param buffer - The buffer to read bytes into
+     * @param offset - The offset in the buffer to start writing at
+     * @param length - The number of bytes to read
+     * @param position - The position in the file to start reading from
+     * @returns The number of bytes actually read (may be less than length at EOF)
+     */
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
     chmod?(mode: number): Promise<void>;
     chown?(uid: number, gid: number): Promise<void>;
 }

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,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AAE5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC1E,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErF,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IACpD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEzC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}
+{"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,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AAE5E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzE,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC1E,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErF;;;;;;;;OAQG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5F,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IACpD,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEzC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}

package/dist/utils/file-info-utils.d.ts

@@ -0,0 +1,10 @@
+import type { FileInfo } from "../types.js";
+/**
+ * Check if FileInfo represents a directory
+ */
+export declare function isDirectory(info: FileInfo | undefined): boolean;
+/**
+ * Check if FileInfo represents a file
+ */
+export declare function isFile(info: FileInfo | undefined): boolean;
+//# sourceMappingURL=file-info-utils.d.ts.map

package/dist/utils/file-info-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-info-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-info-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAE/D;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAE1D"}

package/dist/utils/index.d.ts

@@ -2,6 +2,7 @@
  * Utility functions
  */
 export * from "./collect-stream.js";
+export * from "./file-info-utils.js";
 export * from "./normalize-path.js";
 export * from "./path-utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Basic files API",
@@ -33,7 +33,8 @@
     "rimraf": "^6.1.2",
     "rolldown": "^1.0.0-beta.53",
     "typescript": "^5.6.0",
-    "vitest": "^4.0.12"
+    "vitest": "^4.0.12",
+    "@statewalker/webrun-files-tests": "1.0.0"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/files-api.ts

@@ -13,9 +13,10 @@ import type {
   ReadStreamOptions,
 } from "./types.js";
 import { toBinaryAsyncIterable } from "./utils/collect-stream.js";
-import { joinPath, resolveFileRef } from "./utils/index.js";
+import { resolveFileRef } from "./utils/index.js";
+import { joinPath } from "./utils/path-utils.js";
 
-const IGNORE_FILE = ".gitkeep";
+const IGNORE_FILE = ".ignore";
 
 export class FilesApi implements IFilesApi {
   constructor(private fs: IFilesApi) {}

package/src/impl/mem-files-api.ts

@@ -151,6 +151,23 @@ class MemFileHandle implements FileHandle {
 
     return bytesWritten;
   }
+
+  async read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number> {
+    const entry = this.store.get(this.path);
+    if (!entry || entry.kind !== "file") {
+      return 0;
+    }
+
+    const content = entry.content;
+    const available = content.length - position;
+    if (available <= 0) {
+      return 0;
+    }
+
+    const bytesToRead = Math.min(length, available, buffer.length - offset);
+    buffer.set(content.subarray(position, position + bytesToRead), offset);
+    return bytesToRead;
+  }
 }
 
 export class MemFilesApi implements IFilesApi {

package/src/impl/node-files-api.ts

@@ -118,6 +118,16 @@ class NodeFileHandleWrapper implements FileHandle {
   async chown(uid: number, gid: number): Promise<void> {
     await this.handle.chown(uid, gid);
   }
+
+  async read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number> {
+    // Limit length to what can fit in the buffer at the given offset
+    const actualLength = Math.min(length, buffer.length - offset);
+    if (actualLength <= 0) {
+      return 0;
+    }
+    const result = await this.handle.read(buffer, offset, actualLength, position);
+    return result.bytesRead;
+  }
 }
 
 export class NodeFilesApi implements IFilesApi {
@@ -196,7 +206,7 @@ export class NodeFilesApi implements IFilesApi {
     try {
       const stat = await this.fs.stat(fullPath);
       if (stat.isDirectory()) {
-        await this.fs.rm(fullPath, { recursive: true });
+        await this.fs.rm(fullPath, { recursive: true, force: true });
       } else {
         await this.fs.unlink(fullPath);
       }

package/src/index.ts

@@ -32,4 +32,5 @@ export {
   resolveFileRef,
   toPath,
 } from "./utils/normalize-path.js";
+export { isDirectory, isFile } from "./utils/file-info-utils.js";
 export { basename, dirname, extname, joinPath } from "./utils/path-utils.js";

package/src/types.ts

@@ -48,6 +48,17 @@ export interface FileHandle {
   createReadStream(options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
   createWriteStream(data: BinaryStream, options?: WriteStreamOptions): Promise<number>;
 
+  /**
+   * Read bytes from the file at a specific position.
+   *
+   * @param buffer - The buffer to read bytes into
+   * @param offset - The offset in the buffer to start writing at
+   * @param length - The number of bytes to read
+   * @param position - The position in the file to start reading from
+   * @returns The number of bytes actually read (may be less than length at EOF)
+   */
+  read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
+
   chmod?(mode: number): Promise<void>;
   chown?(uid: number, gid: number): Promise<void>;
 }

package/src/utils/file-info-utils.ts

@@ -0,0 +1,15 @@
+import type { FileInfo } from "../types.js";
+
+/**
+ * Check if FileInfo represents a directory
+ */
+export function isDirectory(info: FileInfo | undefined): boolean {
+  return info?.kind === "directory";
+}
+
+/**
+ * Check if FileInfo represents a file
+ */
+export function isFile(info: FileInfo | undefined): boolean {
+  return info?.kind === "file";
+}

package/src/utils/index.ts

@@ -3,5 +3,6 @@
  */
 
 export * from "./collect-stream.js";
+export * from "./file-info-utils.js";
 export * from "./normalize-path.js";
 export * from "./path-utils.js";