@fullstackunicorn/filesystem 1.0.0 → 1.0.1

package/index.js

@@ -10,7 +10,7 @@ export const fss = {
         try { return fss.exists(...args) ? JSON.parse(fsSync.readFileSync(...args), 'utf8') : {} }
         catch { return {} }
     },
-    writeJSON: (path, json) => fsSync.writeFileSync(path, JSON.stringify(json, null, 2)),
+    writeJSON: (path, json) => fsSync.writeFileSync(path, JSON.stringify(json, null, 4)),
     readDir: (...args) => fss.exists(...args) ? fsSync.readdirSync(...args) : [],
     readDirVisible: (path) => (
         fss.readDir(path, { withFileTypes: true }) || []
@@ -43,7 +43,7 @@ export const fsa = {
         try { return await fsa.exists(path) ? JSON.parse(await fsAsync.readFile(path, 'utf8')) : {} }
         catch { return {} }
     },
-    writeJSON: async (path, json) => await fsAsync.writeFile(path, JSON.stringify(json, null, 2)),
+    writeJSON: async (path, json) => await fsAsync.writeFile(path, JSON.stringify(json, null, 4)),
     readDir: async (path, opts) => await fsa.exists(path) ? await fsAsync.readdir(path, opts) : [],
     readDirVisible: async (path) => (await fsa.readDir(path, { withFileTypes: true }))
         .filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => e.name),

package/package.json

@@ -1,13 +1,20 @@
 {
     "name": "@fullstackunicorn/filesystem",
     "author": "lucanigido[](https://fullstackunicorn.dev/author/lucanigido)",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "main": "index.js",
     "type": "module",
     "license": "MIT",
     "private": false,
     "description": "A simple sync/async file system wrapper for Node.js",
-    "keywords": ["filesystem", "fs", "node", "sync", "async"],
+    "readme": "README.md",
+    "keywords": [
+        "filesystem",
+        "fs",
+        "node",
+        "sync",
+        "async"
+    ],
     "repository": {
         "type": "git",
         "url": "https://gitlab.com/fullstackunicorn/filesystem.git"

package/readme.md

@@ -0,0 +1,122 @@
+# @fullstackunicorn/filesystem
+
+[![NPM version](https://badge.fury.io/js/%40fullstackunicorn%2Ffilesystem.svg)](https://www.npmjs.com/package/@fullstackunicorn/filesystem)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-v20-green.svg)](https://nodejs.org/)
+
+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
+```bash
+npm install @fullstackunicorn/filesystem
+```
+```bash
+yarn add @fullstackunicorn/filesystem
+```
+
+## Quick Start
+```javascript
+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
+```javascript
+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
+```javascript
+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!
+
+## License
+MIT © [fullstackunicorn.dev/author/lucanigido](https://fullstackunicorn.dev/author/lucanigido)