@hyperfrontend/project-scope/core/fsfs
Safe, typed wrappers around Node.js synchronous filesystem APIs with structured error handling.
Covers four areas: reading (readFileContent, readFileBuffer, readJsonFile, plus *IfExists variants), writing (writeFileContent, writeJsonFile, ensureDir — automatically creates parent directories), directory operations (readDirectory, readDirectoryRecursive, createDirectory, removeDirectory), and stat/traversal helpers (exists, isFile, isDirectory, isSymlink, findUpwardWhere, locateByMarkers, traverseUpward).
All operations surface failures via createFileSystemError with codes (FS_NOT_FOUND, FS_READ_ERROR, FS_WRITE_ERROR, FS_PARSE_ERROR) carrying contextual paths.
API Reference
ƒ Functions
Create a directory, optionally creating parent directories.
Parameters
Example
Creating directories
// Create nested directories
createDirectory('./output/reports/2024')
// Create single directory without parents
createDirectory('./logs', { recursive: false })§function
createFileSystemError(message: string, code: FileSystemErrorCode, context: FileSystemErrorContext): Error
Create a file system error with code and context.
Parameters
Returns
ErrorA configured Error object with code and context properties
Example
Creating a file system error
throw createFileSystemError(
'Cannot read file',
'FS_READ_ERROR',
{ path: './missing.txt', operation: 'read' }
)Ensure directory exists, create recursively if not.
Parameters
| Name | Type | Description |
|---|---|---|
§dirPath | string | Directory path to ensure exists |
Example
Ensuring directory exists
ensureDir('./output/reports')
// Directory now exists (created if missing)Check if path exists.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to check |
Returns
booleanTrue if path exists
Example
Checking if path exists
if (exists('./config.json')) {
const config = readJsonFile('./config.json')
}Find directory where predicate returns true, starting from given path.
Parameters
Returns
stringMatching directory path or null
Example
Finding directory with specific config
// Find directory with a specific config
const configDir = findUpwardWhere('./deep/nested/path', (dir) =>
existsSync(join(dir, '.eslintrc.js'))
)Get file stats with error handling.
Parameters
Returns
FileStatsFile stats or null if path doesn't exist
Example
Getting file statistics
const stats = getFileStat('./package.json')
if (stats) {
console.log(`Size: ${stats.size} bytes`)
console.log(`Modified: ${stats.modified}`)
}Check if path is a directory.
Parameters
| Name | Type | Description |
|---|---|---|
§dirPath | string | Path to check |
Returns
booleanTrue if path is a directory
Example
Checking if path is a directory
if (isDirectory('./src')) {
// Path exists and is a directory
}Check if path is a file.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to check |
Returns
booleanTrue if path is a file
Example
Checking if path is a file
if (isFile('./package.json')) {
// Path exists and is a regular file
}Check if path is a symbolic link.
Parameters
| Name | Type | Description |
|---|---|---|
§linkPath | string | Path to check |
Returns
booleanTrue if path is a symlink
Example
Checking if path is a symlink
if (isSymlink('./node_modules/.bin/tsc')) {
// Path is a symbolic link
}Find directory containing any of the specified marker files.
Parameters
Returns
stringFirst directory containing any marker, or null
Example
Finding project root by marker files
// Find project root by looking for common marker files
const projectRoot = locateByMarkers('./src/components', [
'package.json',
'nx.json',
'tsconfig.base.json'
])
// => '/workspace/my-project'List immediate contents of a directory.
Parameters
| Name | Type | Description |
|---|---|---|
§dirPath | string | Absolute or relative path to the directory |
Returns
DirectoryEntry[]Array of entries with metadata for each file/directory
Example
Listing directory contents
import { readDirectory } from '@hyperfrontend/project-scope'
const entries = readDirectory('./src')
for (const entry of entries) {
console.log(entry.name, entry.isFile ? 'file' : 'directory')
}List directory contents recursively with depth tracking.
Parameters
Returns
DirectoryEntry[]Flat array of all entries found during traversal
Example
Recursive directory listing with options
import { readDirectoryRecursive } from '@hyperfrontend/project-scope'
// List all files up to 3 levels deep
const entries = readDirectoryRecursive('./src', { maxDepth: 3 })
// Include hidden files
const allEntries = readDirectoryRecursive('./project', { includeHidden: true })Read file contents as Buffer.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to file |
Returns
BufferFile contents as Buffer
Example
Reading file as buffer
const buffer = readFileBuffer('./image.png')
console.log(buffer.length) // File size in bytesRead file contents as string.
Parameters
Returns
stringFile contents as string
Example
Reading file contents
import { readFileContent } from '@hyperfrontend/project-scope'
const content = readFileContent('./package.json')
console.log(content) // JSON stringRead file if exists, return null otherwise.
Parameters
Returns
stringFile contents or null if file doesn't exist
Example
Reading file if it exists
const content = readFileIfExists('./optional-config.json')
if (content) {
// File existed, use content
}Read and parse JSON file.
Parameters
Returns
TParsed JSON object
Example
Reading JSON file
import { readJsonFile } from '@hyperfrontend/project-scope'
// Read with type inference
interface Config { port: number }
const config = readJsonFile<Config>('./config.json')
// Read with default fallback
const settings = readJsonFile('./settings.json', { default: {} })Read and parse JSON file if exists, return null otherwise.
Parameters
| Name | Type | Description |
|---|---|---|
§filePath | string | Path to JSON file |
Returns
TParsed JSON object or null if file doesn't exist or is invalid
Example
Reading JSON file if it exists
interface UserSettings { theme: string }
const settings = readJsonFileIfExists<UserSettings>('./user-settings.json')
const theme = settings?.theme ?? 'default'Delete a directory from the filesystem.
Parameters
Example
Removing directories
// Remove directory and all contents
removeDirectory('./temp', { recursive: true })
// Safe removal (no error if missing)
removeDirectory('./cache', { recursive: true, force: true })Generic upward directory traversal. Name avoids similarity to fs.readdir/fs.readdirSync.
Parameters
Returns
stringFirst matching directory or null
Example
Finding directory containing README
// Find first directory containing a README
const readmeDir = traverseUpward('./src/utils', (dir) =>
existsSync(join(dir, 'README.md'))
)
// => '/project' or nullWrite Buffer to file. Creates parent directories if needed.
Parameters
Example
Writing binary buffer to file
const imageBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47])
writeFileBuffer('./output/image.png', imageBuffer)Write string content to file. Creates parent directories if needed.
Parameters
Example
Writing text content to file
import { writeFileContent } from '@hyperfrontend/project-scope'
// Write a simple text file
writeFileContent('./output/data.txt', 'Hello, World!')
// Write with custom encoding
writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })Write JSON data to file with formatting. Creates parent directories if needed.
Parameters
Example
Writing JSON data to file
import { writeJsonFile } from '@hyperfrontend/project-scope'
// Write object to JSON file
writeJsonFile('./config.json', { port: 3000, debug: true })
// Write with custom indentation
writeJsonFile('./config.json', data, { indent: 4 })◈ Interfaces
Entry metadata for a directory listing.
File statistics.
File system error with code and context.
Options for reading a JSON file.
Properties
Options for recursive directory listing.
Options for write operations.
◆ Types
Error codes for file system operations.
type FileSystemErrorCode = "FS_NOT_FOUND" | "FS_READ_ERROR" | "FS_WRITE_ERROR" | "FS_PARSE_ERROR" | "FS_NOT_A_DIRECTORY"