@ecopages/file-system 0.2.0-alpha.5 → 0.2.0-alpha.50

package/README.md

@@ -1,13 +1,12 @@
 # @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 native `node:fs/promises.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
 
@@ -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,6 +1,6 @@
 {
   "name": "@ecopages/file-system",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.50",
   "description": "Runtime-agnostic file system utilities for Ecopages with Bun and Node adapters",
   "keywords": [
     "ecopages",
@@ -44,9 +44,6 @@
       "default": "./src/adapters/node.js"
     }
   },
-  "dependencies": {
-    "fast-glob": "^3.3.2"
-  },
   "peerDependencies": {
     "bun": ">=1.0.0"
   },

package/src/adapters/node.d.ts

@@ -1,6 +1,6 @@
 /**
  * @module @ecopages/file-system/adapters/node
- * @description Node.js file system adapter using fast-glob, crypto, and node:fs.
+ * @description Node.js file system adapter using node:fs/promises.glob(), crypto, and node:fs.
  */
 import type { FileSystem, GlobOptions } from '../types.js';
 import { BaseFileSystem } from '../utils/common.js';

package/src/adapters/node.js

@@ -2,12 +2,22 @@ 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 fg from "fast-glob";
 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 {
@@ -39,11 +49,8 @@ class NodeFileSystem extends BaseFileSystem {
     await cpAsync(source, destination);
   }
   async glob(patterns, options = {}) {
-    return fg(patterns, {
-      cwd: options.cwd ?? process.cwd(),
-      ignore: options.ignore,
-      ...options
-    });
+    const files = await Promise.all(patterns.map((pattern) => collectGlobMatches(pattern, options)));
+    return Array.from(new Set(files.flat()));
   }
   hash(path) {
     try {

package/src/index.d.ts

@@ -4,7 +4,7 @@
  *
  * Automatically selects the optimal adapter based on runtime:
  * - **Bun**: Uses `Bun.Glob`, `Bun.hash`, `Bun.file` for maximum performance
- * - **Node.js**: Uses `fast-glob` and `crypto` for compatibility
+ * - **Node.js**: Uses native `node:fs/promises.glob()` and `crypto`
  *
  * @example
  * ```typescript

package/CHANGELOG.md

@@ -1,11 +0,0 @@
-# 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
-
-### Refactoring
-
-- `package.json` updated to add `fs` as an explicit peer dependency, reflecting the package's role in the runtime-agnostic file abstraction layer used by the Node adapter.

package/src/adapters/bun.ts

@@ -1,83 +0,0 @@
-/**
- * @module @ecopages/file-system/adapters/bun
- * @description Bun-optimized file system adapter using Bun.Glob, Bun.hash, and Bun.file.
- */
-
-import { dirname } from 'node:path';
-import type { GlobScanOptions } from 'bun';
-import type { FileSystem, GlobOptions } from '../types.ts';
-import { BaseFileSystem } from '../utils/common.ts';
-
-/**
- * Bun-optimized implementation of the FileSystem interface.
- */
-export class BunFileSystem extends BaseFileSystem implements FileSystem {
-	async existsAsync(path: string): Promise<boolean> {
-		return Bun.file(path).exists();
-	}
-
-	async readFile(path: string): Promise<string> {
-		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: string, contents: string | Buffer): Promise<void> {
-		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: string, destination: string): Promise<void> {
-		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: string[], options: GlobOptions = {}): Promise<string[]> {
-		const scanOptions: GlobScanOptions = {
-			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: string): string {
-		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}`);
-		}
-	}
-}
-
-/**
- * Singleton instance for Bun runtime.
- */
-export const bunFs: BunFileSystem = new BunFileSystem();

package/src/adapters/node.ts

