@fullstackunicorn/filesystem 1.0.1 → 1.0.4

package/index.dep.js

@@ -0,0 +1,4 @@
+// NODE BUILT IN
+export * as fsSync from 'fs'
+export * as fsAsync from 'fs/promises'
+export { constants } from 'fs'

package/index.js

@@ -1,65 +1,2 @@
-import * as fsSync from 'fs'
-import * as fsAsync from 'fs/promises'
-import { constants } from 'fs'
-
-export const fss = {
-    exists: (...args) => fsSync.existsSync(...args),
-    readFile: (...args) => fss.exists(...args) ? fsSync.readFileSync(...args) : null,
-    readText: (path) => fss.exists(path) ? fsSync.readFileSync(path, 'utf8') : null,
-    readJSON: (...args) => {
-        try { return fss.exists(...args) ? JSON.parse(fsSync.readFileSync(...args), 'utf8') : {} }
-        catch { return {} }
-    },
-    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 }) || []
-    ).filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => e.name),
-    isDir: (path) => {
-        try { return fsSync.statSync(path).isDirectory() }
-        catch { return false }
-    },
-    ensureDir: (path) => { if (!fss.exists(path)) fsSync.mkdirSync(path, { recursive: true }) },
-    writeText: (path, text) => fsSync.writeFileSync(path, text),
-    listFiles: (path, ext = null) => fss.readDir(path).filter(f => !ext || f.endsWith(ext)),
-    safeUnlink: (path) => { if (fss.exists(path)) fsSync.unlinkSync(path) },
-    safeRemove: (path) => { if (fss.exists(path)) fsSync.rmSync(path, { recursive: true, force: true }) },
-    copyFile: fsSync.copyFileSync,
-    remove: fsSync.rmSync,
-    writeDir: fsSync.mkdirSync,
-    unlink: fsSync.unlinkSync,
-    stat: fsSync.statSync,
-    writeFile: fsSync.writeFileSync
-}
-
-export const fsa = {
-    exists: async (path) => {
-        try { await fsAsync.access(path, constants.F_OK); return true }
-        catch { return false }
-    },
-    readFile: async (path) => await fsa.exists(path) ? await fsAsync.readFile(path) : null,
-    readText: async (path) => await fsa.exists(path) ? await fsAsync.readFile(path, 'utf8') : null,
-    readJSON: async (path) => {
-        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, 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),
-    isDir: async (path) => {
-        try { return (await fsAsync.stat(path)).isDirectory() }
-        catch { return false }
-    },
-    ensureDir: async (path) => { if (!await fsa.exists(path)) await fsAsync.mkdir(path, { recursive: true }) },
-    writeText: async (path, text) => await fsAsync.writeFile(path, text),
-    listFiles: async (path, ext = null) => (await fsa.readDir(path)).filter(f => !ext || f.endsWith(ext)),
-    safeUnlink: async (path) => { if (await fsa.exists(path)) await fsAsync.unlink(path) },
-    safeRemove: async (path) => { if (await fsa.exists(path)) await fsAsync.rm(path, { recursive: true, force: true }) },
-    copyFile: fsAsync.copyFile,
-    remove: fsAsync.rm,
-    writeDir: fsAsync.mkdir,
-    unlink: fsAsync.unlink,
-    stat: fsAsync.stat,
-    writeFile: fsAsync.writeFile
-}
+export { fsa } from '#@/modules/fsa.js'
+export { fss } from '#@/modules/fss.js'

package/modules/fsa.js

