@ecopages/file-system 0.2.0-alpha.0 → 0.2.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `@ecopages/file-system` are documented here.
+
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+
+## [UNRELEASED] — TBD
+
+### Bug Fixes
+
+- Switched Node-side globbing from `fast-glob` to native `node:fs/promises.glob()` so bundled ESM runtime paths avoid CommonJS interop failures.

package/README.md

@@ -1,18 +1,17 @@
 # @ecopages/file-system
 
-Runtime-agnostic file system utilities for Ecopages with optimized Bun and Node.js adapters.
+Runtime-agnostic file system utilities for Ecopages that automatically select the optimal adapter (Bun or Node.js) based on the execution environment.
 
 ## Features
 
-- **Runtime Detection**: Automatically selects optimal adapter based on runtime
-- **Bun Optimized**: Uses `Bun.Glob`, `Bun.hash`, `Bun.file` for maximum performance
-- **Node.js Fallback**: Uses `fast-glob` and `crypto` for full compatibility
-- **Type Safe**: Full TypeScript support with consistent interface
+- **Runtime Detection**: Automatically uses `Bun.Glob`, `Bun.hash`, `Bun.file` for maximum performance on Bun, and falls back to `fast-glob` and `crypto` on Node.js.
+- **Unified Interface**: Write file system code once; let the runtime handle the optimization.
+- **Type Safe**: Full TypeScript support with a consistent API.
 
 ## Installation
 
 ```bash
-bun add @ecopages/file-system
+bunx jsr add @ecopages/file-system
 ```
 
 ## Usage
@@ -41,11 +40,11 @@ if (fileSystem.exists('file.txt')) {
 ## API
 
 | Method                      | Description                       |
-| --------------------------- | --------------------------------- |
+| :-------------------------- | :-------------------------------- |
 | `glob(patterns, options)`   | Find files matching glob patterns |
 | `readFile(path)`            | Read file as string (async)       |
 | `readFileSync(path)`        | Read file as string (sync)        |
-| `readFileAsBuffer(path)`    | Read file as Buffer               |
+| `readFileAsBuffer(path)`    | Read file as `Buffer`             |
 | `write(path, content)`      | Write content to file             |
 | `writeAsync(path, content)` | Write content to file (async)     |
 | `exists(path)`              | Check if path exists              |
@@ -59,18 +58,3 @@ if (fileSystem.exists('file.txt')) {
 | `gzipDir(path, extensions)` | Gzip files in directory           |
 | `isDirectory(path)`         | Check if path is directory        |
 | `verifyFileExists(path)`    | Throw if file doesn't exist       |
-
-## Performance
-
-Benchmark results (Apple M4):
-
-| Operation        | BunFileSystem | NodeFileSystem |
-| ---------------- | ------------- | -------------- |
-| glob (100 files) | 64.85 µs      | 71.06 µs       |
-| hash (1MB file)  | **87 µs**     | **393 µs**     |
-
-Bun adapter is **4.5x faster** for file hashing.
-
-## License
-
-MIT

package/package.json

@@ -1,60 +1,59 @@
 {
-	"name": "@ecopages/file-system",
-	"version": "0.2.0-alpha.0",
-	"description": "Runtime-agnostic file system utilities for Ecopages with Bun and Node adapters",
-	"keywords": [
-		"ecopages",
-		"fs",
-		"file-system",
-		"bun",
-		"node"
-	],
-	"license": "MIT",
-	"main": "./src/index.ts",
-	"type": "module",
-	"files": [
-		"src"
-	],
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/ecopages/ecopages.git",
-		"directory": "packages/file-system"
-	},
-	"scripts": {
-		"typecheck": "tsc --noEmit",
-		"test": "bun test",
-		"benchmark": "bun run test/benchmark.ts",
-		"release:jsr": "bunx jsr publish"
-	},
-	"exports": {
-		".": {
-			"import": "./src/index.ts",
-			"require": "./src/index.ts",
-			"types": "./src/types.ts"
-		},
-		"./bun": {
-			"import": "./src/adapters/bun.ts",
-			"types": "./src/adapters/bun.ts"
-		},
-		"./node": {
-			"import": "./src/adapters/node.ts",
-			"types": "./src/adapters/node.ts"
-		}
-	},
-	"dependencies": {
-		"fast-glob": "^3.3.2"
-	},
-	"devDependencies": {
-		"@types/bun": "^1.3.9",
-		"@types/node": "^24",
-		"mitata": "^1.0.34"
-	},
-	"peerDependencies": {
-		"bun": ">=1.0.0"
-	},
-	"peerDependenciesMeta": {
-		"bun": {
-			"optional": true
-		}
-	}
+  "name": "@ecopages/file-system",
+  "version": "0.2.0-alpha.10",
+  "description": "Runtime-agnostic file system utilities for Ecopages with Bun and Node adapters",
+  "keywords": [
+    "ecopages",
+    "fs",
+    "file-system",
+    "bun",
+    "node"
+  ],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/file-system"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/types.d.ts",
+      "default": "./src/index.js"
+    },
+    "./bun": {
+      "import": "./src/adapters/bun.js",
+      "types": "./src/adapters/bun.d.ts",
+      "default": "./src/adapters/bun.js"
+    },
+    "./node": {
+      "import": "./src/adapters/node.js",
+      "types": "./src/adapters/node.d.ts",
+      "default": "./src/adapters/node.js"
+    },
+    "./bun.ts": {
+      "import": "./src/adapters/bun.js",
+      "types": "./src/adapters/bun.d.ts",
+      "default": "./src/adapters/bun.js"
+    },
+    "./node.ts": {
+      "import": "./src/adapters/node.js",
+      "types": "./src/adapters/node.d.ts",
+      "default": "./src/adapters/node.js"
+    }
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.2"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "bun": {
+      "optional": true
+    }
+  },
+  "types": "./src/types.d.ts"
 }

