Package Exports

@fullstackunicorn/filesystem
@fullstackunicorn/filesystem/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@fullstackunicorn/filesystem) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@fullstackunicorn/filesystem

A lightweight, zero-dependency wrapper for Node.js's built-in fs module. It provides safe, crash-proof sync (fss) and async (fsa) APIs for common file system tasks. The goal is simplicity: one-liners that handle edge cases like non-existent paths or files, ensuring your code doesn't throw unexpected errors.

Perfect for scripts, CLIs, or apps where you need reliable file I/O without boilerplate checks.

Features

Safe by Default: Built-in existence checks prevent crashes (e.g., readJSON returns {} if file missing or invalid).
One-Line Operations: Write JSON to a new dir? fss.writeJSON('./new/dir/config.json', data);—it auto-creates dirs.
Sync & Async: Choose blocking (fss) or promise-based (fsa) methods.
No Dependencies: Pure Node.js (requires Node 14+ for rm support).
Clear API: Consistent methods like readJSON, writeJSON, safeUnlink.

Installation

npm install @fullstackunicorn/filesystem

yarn add @fullstackunicorn/filesystem

Quick Start

import { fss, fsa } from '@fullstackunicorn/filesystem';

// Sync: Safe JSON read (returns {} if missing)
const config = fss.readJSON('./config.json');
console.log(config);

// Sync: Write JSON (auto-creates dir if needed)
fss.writeJSON('./logs/app.json', { message: 'Hello, safe FS!' });

// Async: List files with extension filter
const jsFiles = await fsa.listFiles('./src', '.js');
console.log(jsFiles);

// Safe removal (no error if missing)
fss.safeRemove('./temp/dir');

API Reference

Sync API (`fss`)

All methods are synchronous and return fallbacks on errors (e.g., null, [], {}).

Method	Description	Parameters	Returns
`exists(path)`	Checks if path exists.	`path: string`	`boolean`
`readFile(path)`	Reads file as Buffer.	`path: string`	`Buffer \| null`
`readText(path)`	Reads file as UTF-8 string.	`path: string`	`string \| null`
`readJSON(path)`	Reads and parses JSON.	`path: string`	`object` (empty `{}` on error)
`writeJSON(path, json)`	Writes pretty JSON (creates dir if needed).	`path: string`, `json: object`	`void`
`readDir(path, opts?)`	Lists dir contents.	`path: string`, `opts?: object`	`string[]`
`readDirVisible(path)`	Lists visible subdirs (no `.` hidden).	`path: string`	`string[]`
`isDir(path)`	Checks if path is directory.	`path: string`	`boolean`
`ensureDir(path)`	Creates dir recursively if missing.	`path: string`	`void`
`writeText(path, text)`	Writes UTF-8 text.	`path: string`, `text: string`	`void`
`listFiles(path, ext?)`	Lists files (optional extension filter).	`path: string`, `ext?: string`	`string[]`
`safeUnlink(path)`	Removes file (no-op if missing).	`path: string`	`void`
`safeRemove(path)`	Removes file/dir recursively (no-op if missing).	`path: string`	`void`
`copyFile(src, dest)`	Copies file.	`src: string`, `dest: string`	`void`

Async API (`fsa`)

Promise-based equivalents of fss methods. Use await for results.

Method	Description	Parameters	Returns
`exists(path)`	Checks if path exists.	`path: string`	`Promise<boolean>`
`readFile(path)`	Reads file as Buffer.	`path: string`	`Promise<Buffer \| null>`
`readText(path)`	Reads file as UTF-8 string.	`path: string`	`Promise<string \| null>`
`readJSON(path)`	Reads and parses JSON.	`path: string`	`Promise<object>` (empty `{}` on error)
`writeJSON(path, json)`	Writes pretty JSON (creates dir if needed).	`path: string`, `json: object`	`Promise<void>`
`readDir(path, opts?)`	Lists dir contents.	`path: string`, `opts?: object`	`Promise<string[]>`
`readDirVisible(path)`	Lists visible subdirs (no `.` hidden).	`path: string`	`Promise<string[]>`
`isDir(path)`	Checks if path is directory.	`path: string`	`Promise<boolean>`
`ensureDir(path)`	Creates dir recursively if missing.	`path: string`	`Promise<void>`
`writeText(path, text)`	Writes UTF-8 text.	`path: string`, `text: string`	`Promise<void>`
`listFiles(path, ext?)`	Lists files (optional extension filter).	`path: string`, `ext?: string`	`Promise<string[]>`
`safeUnlink(path)`	Removes file (no-op if missing).	`path: string`	`Promise<void>`
`safeRemove(path)`	Removes file/dir recursively (no-op if missing).	`path: string`	`Promise<void>`
`copyFile(src, dest)`	Copies file.	`src: string`, `dest: string`	`Promise<void>`

Notes:

JSON methods use 4-space pretty-printing.
readDir supports { withFileTypes: true } for Dirent objects.
Errors are swallowed where possible (e.g., invalid JSON → {}); use try-catch for strict error handling.

Examples

Safe Config Management

import { fss } from '@fullstackunicorn/filesystem';

function loadOrCreateConfig() {
  let config = fss.readJSON('./config.json');
  if (Object.keys(config).length === 0) {
    config = { theme: 'dark', lang: 'en' };
    fss.writeJSON('./config.json', config);
  }
  return config;
}

Async Dir Cleanup

import { fsa } from '@fullstackunicorn/filesystem';

async function cleanupTemp() {
  await fsa.ensureDir('./temp');
  // ... write temp files ...
  await fsa.safeRemove('./temp');  // Safe even if empty/missing
}

Contributing

Fork the repo, make changes, and submit a PR. Tests welcome!