@@ -0,0 +1,35 @@
+import { fsAsync, constants } from '#@/index.dep.js'
+
+export const fsa = {
+    chmod: fsAsync.chmod,
+    exists: async (path) => {
+        try { await fsAsync.access(path, constants.F_OK); return true }
+        catch { return false }
+    },
+    readFile: async (path) => await fsa.exists(path) ? await fsAsync.readFile(path) : null,
+    readText: async (path) => await fsa.exists(path) ? await fsAsync.readFile(path, 'utf8') : null,
+    readJSON: async (path) => {
+        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, 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),
+    isDir: async (path) => {
+        try { return (await fsAsync.stat(path)).isDirectory() }
+        catch { return false }
+    },
+    ensureDir: async (path) => { if (!await fsa.exists(path)) await fsAsync.mkdir(path, { recursive: true }) },
+    writeText: async (path, text) => await fsAsync.writeFile(path, text),
+    listFiles: async (path, ext = null) => (await fsa.readDir(path)).filter(f => !ext || f.endsWith(ext)),
+    safeUnlink: async (path) => { if (await fsa.exists(path)) await fsAsync.unlink(path) },
+    safeRemove: async (path) => { if (await fsa.exists(path)) await fsAsync.rm(path, { recursive: true, force: true }) },
+    append: async (path, buffer) => await fsAsync.appendFile(path, buffer),
+    copyFile: fsAsync.copyFile,
+    remove: fsAsync.rm,
+    writeDir: fsAsync.mkdir,
+    unlink: fsAsync.unlink,
+    stat: fsAsync.stat,
+    writeFile: fsAsync.writeFile
+}

package/modules/fss.js

@@ -0,0 +1,32 @@
+import { fsSync } from '#@/index.dep.js'
+
+export const fss = {
+    exists: (...args) => fsSync.existsSync(...args),
+    readFile: (...args) => fss.exists(...args) ? fsSync.readFileSync(...args) : null,
+    readText: (path) => fss.exists(path) ? fsSync.readFileSync(path, 'utf8') : null,
+    readJSON: (...args) => {
+        try { return fss.exists(...args) ? JSON.parse(fsSync.readFileSync(...args), 'utf8') : {} }
+        catch { return {} }
+    },
+    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 }) || []
+    ).filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => e.name),
+    isDir: (path) => {
+        try { return fsSync.statSync(path).isDirectory() }
+        catch { return false }
+    },
+    ensureDir: (path) => { if (!fss.exists(path)) fsSync.mkdirSync(path, { recursive: true }) },
+    writeText: (path, text) => fsSync.writeFileSync(path, text),
+    listFiles: (path, ext = null) => fss.readDir(path).filter(f => !ext || f.endsWith(ext)),
+    safeUnlink: (path) => { if (fss.exists(path)) fsSync.unlinkSync(path) },
+    safeRemove: (path) => { if (fss.exists(path)) fsSync.rmSync(path, { recursive: true, force: true }) },
+    copyFile: fsSync.copyFileSync,
+    remove: fsSync.rmSync,
+    writeDir: fsSync.mkdirSync,
+    unlink: fsSync.unlinkSync,
+    stat: fsSync.statSync,
+    writeFile: fsSync.writeFileSync,
+    writeStream: (...args) => fsSync.createWriteStream(...args),
+}

package/package.json

@@ -1,13 +1,22 @@
 {
+    "version": "1.0.4",
     "name": "@fullstackunicorn/filesystem",
-    "author": "lucanigido[](https://fullstackunicorn.dev/author/lucanigido)",
-    "version": "1.0.1",
-    "main": "index.js",
-    "type": "module",
+    "author": "lucanigido (https://fullstackunicorn.dev/author/lucanigido)",
+    "description": "A simple sync/async file system wrapper for Node.js",
     "license": "MIT",
+    "type": "module",
     "private": false,
-    "description": "A simple sync/async file system wrapper for Node.js",
-    "readme": "README.md",
+    "readme": "package.readme.md",
+    "main": "index.js",
+    "files": [
+        "index.js",
+        "index.dep.js",
+        "modules/"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://gitlab.com/fullstackunicorn/filesystem.git"
+    },
     "keywords": [
         "filesystem",
         "fs",
@@ -15,14 +24,12 @@
         "sync",
         "async"
     ],
-    "repository": {
-        "type": "git",
-        "url": "https://gitlab.com/fullstackunicorn/filesystem.git"
+    "imports": {
+        "#@": "./",
+        "#@/*": "./*"
     },
-    "files": [
-        "index.js"
-    ],
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
+        "test": "exit 1",
+        "cli": "chmod +x ./config.cli.sh && ./config.cli.sh"
     }
-}
+}

package/readme.md

@@ -1,122 +0,0 @@
-# @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)