@cutticat/fs-extras

A filesystem utilities library.

Overview
Installation
Quick start
API
Documentation
Requirements

Overview

The library provides functions for access checks, JSON read/write, directory operations, and file tree search. It uses types from @cutticat/types.

Installation

pnpm i @cutticat/fs-extras

Quick start

import {
  canAccess,
  isJsonFile,
  ensureDirectoryExists,
  withTempDir,
  createTestTree,
  readJsonFile,
  writeJsonFile,
  findFiles,
  findFilesByNames,
  findFilesByExtensions,
} from "@cutticat/fs-extras"

// Access check
await canAccess("/path/to/file") // true/false

// JSON
const data = await readJsonFile("config.json")
await writeJsonFile("output.json", { foo: 42 })

// Directories
await ensureDirectoryExists("./logs")
await withTempDir(async tmpPath => {
  // work in a temporary directory
})

// Tree search (returns an array of paths)
const pkgPaths = await findFilesByNames(process.cwd(), ["package.json"], { type: "up" })
const tsFiles = await findFilesByExtensions("./src", [".ts"], { type: "down" })
// Limit the number of results
const firstFive = await findFilesByExtensions("./src", [".ts"], { type: "down", limit: 5 })

API

Checks

canAccess(path, flags?) — checks access to a file/directory
isJsonFile(entry) — checks whether a path/Dirent is a JSON file by extension

Dirs

ensureDirectoryExists(dir) — creates a directory recursively
withTempDir(fn, name?) — temporary directory with auto-cleanup
createTestTree(basePath, structure, encoding?) — creates a tree of files/folders

Reading / Writing

readJsonFile(path, options?) — reads and parses JSON
writeJsonFile(path, value, options?) — writes JSON

Search

Search functions return an array of paths to matched files (they do not stop after the first match). The limit option caps the number of results (default: Infinity).

findFiles(dirPath, find, options?) — generic search (current/up/down)
findFilesByNames(dirPath, names, options?) — search by name list
findFilesByRegExps(dirPath, regExps, options?) — search by regex
findFilesByExtensions(dirPath, extensions, options?) — search by extensions
findFilesReadingDirs(dirPath, matches, options?) — search via Dirent callback

Types

TreeStructure, ReadonlyTreeStructure — tree structure for createTestTree
ParseJson, StringifyJson — types for custom JSON parse/stringify
SearchType, DownSearchType, FindFilesInDir, StopDirsTraversal, FindFilesOptions — search options

Documentation

Further documentation:

Full API documentation is available in JSDoc comments. Use your IDE autocomplete to browse it.

Requirements

Node.js >= 22.0.0
pnpm >= 10.17.0
TypeScript >= 5.9.0