@statewalker/webrun-files 0.3.1 → 0.4.0

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

@@ -0,0 +1,306 @@
+/**
+ * In-memory implementation of IFilesApi for testing
+ */
+
+import type {
+  AppendOptions,
+  BinaryStream,
+  FileHandle,
+  FileInfo,
+  FileRef,
+  IFilesApi,
+  ListOptions,
+  ReadStreamOptions,
+  WriteStreamOptions,
+} from "../types.js";
+import { toBinaryAsyncIterable } from "../utils/collect-stream.js";
+import { basename, joinPath, resolveFileRef } from "../utils/index.js";
+
+interface FileEntry {
+  kind: "file";
+  content: Uint8Array;
+  lastModified: number;
+}
+
+interface DirEntry {
+  kind: "directory";
+  lastModified: number;
+}
+
+type Entry = FileEntry | DirEntry;
+
+class MemFileHandle implements FileHandle {
+  constructor(
+    private store: Map<string, Entry>,
+    private path: string,
+  ) {}
+
+  get size(): number {
+    const entry = this.store.get(this.path);
+    if (entry?.kind === "file") {
+      return entry.content.length;
+    }
+    return 0;
+  }
+
+  private getOrCreateFile(): FileEntry {
+    let entry = this.store.get(this.path);
+    if (!entry || entry.kind !== "file") {
+      entry = {
+        kind: "file",
+        content: new Uint8Array(0),
+        lastModified: Date.now(),
+      };
+      this.store.set(this.path, entry);
+    }
+    return entry;
+  }
+
+  async close(): Promise<void> {
+    // No-op for memory implementation
+  }
+
+  async appendFile(data: BinaryStream, options: AppendOptions = {}): Promise<number> {
+    const file = this.getOrCreateFile();
+    const chunks: Uint8Array[] = [file.content];
+    let bytesWritten = 0;
+
+    for await (const chunk of toBinaryAsyncIterable(data)) {
+      if (options.signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+      chunks.push(chunk);
+      bytesWritten += chunk.length;
+    }
+
+    // Merge all chunks
+    const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+    const merged = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      merged.set(chunk, offset);
+      offset += chunk.length;
+    }
+
+    file.content = merged;
+    file.lastModified = Date.now();
+
+    return bytesWritten;
+  }
+
+  async *createReadStream(options: ReadStreamOptions = {}): AsyncGenerator<Uint8Array> {
+    const entry = this.store.get(this.path);
+    if (!entry || entry.kind !== "file") return;
+
+    const { start = 0, end = Infinity, signal } = options;
+    const bufferSize = 8192;
+    const content = entry.content;
+    const actualEnd = Math.min(end, content.length);
+
+    let position = start;
+
+    while (position < actualEnd) {
+      if (signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+
+      const remaining = actualEnd - position;
+      const toRead = Math.min(bufferSize, remaining);
+
+      yield content.subarray(position, position + toRead);
+      position += toRead;
+    }
+  }
+
+  async createWriteStream(data: BinaryStream, options: WriteStreamOptions = {}): Promise<number> {
+    const { start = 0, signal } = options;
+    const file = this.getOrCreateFile();
+
+    const chunks: Uint8Array[] = [];
+    let bytesWritten = 0;
+
+    // Keep content before start position
+    if (start > 0 && file.content.length > 0) {
+      chunks.push(file.content.subarray(0, Math.min(start, file.content.length)));
+    }
+
+    // Pad with zeros if start is beyond current content
+    if (start > file.content.length) {
+      chunks.push(new Uint8Array(start - file.content.length));
+    }
+
+    for await (const chunk of toBinaryAsyncIterable(data)) {
+      if (signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+      chunks.push(chunk);
+      bytesWritten += chunk.length;
+    }
+
+    // Merge all chunks
+    const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+    const merged = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      merged.set(chunk, offset);
+      offset += chunk.length;
+    }
+
+    file.content = merged;
+    file.lastModified = Date.now();
+
+    return bytesWritten;
+  }
+}
+
+export class MemFilesApi implements IFilesApi {
+  private store = new Map<string, Entry>();
+
+  async *list(file: FileRef, options: ListOptions = {}): AsyncGenerator<FileInfo> {
+    const normalized = resolveFileRef(file);
+    const prefix = normalized === "/" ? "/" : `${normalized}/`;
+    const { recursive = false } = options;
+
+    const seen = new Set<string>();
+
+    for (const [path, entry] of this.store.entries()) {
+      if (!path.startsWith(prefix)) continue;
+
+      const relativePath = path.substring(prefix.length);
+      const segments = relativePath.split("/");
+
+      if (segments.length === 0 || segments[0] === "") continue;
+
+      if (segments.length === 1) {
+        // Direct child file or directory
+        if (seen.has(path)) continue;
+        seen.add(path);
+
+        const info: FileInfo = {
+          kind: entry.kind,
+          name: basename(path),
+          path,
+          lastModified: entry.lastModified,
+        };
+
+        if (entry.kind === "file") {
+          info.size = entry.content.length;
+        }
+
+        yield info;
+      } else {
+        // This is a nested path
+        if (recursive) {
+          // Yield all nested entries
+          if (seen.has(path)) continue;
+          seen.add(path);
+
+          const info: FileInfo = {
+            kind: entry.kind,
+            name: basename(path),
+            path,
+            lastModified: entry.lastModified,
+          };
+
+          if (entry.kind === "file") {
+            info.size = entry.content.length;
+          }
+
+          yield info;
+        } else {
+          // Non-recursive: yield the intermediate directory
+          const dirName = segments[0];
+          const dirPath = joinPath(normalized, dirName);
+          if (!seen.has(dirPath)) {
+            seen.add(dirPath);
+            yield {
+              kind: "directory",
+              name: dirName,
+              path: dirPath,
+              lastModified: 0,
+            };
+          }
+        }
+      }
+    }
+  }
+
+  async stats(file: FileRef): Promise<FileInfo | undefined> {
+    const normalized = resolveFileRef(file);
+
+    const entry = this.store.get(normalized);
+    if (entry) {
+      const info: FileInfo = {
+        kind: entry.kind,
+        name: basename(normalized),
+        path: normalized,
+        lastModified: entry.lastModified,
+      };
+      if (entry.kind === "file") {
+        info.size = entry.content.length;
+      }
+      return info;
+    }
+
+    // Check if it's an implicit directory (root always exists)
+    if (normalized === "/") {
+      return {
+        kind: "directory",
+        name: "",
+        path: "/",
+        lastModified: 0,
+      };
+    }
+
+    const prefix = `${normalized}/`;
+    for (const path of this.store.keys()) {
+      if (path.startsWith(prefix)) {
+        return {
+          kind: "directory",
+          name: basename(normalized),
+          path: normalized,
+          lastModified: 0,
+        };
+      }
+    }
+
+    return undefined;
+  }
+
+  async remove(file: FileRef): Promise<boolean> {
+    const normalized = resolveFileRef(file);
+    const prefix = `${normalized}/`;
+
+    let removed = false;
+
+    // Remove exact match
+    if (this.store.delete(normalized)) {
+      removed = true;
+    }
+
+    // Remove all children (for directories)
+    for (const path of [...this.store.keys()]) {
+      if (path.startsWith(prefix)) {
+        this.store.delete(path);
+        removed = true;
+      }
+    }
+
+    return removed;
+  }
+
+  async open(file: FileRef): Promise<FileHandle> {
+    const normalized = resolveFileRef(file);
+    return new MemFileHandle(this.store, normalized);
+  }
+
+  async mkdir(file: FileRef): Promise<void> {
+    const normalized = resolveFileRef(file);
+    if (!this.store.has(normalized)) {
+      this.store.set(normalized, {
+        kind: "directory",
+        lastModified: Date.now(),
+      });
+    }
+  }
+}

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

@@ -0,0 +1,261 @@
+/**
+ * Node.js implementation of IFilesApi
+ */
+
+import type * as NodeFS from "node:fs/promises";
+import type { FileHandle as NodeFileHandle } from "node:fs/promises";
+import type {
+  AppendOptions,
+  BinaryStream,
+  CopyOptions,
+  FileHandle,
+  FileInfo,
+  FileRef,
+  IFilesApi,
+  ListOptions,
+  ReadStreamOptions,
+  WriteStreamOptions,
+} from "../types.js";
+import { toBinaryAsyncIterable } from "../utils/collect-stream.js";
+import { basename, dirname, joinPath, resolveFileRef } from "../utils/index.js";
+
+interface NodeFilesApiOptions {
+  fs: typeof NodeFS;
+  rootDir?: string;
+}
+
+/**
+ * Wraps Node.js FileHandle to implement our FileHandle interface.
+ */
+class NodeFileHandleWrapper implements FileHandle {
+  constructor(
+    private handle: NodeFileHandle,
+    private _size: number,
+  ) {}
+
+  get size(): number {
+    return this._size;
+  }
+
+  async close(): Promise<void> {
+    await this.handle.close();
+  }
+
+  async appendFile(data: BinaryStream, options: AppendOptions = {}): Promise<number> {
+    let bytesWritten = 0;
+    const asyncData = toBinaryAsyncIterable(data);
+
+    for await (const chunk of asyncData) {
+      if (options.signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+      await this.handle.appendFile(chunk);
+      bytesWritten += chunk.length;
+    }
+
+    // Update size
+    const stat = await this.handle.stat();
+    this._size = stat.size;
+
+    return bytesWritten;
+  }
+
+  async *createReadStream(options: ReadStreamOptions = {}): AsyncGenerator<Uint8Array> {
+    const { start = 0, end = Infinity, signal } = options;
+    const bufferSize = 8192;
+
+    let position = start;
+    const actualEnd = Math.min(end, this._size);
+
+    while (position < actualEnd) {
+      if (signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+
+      const remaining = actualEnd - position;
+      const toRead = Math.min(bufferSize, remaining);
+      const buffer = new Uint8Array(toRead);
+
+      const { bytesRead } = await this.handle.read(buffer, 0, toRead, position);
+      if (bytesRead === 0) break;
+
+      yield buffer.subarray(0, bytesRead);
+      position += bytesRead;
+    }
+  }
+
+  async createWriteStream(data: BinaryStream, options: WriteStreamOptions = {}): Promise<number> {
+    const { start = 0, signal } = options;
+    let position = start;
+    let bytesWritten = 0;
+
+    const asyncData = toBinaryAsyncIterable(data);
+
+    // Truncate file at start position
+    await this.handle.truncate(start);
+
+    for await (const chunk of asyncData) {
+      if (signal?.aborted) {
+        throw new Error("Operation aborted");
+      }
+
+      const { bytesWritten: written } = await this.handle.write(chunk, 0, chunk.length, position);
+      position += written;
+      bytesWritten += written;
+    }
+
+    // Update size
+    const stat = await this.handle.stat();
+    this._size = stat.size;
+
+    return bytesWritten;
+  }
+
+  async chmod(mode: number): Promise<void> {
+    await this.handle.chmod(mode);
+  }
+
+  async chown(uid: number, gid: number): Promise<void> {
+    await this.handle.chown(uid, gid);
+  }
+}
+
+export class NodeFilesApi implements IFilesApi {
+  private fs: typeof NodeFS;
+  private rootDir: string;
+
+  constructor(options: NodeFilesApiOptions) {
+    this.fs = options.fs;
+    this.rootDir = options.rootDir ?? "";
+  }
+
+  private resolvePath(file: FileRef): string {
+    const normalized = resolveFileRef(file);
+    return this.rootDir + normalized;
+  }
+
+  async *list(file: FileRef, options: ListOptions = {}): AsyncGenerator<FileInfo> {
+    const dirPath = this.resolvePath(file);
+    const { recursive = false } = options;
+
+    try {
+      const entries = await this.fs.readdir(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const entryPath = joinPath(resolveFileRef(file), entry.name);
+        const fullPath = this.rootDir + entryPath;
+
+        const info: FileInfo = {
+          kind: entry.isDirectory() ? "directory" : "file",
+          name: entry.name,
+          path: entryPath,
+          lastModified: 0,
+        };
+
+        // Get full stats for size and mtime
+        try {
+          const stat = await this.fs.stat(fullPath);
+          info.size = stat.size;
+          info.lastModified = stat.mtimeMs;
+        } catch {
+          // Ignore stat errors
+        }
+
+        yield info;
+
+        if (recursive && entry.isDirectory()) {
+          yield* this.list(entryPath, options);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or isn't readable
+    }
+  }
+
+  async stats(file: FileRef): Promise<FileInfo | undefined> {
+    const fullPath = this.resolvePath(file);
+    const normalized = resolveFileRef(file);
+
+    try {
+      const stat = await this.fs.stat(fullPath);
+      return {
+        kind: stat.isDirectory() ? "directory" : "file",
+        name: basename(normalized),
+        path: normalized,
+        size: stat.size,
+        lastModified: stat.mtimeMs,
+      };
+    } catch {
+      return undefined;
+    }
+  }
+
+  async remove(file: FileRef): Promise<boolean> {
+    const fullPath = this.resolvePath(file);
+
+    try {
+      const stat = await this.fs.stat(fullPath);
+      if (stat.isDirectory()) {
+        await this.fs.rm(fullPath, { recursive: true });
+      } else {
+        await this.fs.unlink(fullPath);
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async open(file: FileRef): Promise<FileHandle> {
+    const fullPath = this.resolvePath(file);
+    const normalized = resolveFileRef(file);
+
+    // Ensure parent directory exists
+    const dir = this.rootDir + dirname(normalized);
+    await this.fs.mkdir(dir, { recursive: true });
+
+    // Open file with read/write access, create if doesn't exist
+    const handle = await this.fs.open(fullPath, "a+");
+    const stat = await handle.stat();
+
+    return new NodeFileHandleWrapper(handle, stat.size);
+  }
+
+  async move(source: FileRef, target: FileRef): Promise<boolean> {
+    const sourcePath = this.resolvePath(source);
+    const targetPath = this.resolvePath(target);
+
+    try {
+      // Ensure target parent directory exists
+      const targetDir = dirname(targetPath);
+      await this.fs.mkdir(targetDir, { recursive: true });
+
+      await this.fs.rename(sourcePath, targetPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async copy(source: FileRef, target: FileRef, options: CopyOptions = {}): Promise<boolean> {
+    const sourcePath = this.resolvePath(source);
+    const targetPath = this.resolvePath(target);
+    const { recursive = true } = options;
+
+    try {
+      // Ensure target parent directory exists
+      const targetDir = dirname(targetPath);
+      await this.fs.mkdir(targetDir, { recursive: true });
+
+      await this.fs.cp(sourcePath, targetPath, { recursive });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async mkdir(file: FileRef): Promise<void> {
+    const fullPath = this.resolvePath(file);
+    await this.fs.mkdir(fullPath, { recursive: true });
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * webrun-files - Cross-platform filesystem API
+ */
+
+// 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
+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";
+// Utilities
+export {
+  normalizePath,
+  resolveFileRef,
+  toPath,
+} from "./utils/normalize-path.js";
+export { basename, dirname, extname, joinPath } from "./utils/path-utils.js";

package/src/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Type definitions for IFilesApi
+ */
+
+export type FileKind = "file" | "directory";
+
+export interface FileInfo {
+  kind: FileKind;
+  name: string;
+  path: string;
+  type?: string;
+  size?: number;
+  lastModified: number;
+}
+
+export type FileRef = string | { path: string };
+
+export interface ListOptions {
+  recursive?: boolean;
+}
+
+export interface CopyOptions {
+  recursive?: boolean;
+}
+
+export interface AppendOptions {
+  signal?: AbortSignal;
+}
+
+export interface ReadStreamOptions {
+  start?: number;
+  end?: number;
+  signal?: AbortSignal;
+}
+
+export interface WriteStreamOptions {
+  start?: number;
+  signal?: AbortSignal;
+}
+
+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>;
+
+  chmod?(mode: number): Promise<void>;
+  chown?(uid: number, gid: number): Promise<void>;
+}
+
+/**
+ * Core filesystem interface - minimal contract for implementations.
+ * Platform-specific implementations should implement this interface.
+ */
+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>;
+}

package/src/utils/collect-stream.ts

@@ -0,0 +1,35 @@
+/**
+ * Stream collection utilities
+ */
+
+/**
+ * Collects all values from an async generator into an array.
+ */
+export async function collectGenerator<T>(generator: AsyncIterable<T>): Promise<T[]> {
+  const results: T[] = [];
+  for await (const item of generator) {
+    results.push(item);
+  }
+  return results;
+}
+
+/**
+ * Converts a synchronous iterable to an async iterable.
+ */
+export async function* toAsyncIterable<T>(iterable: Iterable<T>): AsyncIterable<T> {
+  for (const item of iterable) {
+    yield item;
+  }
+}
+
+/**
+ * Normalizes BinaryStream to AsyncIterable<Uint8Array>.
+ */
+export function toBinaryAsyncIterable(
+  data: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+): AsyncIterable<Uint8Array> {
+  if (Symbol.asyncIterator in data) {
+    return data as AsyncIterable<Uint8Array>;
+  }
+  return toAsyncIterable(data as Iterable<Uint8Array>);
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility functions
+ */
+
+export * from "./collect-stream.js";
+export * from "./normalize-path.js";
+export * from "./path-utils.js";