@coze-arch/fs-enhance

Enhanced file system utilities for improved developer experience

Project Overview

@coze-arch/fs-enhance is a lightweight TypeScript utility library that provides enhanced file system operations with modern async/await API. It offers convenient wrappers around Node.js file system operations with built-in support for JSON5 and YAML parsing, making it easier to work with configuration files and common file operations in your projects.

Features

• ✅ Async/Await Support - Modern promise-based API for all file operations
• ✅ Type Safe - Full TypeScript support with generic types for parsed content
• ✅ JSON5 Support - Read JSON files with comments and relaxed syntax
• ✅ YAML Support - Parse YAML configuration files
• ✅ File/Directory Checks - Convenient existence checks for files and directories
• ✅ Directory Creation - Recursive directory creation with existence checks
• ✅ Line Counting - Utility to count lines in text files
• ✅ Zero Dependencies - Minimal external dependencies (only json5 and yaml)

Get Started

Installation

Since this is a workspace package, install it using the workspace protocol:

# Add to your package.json dependencies
"@coze-arch/fs-enhance": "workspace:*"

# Then run rush update
rush update

Basic Usage

import {
  isFileExists,
  isDirExists,
  readJsonFile,
  readYamlFile,
  writeJsonFile,
  ensureDir,
  readFileLineCount
} from '@coze-arch/fs-enhance';

// Check if file exists
const exists = await isFileExists('./config.json');

// Read JSON with type safety
interface Config {
  name: string;
  version: string;
}
const config = await readJsonFile<Config>('./config.json');

// Create directory if it doesn't exist
await ensureDir('./dist/output');

API Reference

File Existence Checks

isFileExists(file: string): Promise<boolean>

Checks if a file exists and is actually a file (not a directory).

const exists = await isFileExists('./package.json');
if (exists) {
  console.log('Package.json found!');
}

isDirExists(file: string): Promise<boolean>

Checks if a directory exists and is actually a directory (not a file).

const exists = await isDirExists('./src');
if (exists) {
  console.log('Source directory found!');
}

File Reading Operations

readJsonFile<T>(file: string): Promise<T>

Reads and parses a JSON file with JSON5 support (allows comments and relaxed syntax). Returns a typed result.

interface PackageJson {
  name: string;
  version: string;
  dependencies?: Record<string, string>;
}

const pkg = await readJsonFile<PackageJson>('./package.json');
console.log(`Package: ${pkg.name}@${pkg.version}`);

readYamlFile<T extends object>(filePath: string): Promise<T>

Reads and parses a YAML file. Returns a typed result.

interface DockerCompose {
  version: string;
  services: Record<string, any>;
}

const compose = await readYamlFile<DockerCompose>('./docker-compose.yml');
console.log(`Docker Compose version: ${compose.version}`);

readFileLineCount(file: string): Promise<number>

Counts the number of lines in a text file.

const lineCount = await readFileLineCount('./src/index.ts');
console.log(`File has ${lineCount} lines`);

File Writing Operations

writeJsonFile(file: string, content: unknown): Promise<void>

Writes an object to a JSON file with pretty formatting (2-space indentation).

const config = {
  name: 'my-app',
  version: '1.0.0',
  features: ['json5', 'yaml']
};

await writeJsonFile('./config.json', config);

Directory Operations

ensureDir(dir: string): Promise<void>

Creates a directory and any necessary parent directories if they don't exist. Does nothing if the directory already exists.

// Creates ./dist/assets/images and any missing parent directories
await ensureDir('./dist/assets/images');

// Safe to call multiple times
await ensureDir('./dist/assets/images'); // No error, does nothing

Development

Project Structure

fs-enhance/
├── src/
│   └── index.ts          # Main implementation
├── __tests__/
│   └── file-enhance.test.ts  # Test suite
├── package.json
├── tsconfig.json
└── README.md

Running Tests

# Run tests
rush test --to @coze-arch/fs-enhance

# Run tests with coverage
rush test:cov --to @coze-arch/fs-enhance

Building

# Type check
rush build --to @coze-arch/fs-enhance

# Lint code
rush lint --to @coze-arch/fs-enhance

Dependencies

Runtime Dependencies

• json5 (^2.2.1) - JSON5 parsing support for relaxed JSON syntax
• yaml (^2.2.2) - YAML parsing and stringifying support

Development Dependencies

• @coze-arch/eslint-config - Shared ESLint configuration
• @coze-arch/ts-config - Shared TypeScript configuration
• @coze-arch/vitest-config - Shared Vitest testing configuration
• vitest - Fast unit testing framework
• @types/node - TypeScript definitions for Node.js

Error Handling

All functions handle errors gracefully:

• File existence checks (isFileExists, isDirExists) return false instead of throwing when files don't exist
• ensureDir safely handles existing directories without errors
• Parse operations will throw meaningful errors for invalid JSON/YAML syntax

TypeScript Support

This package is written in TypeScript and provides full type definitions. Generic types are supported for parsing operations:

// Strongly typed configuration
interface AppConfig {
  database: {
    host: string;
    port: number;
  };
  features: string[];
}

const config = await readJsonFile<AppConfig>('./app.config.json');
// config is fully typed as AppConfig

License

Apache-2.0

Note: This package was extracted from rush-x utilities to provide reusable file system enhancements across the monorepo.