package/src/adapters/bun.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module @ecopages/file-system/adapters/bun
+ * @description Bun-optimized file system adapter using Bun.Glob, Bun.hash, and Bun.file.
+ */
+import type { FileSystem, GlobOptions } from '../types.js';
+import { BaseFileSystem } from '../utils/common.js';
+/**
+ * Bun-optimized implementation of the FileSystem interface.
+ */
+export declare class BunFileSystem extends BaseFileSystem implements FileSystem {
+    existsAsync(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    writeAsync(filepath: string, contents: string | Buffer): Promise<void>;
+    copyFileAsync(source: string, destination: string): Promise<void>;
+    glob(patterns: string[], options?: GlobOptions): Promise<string[]>;
+    hash(path: string): string;
+}
+/**
+ * Singleton instance for Bun runtime.
+ */
+export declare const bunFs: BunFileSystem;

package/src/adapters/bun.js

@@ -0,0 +1,63 @@
+import { dirname } from "node:path";
+import { BaseFileSystem } from "../utils/common.js";
+class BunFileSystem extends BaseFileSystem {
+  async existsAsync(path) {
+    return Bun.file(path).exists();
+  }
+  async readFile(path) {
+    try {
+      this.verifyFileExists(path);
+      return await Bun.file(path).text();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error reading file: ${path}, ${message}`);
+    }
+  }
+  async writeAsync(filepath, contents) {
+    try {
+      await this.ensureDirAsync(dirname(filepath));
+      await Bun.write(filepath, contents);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error writing file: ${filepath}. Cause: ${message}`);
+    }
+  }
+  async copyFileAsync(source, destination) {
+    try {
+      await Bun.write(destination, Bun.file(source));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error copying file: ${source} to ${destination}. Cause: ${message}`);
+    }
+  }
+  async glob(patterns, options = {}) {
+    const scanOptions = {
+      cwd: options.cwd ?? process.cwd()
+    };
+    const promises = patterns.map((pattern) => {
+      const glob = new Bun.Glob(pattern);
+      return Array.fromAsync(glob.scan(scanOptions));
+    });
+    const results = await Promise.all(promises);
+    let files = results.flat();
+    if (options.ignore?.length) {
+      const ignoreGlobs = options.ignore.map((pattern) => new Bun.Glob(pattern));
+      files = files.filter((file) => !ignoreGlobs.some((glob) => glob.match(file)));
+    }
+    return files;
+  }
+  hash(path) {
+    try {
+      const buffer = this.readFileAsBuffer(path);
+      return Bun.hash(buffer).toString();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error hashing file: ${path}. Cause: ${message}`);
+    }
+  }
+}
+const bunFs = new BunFileSystem();
+export {
+  BunFileSystem,
+  bunFs
+};

