@statewalker/webrun-files 0.5.0 → 0.9.0

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,WAAW,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACjE,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;;;;;;;;;;;;;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/{utils/path-utils.d.ts → path-utils.d.ts}

@@ -1,6 +1,15 @@
 /**
- * Path manipulation utilities
+ * Path manipulation utilities for virtual filesystem paths.
+ * All paths use forward slashes and start with "/".
  */
+/**
+ * Normalizes a file path to a consistent format.
+ * - Adds leading slash if missing
+ * - Removes trailing slash
+ * - Removes `.` segments
+ * - Collapses multiple slashes
+ */
+export declare function normalizePath(filePath: string): string;
 /**
  * Joins path segments with proper normalization.
  */

package/dist/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../src/path-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGtD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C"}

package/dist/types.d.ts

@@ -1,67 +1,146 @@
 /**
- * Type definitions for IFilesApi
+ * Core types for FilesApi abstraction
  */
 export type FileKind = "file" | "directory";
-export interface FileInfo {
-    kind: FileKind;
-    name: string;
-    path: string;
-    type?: string;
-    size?: number;
-    lastModified: number;
+/**
+ * Options for reading file content with range support.
+ *
+ * @example
+ * // Read 100 bytes starting at position 50
+ * api.read("/file.bin", { start: 50, length: 100 })
+ *
+ * @example
+ * // Read from position 1000 to end of file
+ * api.read("/file.bin", { start: 1000 })
+ */
+export interface ReadOptions {
+    /** Starting byte position (0-indexed). Defaults to 0. */
+    start?: number;
+    /** Number of bytes to read. If omitted, reads to end of file. */
+    length?: number;
+    /** AbortSignal for cancellation support. */
+    signal?: AbortSignal;
 }
-export type FileRef = string | {
-    path: string;
-};
+/**
+ * Options for listing directory contents.
+ */
 export interface ListOptions {
+    /** If true, lists all descendants recursively. Defaults to false. */
     recursive?: boolean;
 }
-export interface CopyOptions {
-    recursive?: boolean;
+/**
+ * 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;
 }
-export interface AppendOptions {
-    signal?: AbortSignal;
+/**
+ * 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";
 }
-export interface ReadStreamOptions {
-    start?: number;
-    end?: number;
-    signal?: AbortSignal;
+/**
+ * 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;
 }
-export interface WriteStreamOptions {
-    start?: number;
-    signal?: AbortSignal;
+/** A file yielded by `list()`. */
+export interface FileEntryInfo extends FileEntryStats, FileEntryLocation {
 }
-export type BinaryStream = AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
-export interface FileHandle {
-    readonly size: number;
-    close(): Promise<void>;
-    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>;
+/** A directory yielded by `list()`. */
+export interface DirectoryEntryInfo extends DirectoryEntryStats, FileEntryLocation {
 }
 /**
- * Core filesystem interface - minimal contract for implementations.
- * Platform-specific implementations should implement this interface.
+ * 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 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>;
-    move?(source: FileRef, target: FileRef): Promise<boolean>;
-    copy?(source: FileRef, target: FileRef, options?: CopyOptions): Promise<boolean>;
-    mkdir?(file: FileRef): Promise<void>;
+export type FileInfo = FileEntryInfo | DirectoryEntryInfo;
+/**
+ * Cross-platform filesystem abstraction interface.
+ *
+ * All paths are virtual paths using forward slashes and starting with "/".
+ * Implementations handle mapping to underlying storage.
+ */
+export interface FilesApi {
+    /**
+     * Read file content as an async iterable of chunks.
+     * Returns empty iterable for non-existent files.
+     */
+    read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+    /**
+     * Write content to a file, creating parent directories as needed.
+     * Overwrites existing file content.
+     */
+    write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    /**
+     * Create a directory and all parent directories.
+     * No-op if directory already exists.
+     */
+    mkdir(path: string): Promise<void>;
+    /**
+     * List directory contents.
+     * Returns empty iterable for non-existent or non-directory paths.
+     */
+    list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    /**
+     * Get file or directory metadata.
+     * Returns undefined for non-existent paths.
+     */
+    stats(path: string): Promise<FileStats | undefined>;
+    /**
+     * Check if a path exists.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Remove a file or directory (recursively).
+     * Returns true if something was removed, false if path didn't exist.
+     */
+    remove(path: string): Promise<boolean>;
+    /**
+     * Move/rename a file or directory.
+     * Returns true on success, false if source doesn't exist.
+     */
+    move(source: string, target: string): Promise<boolean>;
+    /**
+     * Copy a file or directory (recursively).
+     * Returns true on success, false if source doesn't exist.
+     */
+    copy(source: string, target: string): Promise<boolean>;
 }
 //# sourceMappingURL=types.d.ts.map

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;;;;;;;;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"}
+{"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,9 +1,9 @@
 {
   "name": "@statewalker/webrun-files",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
-  "description": "Basic files API",
+  "description": "FilesApi interface and utilities for cross-platform filesystem abstraction",
   "homepage": "https://github.com/statewalker/webrun-files",
   "author": {
     "name": "Mikhail Kotelnikov",
@@ -29,12 +29,10 @@
     "src"
   ],
   "devDependencies": {
-    "@types/node": "^24.10.1",
-    "rimraf": "^6.1.2",
-    "rolldown": "^1.0.0-beta.53",
-    "typescript": "^5.6.0",
-    "vitest": "^4.0.12",
-    "@statewalker/webrun-files-tests": "1.0.0"
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2"
   },
   "sideEffects": false,
   "publishConfig": {
@@ -42,7 +40,6 @@
   },
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
-    "test": "vitest run",
-    "lint": "biome lint src tests"
+    "lint": "biome lint src"
   }
 }

package/src/file-utils.ts

@@ -0,0 +1,106 @@
+import type { FilesApi } from "./types.js";
+
+/**
+ * Collect async iterable chunks into a single Uint8Array.
+ */
+async function collectChunks(chunks: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const parts: Uint8Array[] = [];
+  let totalLength = 0;
+  for await (const chunk of chunks) {
+    parts.push(chunk);
+    totalLength += chunk.length;
+  }
+  if (parts.length === 0) return new Uint8Array(0);
+  if (parts.length === 1) return parts[0];
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of parts) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+
+/**
+ * Read entire file content into a Uint8Array.
+ * Returns empty array if file doesn't exist.
+ */
+export async function readFile(files: FilesApi, path: string): Promise<Uint8Array> {
+  return collectChunks(files.read(path));
+}
+
+/**
+ * Read entire file content as a UTF-8 string.
+ * Returns empty string if file doesn't exist.
+ */
+export async function readText(files: FilesApi, path: string): Promise<string> {
+  const data = await readFile(files, path);
+  return new TextDecoder().decode(data);
+}
+
+/**
+ * Read file content, returning undefined if file doesn't exist.
+ */
+export async function tryReadFile(files: FilesApi, path: string): Promise<Uint8Array | undefined> {
+  if (!(await files.exists(path))) return undefined;
+  return readFile(files, path);
+}
+
+/**
+ * Read file content as string, returning undefined if file doesn't exist.
+ */
+export async function tryReadText(files: FilesApi, path: string): Promise<string | undefined> {
+  const data = await tryReadFile(files, path);
+  return data ? new TextDecoder().decode(data) : undefined;
+}
+
+/**
+ * Read a specific byte range from a file.
+ *
+ * @param files - FilesApi instance
+ * @param path - File path
+ * @param position - Starting byte position
+ * @param length - Number of bytes to read
+ * @returns Uint8Array with requested bytes (may be shorter if EOF reached)
+ */
+export async function readRange(
+  files: FilesApi,
+  path: string,
+  position: number,
+  length: number,
+): Promise<Uint8Array> {
+  return collectChunks(files.read(path, { start: position, length }));
+}
+
+/**
+ * Read bytes from a file into a buffer at a specific offset.
+ * Similar to Node.js fs.read() signature.
+ *
+ * @param files - FilesApi instance
+ * @param path - File path
+ * @param buffer - Target buffer to write into
+ * @param bufferOffset - Offset in buffer where to start writing
+ * @param length - Number of bytes to read
+ * @param position - Position in file where to start reading
+ * @returns Number of bytes actually read
+ */
+export async function readAt(
+  files: FilesApi,
+  path: string,
+  buffer: Uint8Array,
+  bufferOffset: number,
+  length: number,
+  position: number,
+): Promise<number> {
+  const data = await readRange(files, path, position, length);
+  const bytesToCopy = Math.min(data.length, buffer.length - bufferOffset);
+  buffer.set(data.subarray(0, bytesToCopy), bufferOffset);
+  return bytesToCopy;
+}
+
+/**
+ * Write a string to a file as UTF-8.
+ */
+export async function writeText(files: FilesApi, path: string, content: string): Promise<void> {
+  await files.write(path, [new TextEncoder().encode(content)]);
+}

package/src/index.ts

@@ -1,36 +1,47 @@
 /**
  * webrun-files - Cross-platform filesystem API
+ *
+ * This package provides:
+ * - FilesApi interface for filesystem abstraction
+ * - Utility functions for common file operations
+ * - Path manipulation utilities
+ *
+ * For implementations, use:
+ * - @statewalker/webrun-files-mem (in-memory)
+ * - @statewalker/webrun-files-node (Node.js)
+ * - @statewalker/webrun-files-browser (browser)
+ * - @statewalker/webrun-files-s3 (S3)
  */
 
-// Wrapper class
-export { FilesApi } from "./files-api.js";
-// Implementations
-export { MemFilesApi } from "./impl/mem-files-api.js";
-export { NodeFilesApi } from "./impl/node-files-api.js";
-// Types
+// File utilities
+export {
+  readAt,
+  readFile,
+  readRange,
+  readText,
+  tryReadFile,
+  tryReadText,
+  writeText,
+} from "./file-utils.js";
+// Path utilities
+export {
+  basename,
+  dirname,
+  extname,
+  joinPath,
+  normalizePath,
+} from "./path-utils.js";
+// Core types
 export type {
-  AppendOptions,
-  BinaryStream,
-  CopyOptions,
-  FileHandle,
+  DirectoryEntryInfo,
+  DirectoryEntryStats,
+  FileEntryInfo,
+  FileEntryLocation,
+  FileEntryStats,
   FileInfo,
   FileKind,
-  FileRef,
-  IFilesApi,
+  FileStats,
+  FilesApi,
   ListOptions,
-  ReadStreamOptions,
-  WriteStreamOptions,
+  ReadOptions,
 } from "./types.js";
-export {
-  collectGenerator,
-  toAsyncIterable,
-  toBinaryAsyncIterable,
-} from "./utils/collect-stream.js";
-// Utilities
-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";

package/src/{utils/path-utils.ts → path-utils.ts}

@@ -1,8 +1,22 @@
 /**
- * Path manipulation utilities
+ * Path manipulation utilities for virtual filesystem paths.
+ * All paths use forward slashes and start with "/".
  */
 
-import { normalizePath } from "./normalize-path.js";
+/**
+ * Normalizes a file path to a consistent format.
+ * - Adds leading slash if missing
+ * - Removes trailing slash
+ * - Removes `.` segments
+ * - Collapses multiple slashes
+ */
+export function normalizePath(filePath: string): string {
+  const segments = filePath.split("/").filter((s) => !!s && s !== ".");
+  if (segments.length === 0) {
+    return "/";
+  }
+  return `/${segments.join("/")}`;
+}
 
 /**
  * Joins path segments with proper normalization.