@statewalker/webrun-files 0.3.1 → 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/utils/collect-stream.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stream collection utilities
+ */
+/**
+ * Collects all values from an async generator into an array.
+ */
+export declare function collectGenerator<T>(generator: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Converts a synchronous iterable to an async iterable.
+ */
+export declare function toAsyncIterable<T>(iterable: Iterable<T>): AsyncIterable<T>;
+/**
+ * Normalizes BinaryStream to AsyncIterable<Uint8Array>.
+ */
+export declare function toBinaryAsyncIterable(data: AsyncIterable<Uint8Array> | Iterable<Uint8Array>): AsyncIterable<Uint8Array>;
+//# sourceMappingURL=collect-stream.d.ts.map

package/dist/utils/collect-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-stream.d.ts","sourceRoot":"","sources":["../../src/utils/collect-stream.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAMnF;AAED;;GAEG;AACH,wBAAuB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAIjF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,GACrD,aAAa,CAAC,UAAU,CAAC,CAK3B"}

package/dist/utils/index.d.ts

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

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

@@ -0,0 +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"}

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

@@ -0,0 +1,21 @@
+/**
+ * Path normalization utilities
+ */
+import type { FileRef } from "../types.js";
+/**
+ * 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;
+/**
+ * Extracts path string from FileRef.
+ */
+export declare function toPath(file: FileRef): string;
+/**
+ * Normalizes FileRef to a path string.
+ */
+export declare function resolveFileRef(file: FileRef): string;
+//# sourceMappingURL=normalize-path.d.ts.map

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

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

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

@@ -0,0 +1,20 @@
+/**
+ * Path manipulation utilities
+ */
+/**
+ * Joins path segments with proper normalization.
+ */
+export declare function joinPath(...segments: string[]): string;
+/**
+ * Returns the directory portion of a path.
+ */
+export declare function dirname(path: string): string;
+/**
+ * Returns the filename portion of a path.
+ */
+export declare function basename(path: string, ext?: string): string;
+/**
+ * Returns the file extension including the dot.
+ */
+export declare function extname(path: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;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/package.json

@@ -1,49 +1,47 @@
 {
   "name": "@statewalker/webrun-files",
-  "version": "0.3.1",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
   "description": "Basic files API",
-  "keywords": [],
   "homepage": "https://github.com/statewalker/webrun-files",
   "author": {
     "name": "Mikhail Kotelnikov",
     "email": "mikhail.kotelnikov@gmail.com"
   },
   "license": "MIT",
-  "type": "module",
-  "files": [
-    "dist/**/package.json",
-    "dist/**/*.js",
-    "src/**/*.js",
-    "index.js"
-  ],
-  "module": "src/index.js",
-  "main": "src/index.js",
-  "jsdelivr": "dist/index.js",
-  "unpkg": "dist/index.js",
-  "exports": {
-    "umd": "./dist/index-umd.min.js",
-    "default": "./src/index.js"
-  },
-  "devDependencies": {
-    "@statewalker/rollup": "^0.1.6",
-    "@statewalker/webrun-files-tests": "^0.1.0",
-    "eslint": "^8",
-    "expect.js": "^0.3",
-    "mocha": "^10",
-    "rollup": "^3"
-  },
   "repository": {
     "type": "git",
     "url": "git@github.com:statewalker/webrun-files.git"
   },
-  "scripts": {
-    "eslint": "eslint src",
-    "rollup": "rollup -c",
-    "test": "mocha -R spec ./test/index.js",
-    "prepublishOnly": "rm -rf dist && yarn test && yarn rollup"
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "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"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
   }
-}
+}

package/src/files-api.ts

@@ -0,0 +1,167 @@
+/**
+ * FilesApi wrapper class providing convenience methods on top of IFilesApi
+ */
+
+import type {
+  BinaryStream,
+  CopyOptions,
+  FileHandle,
+  FileInfo,
+  FileRef,
+  IFilesApi,
+  ListOptions,
+  ReadStreamOptions,
+} from "./types.js";
+import { toBinaryAsyncIterable } from "./utils/collect-stream.js";
+import { joinPath, resolveFileRef } from "./utils/index.js";
+
+const IGNORE_FILE = ".gitkeep";
+
+export class FilesApi implements IFilesApi {
+  constructor(private fs: IFilesApi) {}
+
+  // ========================================
+  // IFilesApi delegation
+  // ========================================
+
+  list(file: FileRef, options?: ListOptions): AsyncGenerator<FileInfo> {
+    return this.fs.list(file, options);
+  }
+
+  stats(file: FileRef): Promise<FileInfo | undefined> {
+    return this.fs.stats(file);
+  }
+
+  remove(file: FileRef): Promise<boolean> {
+    return this.fs.remove(file);
+  }
+
+  open(file: FileRef): Promise<FileHandle> {
+    return this.fs.open(file);
+  }
+
+  // ========================================
+  // Convenience methods built on core API
+  // ========================================
+
+  /**
+   * Checks if a file or directory exists.
+   */
+  async exists(file: FileRef): Promise<boolean> {
+    const info = await this.stats(file);
+    return info !== undefined;
+  }
+
+  /**
+   * Reads file content as a stream.
+   */
+  async *read(file: FileRef, options: ReadStreamOptions = {}): AsyncGenerator<Uint8Array> {
+    const handle = await this.open(file);
+    try {
+      yield* handle.createReadStream(options);
+    } finally {
+      await handle.close();
+    }
+  }
+
+  /**
+   * Writes content to a file.
+   */
+  async write(file: FileRef, content: BinaryStream): Promise<void> {
+    const handle = await this.open(file);
+    try {
+      await handle.createWriteStream(toBinaryAsyncIterable(content));
+    } finally {
+      await handle.close();
+    }
+  }
+
+  /**
+   * Reads entire file into a single buffer.
+   */
+  async readFile(file: FileRef): Promise<Uint8Array> {
+    const chunks: Uint8Array[] = [];
+    let totalLength = 0;
+
+    for await (const chunk of this.read(file)) {
+      chunks.push(chunk);
+      totalLength += chunk.length;
+    }
+
+    if (chunks.length === 0) return new Uint8Array(0);
+    if (chunks.length === 1) return chunks[0];
+
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+
+  /**
+   * Copies file or directory.
+   * Uses native implementation if available, otherwise falls back to read/write.
+   */
+  async copy(source: FileRef, target: FileRef, options: CopyOptions = {}): Promise<boolean> {
+    // Try native implementation first
+    if (this.fs.copy) {
+      return this.fs.copy(source, target, options);
+    }
+
+    // Fallback: read from source, write to target
+    const sourceInfo = await this.stats(source);
+    if (!sourceInfo) return false;
+
+    const sourcePath = resolveFileRef(source);
+    const targetPath = resolveFileRef(target);
+    const recursive = options.recursive ?? true;
+
+    if (sourceInfo.kind === "directory") {
+      for await (const entry of this.list(source, { recursive })) {
+        if (entry.kind === "directory") continue;
+        const suffix = entry.path.substring(sourcePath.length);
+        const newTargetPath = targetPath + suffix;
+        await this.write(newTargetPath, this.read(entry.path));
+      }
+    } else {
+      await this.write(targetPath, this.read(sourcePath));
+    }
+
+    return true;
+  }
+
+  /**
+   * Moves file or directory.
+   * Uses native implementation if available, otherwise falls back to copy+delete.
+   */
+  async move(source: FileRef, target: FileRef): Promise<boolean> {
+    // Try native implementation first
+    if (this.fs.move) {
+      return this.fs.move(source, target);
+    }
+
+    // Fallback: copy then delete
+    const copied = await this.copy(source, target);
+    if (!copied) return false;
+    await this.remove(source);
+    return true;
+  }
+
+  /**
+   * Creates a directory.
+   * Uses native implementation if available, otherwise creates a placeholder file.
+   */
+  async mkdir(file: FileRef): Promise<void> {
+    // Try native implementation first
+    if (this.fs.mkdir) {
+      return this.fs.mkdir(file);
+    }
+
+    // Fallback: create a placeholder file to establish the directory
+    const dirPath = resolveFileRef(file);
+    const placeholderPath = joinPath(dirPath, IGNORE_FILE);
+    await this.write(placeholderPath, [new Uint8Array(0)]);
+  }
+}

package/src/impl/index.ts

@@ -0,0 +1,6 @@
+/**
+ * IFilesApi implementations
+ */
+
+export * from "./mem-files-api.js";
+export * from "./node-files-api.js";