package/src/adapters/node.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module @ecopages/file-system/adapters/node
+ * @description Node.js file system adapter using fast-glob, crypto, and node:fs.
+ */
+import type { FileSystem, GlobOptions } from '../types.js';
+import { BaseFileSystem } from '../utils/common.js';
+/**
+ * Node.js implementation of the FileSystem interface.
+ */
+export declare class NodeFileSystem extends BaseFileSystem implements FileSystem {
+    existsAsync(filePath: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    writeAsync(filepath: string, contents: string | Buffer): Promise<void>;
+    copyFileAsync(source: string, destination: string): Promise<void>;
+    glob(patterns: string[], options?: GlobOptions): Promise<string[]>;
+    hash(path: string): string;
+}
+/**
+ * Singleton instance for Node.js runtime.
+ */
+export declare const nodeFs: NodeFileSystem;

package/src/adapters/node.js

@@ -0,0 +1,69 @@
+import crypto from "node:crypto";
+import {
+  access as accessAsync,
+  cp as cpAsync,
+  glob as globAsync,
+  readFile as readFileAsync,
+  writeFile as writeFileAsync
+} from "node:fs/promises";
+import { dirname } from "node:path";
+import { BaseFileSystem } from "../utils/common.js";
+async function collectGlobMatches(pattern, options) {
+  const matches = [];
+  for await (const entry of globAsync(pattern, {
+    cwd: options.cwd ?? process.cwd(),
+    exclude: options.ignore
+  })) {
+    matches.push(entry);
+  }
+  return matches;
+}
+class NodeFileSystem extends BaseFileSystem {
+  async existsAsync(filePath) {
+    try {
+      await accessAsync(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async readFile(path) {
+    try {
+      this.verifyFileExists(path);
+      return await readFileAsync(path, "utf-8");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error reading file: ${path}, ${message}`);
+    }
+  }
+  async writeAsync(filepath, contents) {
+    try {
+      await this.ensureDirAsync(dirname(filepath));
+      await writeFileAsync(filepath, contents);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error writing file: ${filepath}. Cause: ${message}`);
+    }
+  }
+  async copyFileAsync(source, destination) {
+    await cpAsync(source, destination);
+  }
+  async glob(patterns, options = {}) {
+    const files = await Promise.all(patterns.map((pattern) => collectGlobMatches(pattern, options)));
+    return Array.from(new Set(files.flat()));
+  }
+  hash(path) {
+    try {
+      const buffer = this.readFileAsBuffer(path);
+      return crypto.createHash("sha256").update(buffer).digest("hex");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Error hashing file: ${path}. Cause: ${message}`);
+    }
+  }
+}
+const nodeFs = new NodeFileSystem();
+export {
+  NodeFileSystem,
+  nodeFs
+};

package/src/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module @ecopages/file-system
+ * @description Runtime-agnostic file system utilities for Ecopages.
+ *
+ * Automatically selects the optimal adapter based on runtime:
+ * - **Bun**: Uses `Bun.Glob`, `Bun.hash`, `Bun.file` for maximum performance
+ * - **Node.js**: Uses native `node:fs/promises.glob()` and `crypto`
+ *
+ * @example
+ * ```typescript
+ * import { fileSystem } from '@ecopages/file-system';
+ *
+ * const files = await fileSystem.glob(['**\/*.ts']);
+ * const content = await fileSystem.readFile('file.txt');
+ */
+export * from './types.js';
+export { BaseFileSystem } from './utils/common.js';
+export { BunFileSystem, bunFs } from './adapters/bun.js';
+export { NodeFileSystem, nodeFs } from './adapters/node.js';
+import type { FileSystem } from './types.js';
+/**
+ * Runtime-agnostic file system instance.
+ * Automatically uses Bun or Node adapter based on environment.
+ */
+export declare const fileSystem: FileSystem;

package/src/index.js

@@ -0,0 +1,21 @@
+export * from "./types.js";
+import { BaseFileSystem } from "./utils/common.js";
+import { BunFileSystem, bunFs } from "./adapters/bun.js";
+import { NodeFileSystem, nodeFs } from "./adapters/node.js";
+async function createFileSystem() {
+  if (typeof Bun !== "undefined") {
+    const { bunFs: bunFs2 } = await import("./adapters/bun.js");
+    return bunFs2;
+  }
+  const { nodeFs: nodeFs2 } = await import("./adapters/node.js");
+  return nodeFs2;
+}
+const fileSystem = await createFileSystem();
+export {
+  BaseFileSystem,
+  BunFileSystem,
+  NodeFileSystem,
+  bunFs,
+  fileSystem,
+  nodeFs
+};

package/src/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @module @ecopages/file-system/types
+ * @description Type definitions for runtime-agnostic file system operations.
+ */
+/**
+ * Options for glob pattern matching.
+ */
+export interface GlobOptions {
+    /** Working directory for glob patterns */
+    cwd?: string;
+    /** Patterns to ignore */
+    ignore?: string[];
+}
+/**
+ * Runtime-agnostic file system interface.
+ * Implementations exist for Bun (optimized) and Node.js (fallback).
+ */
+export interface FileSystem {
+    /**
+     * Scan the file system for files matching glob patterns.
+     * @param patterns - Glob patterns to match
+     * @param options - Glob options
+     */
+    glob(patterns: string[], options?: GlobOptions): Promise<string[]>;
+    /**
+     * Read a file as a string asynchronously.
+     * @param path - Path to the file
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Read a file as a string synchronously.
+     * @param path - Path to the file
+     */
+    readFileSync(path: string): string;
+    /**
+     * Read a file as a Buffer.
+     * @param path - Path to the file
+     */
+    readFileAsBuffer(path: string): Buffer;
+    /**
+     * Write contents to a file synchronously.
+     * Creates parent directories if they don't exist.
+     * @param filepath - Path to write to
+     * @param contents - Content to write
+     */
+    write(filepath: string, contents: string | Buffer): void;
+    /**
+     * Write contents to a file asynchronously.
+     * @param filepath - Path to write to
+     * @param contents - Content to write
+     */
+    writeAsync(filepath: string, contents: string | Buffer): Promise<void>;
+    /**
+     * Ensure a directory exists, optionally cleaning it first.
+     * @param dirPath - Directory path
+     * @param forceCleanup - If true, remove existing directory first
+     */
+    ensureDir(dirPath: string, forceCleanup?: boolean): void;
+    /**
+     * Ensure a directory exists asynchronously, optionally cleaning it first.
+     * @param dirPath - Directory path
+     * @param forceCleanup - If true, remove existing directory first
+     */
+    ensureDirAsync(dirPath: string, forceCleanup?: boolean): Promise<void>;
+    /**
+     * Copy a directory recursively.
+     * @param source - Source directory
+     * @param destination - Destination directory
+     */
+    copyDir(source: string, destination: string): void;
+    /**
+     * Copy a directory recursively asynchronously.
+     * @param source - Source directory
+     * @param destination - Destination directory
+     */
+    copyDirAsync(source: string, destination: string): Promise<void>;
+    /**
+     * Remove all contents of a directory.
+     * @param path - Directory path
+     */
+    emptyDir(path: string): void;
+    /**
+     * Remove all contents of a directory asynchronously.
+     * @param path - Directory path
+     */
+    emptyDirAsync(path: string): Promise<void>;
+    /**
+     * Check if a path is a directory.
+     * @param path - Path to check
+     */
+    isDirectory(path: string): boolean;
+    /**
+     * Check if a path is a directory asynchronously.
+     * @param path - Path to check
+     */
+    isDirectoryAsync(path: string): Promise<boolean>;
+    /**
+     * Check if a file or directory exists.
+     * @param path - Path to check
+     */
+    exists(path: string): boolean;
+    /**
+     * Check if a file or directory exists asynchronously.
+     * @param path - Path to check
+     */
+    existsAsync(path: string): Promise<boolean>;
+    /**
+     * Copy a file.
+     * @param source - Source file path
+     * @param destination - Destination file path
+     */
+    copyFile(source: string, destination: string): void;
+    /**
+     * Copy a file asynchronously.
+     * @param source - Source file path
+     * @param destination - Destination file path
+     */
+    copyFileAsync(source: string, destination: string): Promise<void>;
+    /**
+     * Remove a file or directory synchronously.
+     * @param path - Path to remove
+     */
+    remove(path: string): void;
+    /**
+     * Remove a file or directory asynchronously.
+     * @param path - Path to remove
+     */
+    removeAsync(path: string): Promise<void>;
+    /**
+     * Get a hash of a file's contents.
+     * @param path - Path to the file
+     */
+    hash(path: string): string;
+    /**
+     * Gzip a single file.
+     * @param path - Path to the file
+     */
+    gzipFile(path: string): void;
+    /**
+     * Gzip all files with specified extensions in a directory.
+     * @param path - Directory path
+     * @param extensions - File extensions to gzip (without dot)
+     */
+    gzipDir(path: string, extensions: string[]): void;
+    /**
+     * Verify that a file exists, throw FileNotFoundError if not.
+     * @param path - Path to verify
+     * @throws FileNotFoundError
+     */
+    verifyFileExists(path: string): void;
+}
+/**
+ * Error thrown when a file is not found.
+ */
+export declare class FileNotFoundError extends Error {
+    code: string;
+    constructor(path: string);
+}

package/src/types.js

@@ -0,0 +1,10 @@
+class FileNotFoundError extends Error {
+  code = "ENOENT";
+  constructor(path) {
+    super(`File: ${path} not found`);
+    this.name = "FileNotFoundError";
+  }
+}
+export {
+  FileNotFoundError
+};