@@ -1,77 +0,0 @@
-/**
- * @module @ecopages/file-system/adapters/node
- * @description Node.js file system adapter using fast-glob, crypto, and node:fs.
- */
-
-import crypto from 'node:crypto';
-import {
-	access as accessAsync,
-	cp as cpAsync,
-	readFile as readFileAsync,
-	writeFile as writeFileAsync,
-} from 'node:fs/promises';
-import { dirname } from 'node:path';
-import fg from 'fast-glob';
-import type { FileSystem, GlobOptions } from '../types.ts';
-import { BaseFileSystem } from '../utils/common.ts';
-
-/**
- * Node.js implementation of the FileSystem interface.
- */
-export class NodeFileSystem extends BaseFileSystem implements FileSystem {
-	async existsAsync(filePath: string): Promise<boolean> {
-		try {
-			await accessAsync(filePath);
-			return true;
-		} catch {
-			return false;
-		}
-	}
-
-	async readFile(path: string): Promise<string> {
-		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: string, contents: string | Buffer): Promise<void> {
-		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: string, destination: string): Promise<void> {
-		await cpAsync(source, destination);
-	}
-
-	async glob(patterns: string[], options: GlobOptions = {}): Promise<string[]> {
-		return fg(patterns, {
-			cwd: options.cwd ?? process.cwd(),
-			ignore: options.ignore,
-			...options,
-		});
-	}
-
-	hash(path: string): string {
-		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}`);
-		}
-	}
-}
-
-/**
- * Singleton instance for Node.js runtime.
- */
-export const nodeFs: NodeFileSystem = new NodeFileSystem();

package/src/index.ts

@@ -1,42 +0,0 @@
-/**
- * @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 `fast-glob` and `crypto` for compatibility
- *
- * @example
- * ```typescript
- * import { fileSystem } from '@ecopages/file-system';
- *
- * const files = await fileSystem.glob(['**\/*.ts']);
- * const content = await fileSystem.readFile('file.txt');
- */
-
-export * from './types.ts';
-export { BaseFileSystem } from './utils/common.ts';
-export { BunFileSystem, bunFs } from './adapters/bun.ts';
-export { NodeFileSystem, nodeFs } from './adapters/node.ts';
-
-import type { FileSystem } from './types.ts';
-
-/**
- * Creates a FileSystem instance based on the current runtime.
- * Uses Bun adapter if Bun is available, otherwise Node adapter.
- */
-async function createFileSystem(): Promise<FileSystem> {
-	if (typeof Bun !== 'undefined') {
-		const { bunFs } = await import('./adapters/bun.ts');
-		return bunFs;
-	}
-
-	const { nodeFs } = await import('./adapters/node.ts');
-	return nodeFs;
-}
-
-/**
- * Runtime-agnostic file system instance.
- * Automatically uses Bun or Node adapter based on environment.
- */
-export const fileSystem: FileSystem = await createFileSystem();

package/src/types.ts

@@ -1,187 +0,0 @@
-/**
- * @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 class FileNotFoundError extends Error {
-	code = 'ENOENT';
-	constructor(path: string) {
-		super(`File: ${path} not found`);
-		this.name = 'FileNotFoundError';
-	}
-}

package/src/utils/common.ts

@@ -1,223 +0,0 @@
-/**
- * @module @ecopages/file-system/utils/common
- * @description Shared utilities used by both Bun and Node adapters.
- */
-
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { cp as cpAsync, mkdir as mkdirAsync, readdir, rm as rmAsync, stat as statAsync } from 'node:fs/promises';
-import { dirname, extname, join as pathJoin } from 'node:path';
-import zlib from 'node:zlib';
-import { FileNotFoundError, type GlobOptions } from '../types.ts';
-
-/**
- * Base implementation for file system operations.
- * Subclasses override specific methods with runtime-optimized versions.
- */
-export abstract class BaseFileSystem {
-	/**
-	 * Check if a file or directory exists.
-	 */
-	exists(filePath: string): boolean {
-		return existsSync(filePath);
-	}
-
-	/**
-	 * Verify that a file exists, throw FileNotFoundError if not.
-	 */
-	verifyFileExists(filePath: string): void {
-		if (!this.exists(filePath)) {
-			throw new FileNotFoundError(filePath);
-		}
-	}
-
-	/**
-	 * Read a file as a string synchronously.
-	 */
-	readFileSync(filePath: string): string {
-		try {
-			return readFileSync(filePath, 'utf-8');
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			throw new Error(`Error reading file: ${filePath}, ${message}`, { cause: error });
-		}
-	}
-
-	/**
-	 * Read a file as a Buffer.
-	 */
-	readFileAsBuffer(filePath: string): Buffer {
-		try {
-			return readFileSync(filePath);
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			throw new Error(`Error reading file: ${filePath}, ${message}`, { cause: error });
-		}
-	}
-
-	/**
-	 * Write contents to a file synchronously.
-	 */
-	write(filepath: string, contents: string | Buffer): void {
-		try {
-			this.ensureDir(dirname(filepath));
-			writeFileSync(filepath, contents);
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			throw new Error(`Error writing file: ${filepath}. Cause: ${message}`);
-		}
-	}
-
-	/**
-	 * Ensure a directory exists.
-	 */
-	ensureDir(dirPath: string, forceCleanup?: boolean): void {
-		if (forceCleanup && existsSync(dirPath)) {
-			rmSync(dirPath, { recursive: true, force: true });
-		}
-		mkdirSync(dirPath, { recursive: true });
-	}
-
-	/**
-	 * Ensure a directory exists asynchronously.
-	 */
-	async ensureDirAsync(dirPath: string, forceCleanup?: boolean): Promise<void> {
-		if (forceCleanup && (await this.existsAsync(dirPath))) {
-			await rmAsync(dirPath, { recursive: true, force: true });
-		}
-		await mkdirAsync(dirPath, { recursive: true });
-	}
-
-	/**
-	 * Copy a directory recursively.
-	 */
-	copyDir(source: string, destination: string): void {
-		cpSync(source, destination, { recursive: true });
-	}
-
-	/**
-	 * Copy a directory recursively asynchronously.
-	 */
-	async copyDirAsync(source: string, destination: string): Promise<void> {
-		await cpAsync(source, destination, { recursive: true });
-	}
-
-	/**
-	 * Copy a file.
-	 */
-	copyFile(source: string, destination: string): void {
-		cpSync(source, destination);
-	}
-
-	/**
-	 * Remove all contents of a directory.
-	 */
-	emptyDir(dirPath: string): void {
-		if (!this.isDirectory(dirPath)) {
-			return;
-		}
-		const entries = readdirSync(dirPath);
-		for (const entry of entries) {
-			const fullPath = pathJoin(dirPath, entry);
-			rmSync(fullPath, { recursive: true, force: true });
-		}
-	}
-
-	/**
-	 * Remove a directory's contents asynchronously.
-	 */
-	async emptyDirAsync(dirPath: string): Promise<void> {
-		if (!(await this.isDirectoryAsync(dirPath))) {
-			return;
-		}
-		const entries = await readdir(dirPath);
-		await Promise.all(entries.map((entry) => rmAsync(pathJoin(dirPath, entry), { recursive: true, force: true })));
-	}
-
-	/**
-	 * Remove a file or directory synchronously.
-	 */
-	remove(filePath: string): void {
-		rmSync(filePath, { recursive: true, force: true });
-	}
-
-	/**
-	 * Remove a file or directory asynchronously.
-	 */
-	async removeAsync(filePath: string): Promise<void> {
-		await rmAsync(filePath, { recursive: true, force: true });
-	}
-
-	/**
-	 * Check if a path is a directory.
-	 */
-	isDirectory(filePath: string): boolean {
-		return existsSync(filePath) && statSync(filePath).isDirectory();
-	}
-
-	/**
-	 * Check if a path is a directory asynchronously.
-	 */
-	async isDirectoryAsync(filePath: string): Promise<boolean> {
-		try {
-			const stats = await statAsync(filePath);
-			return stats.isDirectory();
-		} catch {
-			return false;
-		}
-	}
-
-	/**
-	 * Gzip a single file.
-	 */
-	gzipFile(filePath: string): void {
-		const data = this.readFileAsBuffer(filePath);
-		const compressedData = zlib.gzipSync(Buffer.from(data));
-		const gzipFile = `${filePath}.gz`;
-		writeFileSync(gzipFile, compressedData);
-	}
-
-	/**
-	 * Gzip all files with specified extensions in a directory.
-	 */
-	gzipDir(dirPath: string, extensionsToGzip: string[]): void {
-		const entries = readdirSync(dirPath, { recursive: true, withFileTypes: true });
-		for (const entry of entries) {
-			if (entry.isFile()) {
-				const ext = extname(entry.name).slice(1);
-				if (extensionsToGzip.includes(ext)) {
-					this.gzipFile(pathJoin(entry.parentPath, entry.name));
-				}
-			}
-		}
-	}
-
-	/**
-	 * Glob patterns - must be implemented by runtime-specific adapters.
-	 */
-	abstract glob(patterns: string[], options?: GlobOptions): Promise<string[]>;
-
-	/**
-	 * Read file async - must be implemented by runtime-specific adapters.
-	 */
-	abstract readFile(path: string): Promise<string>;
-
-	/**
-	 * Write file async - must be implemented by runtime-specific adapters.
-	 */
-	abstract writeAsync(filepath: string, contents: string | Buffer): Promise<void>;
-
-	/**
-	 * Check if a file exists asynchronously - must be implemented by runtime-specific adapters.
-	 */
-	abstract existsAsync(filePath: string): Promise<boolean>;
-
-	/**
-	 * Copy a file asynchronously - must be implemented by runtime-specific adapters.
-	 */
-	abstract copyFileAsync(source: string, destination: string): Promise<void>;
-
-	/**
-	 * Hash file - must be implemented by runtime-specific adapters.
-	 */
-	abstract hash(path: string): string;
-}