@ecopages/file-system

Runtime file system utilities for Ecopages. The implementation is Node's node:fs and crypto on every runtime, including Bun.

Features

• Node implementation: node:fs/promises.glob(), crypto, and node:fs on every runtime.
• One interface: Call sites import fileSystem and do not choose an adapter. Tests replace it with installFileSystem and can wrap it with createRecordingFileSystem to observe every path argument.
• Recursive watch: watch() opens one native recursive watcher per minimal directory root, rather than one watcher for every subdirectory. File and missing roots share non-recursive parent watches. It indexes existing entries without emitting initial changes, coalesces native events for 50 ms, supports adding paths to a running watch, and maps canonical paths back to the requested roots.
• Type Safe: Full TypeScript support with a consistent API.

Installation

bun add @ecopages/file-system

Usage

import { fileSystem } from '@ecopages/file-system';

// Glob files
const files = await fileSystem.glob(['**/*.ts'], { cwd: './src' });

// Read files
const content = await fileSystem.readFile('file.txt');

// Hash files
const hash = fileSystem.hash('file.txt');

// Write files
fileSystem.write('output.txt', 'Hello World');

// Check existence
if (fileSystem.exists('file.txt')) {
    // ...
}

// Watch a tree, skipping dependencies
const watcher = fileSystem.watch(['./src'], {
    ignored: (path) => path.includes('node_modules'),
    onChange: ({ type, path }) => console.log(type, path),
    onError: (error) => console.error(error),
});
await watcher.ready;
await watcher.add(['./generated']);
await watcher.close();

watch() reports file changes as add, change or unlink, and directory changes as addDir or unlinkDir. Atomic replacement of an existing file is reported as one change. If a native event omits its filename, watch() reconciles the native root and can emit a rescan event for each mapped requested root; consumers should invalidate those roots once. A missing root is watched from its nearest existing parent and begins reporting once it is created. add() extends the running subscription and indexes entries already present under the new paths without reporting them. If registration fails, the added paths are rolled back so callers can retry them. Permission-denied children are skipped during indexing so accessible siblings remain watched. Symlinked roots are reported using the path passed to watch(). The optional ignored predicate runs before existing subdirectory contents are indexed, so ignored subtrees are not scanned. A path the predicate ignores when called without stats is also skipped by the native recursive watcher; on Linux, where Node opens one inotify watch per entry of a recursive root, that keeps trees such as node_modules from costing kernel watches. Return true without stats only for paths that stay ignored, because a predicate that widens later can only do so for answers given with stats. A directory removed while it is being indexed is treated as gone, not as an error.

Paths

@ecopages/file-system/path holds the path convention of Ecopages: every path uses forward slashes, and an absolute Windows path keeps its drive letter as given (D:/app/src/page.tsx); use path.isWithin rather than a string prefix to test containment. Its operations mirror node:path (join, resolve, relative, dirname, basename, extname, isAbsolute, normalize, parse, format, matchesGlob) and always return that form. Paths that fileSystem returns, from realpath, glob, readdir, readlink, mkdtemp, tempDir and watch, are in it too.

import { path } from '@ecopages/file-system/path';

const page = path.join(rootDir, 'src', 'pages', 'index.tsx');
const here = path.fromFileUrl(import.meta.url);
const module = await import(path.toFileUrl(page).href);

API

stat, lstat and readdir return plain objects (isFile, isDirectory, isSymbolicLink, plus size and mtimeMs for stats). readdir(path, { recursive: true }) also lists subdirectories, naming each entry by its path relative to path. stat, lstat, readdir, readlink, mkdtemp and rename throw Node's error unchanged, so a missing path can be detected by error.code === 'ENOENT'.