@reliverse/relifso 1.3.1 → 1.4.1

package/LICENSES

@@ -0,0 +1,16 @@
+LICENSES
+
+---
+
+MIT License
+
+Copyright (c) Nazar Kornienko (blefnk), Reliverse
+
+See LICENSE file for full license text.
+
+---
+
+NOTICES
+
+Some parts of this project are based on and significantly adapt:
+- https://github.com/josdejong/jsonrepair/tree/acab2a4 – ISC © Jos de Jong (josdejong)

package/README.md

@@ -1,26 +1,27 @@
-# Relifso • Node.js Filesystem Toolkit Library
-
-> @reliverse/relifso is a modern filesystem toolkit for builders. drop-in replacement for `node:fs` and `fs-extra` — powered by native promises, built with es modules, and packed with dx-focused utilities.
+# Relifso • Bun & Node.js Filesystem Toolkit Library
 
 [sponsor](https://github.com/sponsors/blefnk) — [discord](https://discord.gg/Pb8uKbwpsJ) — [npm](https://npmjs.com/package/@reliverse/relifso) — [github](https://github.com/reliverse/relifso)
 
+> @reliverse/relifso is a modern node and bun filesystem toolkit. drop-in replacement for `node:fs` and `fs-extra` — powered by native promises, built with es modules, and packed with dx-focused and bun-aware utilities.
+
 ## Features
 
+- 🔥 Both Node.js and Bun-specific filesystem features are exposed via `fs.*`
 - 🪄 Everything you love from `fs-extra` — now simpler, cleaner, and more beginner-friendly
 - ⚙️ Drop-in replacement for `node:fs` — with native `Promise`, `async/await`, and sync variants
-- 🤝 Forget about `try-catch` for common errors like “file not found” — relifso does it under the hood
+- 🤝 Forget about `try-catch` for common errors like "file not found" — relifso does it under the hood
 - 🧯 Gracefully handles errors like `EMFILE` (reading or writing a lot of files at once) and other edge cases
 - 📚 Consistent error-first behavior — even for legacy APIs like `fs.exists()`
 - 📦 First-class ESM and full TypeScript support — no config hacks required
-- 🧼 Zero bloat — small size ([3.9 kB](https://bundlephobia.com/package/@reliverse/relifso@latest)), zero deps, modern code, no monkey-patching
+- 🧼 Zero bloat — small size ([6 kB](https://bundlephobia.com/package/@reliverse/relifso@latest)), zero deps, modern code, no monkey-patching
 - 🎯 Supports all Node.js v16+ features — optimized for Node.js v22+
-- 🧪 **Soon**: Ready for upcoming Node.js v22+ experimental features
-- ✌️ **Soon**: Bun v1.2+ ready — ships with Bun-aware enhancements out of the box
-- 🔥 **Soon**: Bun-specific features are exposed via `fs.*` when running on Bun
+- 🧪 Soon: Ready for upcoming Node.js v22+ experimental features
+- ✌️ Bun v1.2+ ready — ships with Bun-aware enhancements out of the box
+- 🐦‍🔥 Finally! Your `fs.*` usage is now can correctly read/write JSON/JSONC!  
 
 ## Heads Up
 
-- **Most of the things** mentioned in this doc **aren’t implemented yet** — they’re part of the vision for ~`v1.3.0`.
+- **Most of the things** mentioned in this doc **aren't implemented yet** — they're part of the vision for ~`v1.5.0`.
 - Got thoughts? Ideas? Send your feedback in [Discord](https://discord.gg/Pb8uKbwpsJ) or use [GitHub Issues](https://github.com/reliverse/relifso/issues).
 - Your feedback means the world and helps shape where this project goes next. Thank you!
 
@@ -42,12 +43,49 @@ bun rm @types/fs-extra
 # bun dler relifso fs-extra to relifso
 ```
 
-**Coming soon**:
-
-```bash
-bun add -D @reliverse/dler
-bun dler relifso init ...
-```
+### Core Features
+
+- **File Operations**
+  - Read/write files with various encodings
+  - Copy/move files and directories
+  - Create/remove files and directories
+  - File existence checks
+  - File stats and metadata access
+
+- **Directory Operations**
+  - Create nested directories
+  - Empty directories
+  - Directory traversal with `dive`
+  - Directory existence checks
+
+- **JSON Operations**
+  - Read/write JSON files with validation
+  - JSON repair and validation utilities
+  - JSON streaming support
+  - JSONC (JSON with Comments) support
+
+- **Bun Optimizations**
+  - Automatic runtime detection
+  - Optimized file operations using Bun APIs
+  - Fast file stats and metadata access
+  - Graceful fallbacks to Node.js APIs
+
+- **Utility Functions**
+  - File type detection
+  - Hidden file attribute handling
+  - Directory emptiness checks
+  - File size and last modified time access
+
+### Error Handling
+
+- Graceful handling of common filesystem errors
+- Consistent error types and messages
+- Automatic error recovery where possible
+- Detailed error information for debugging
+- Runtime detection errors
+- File operation failures
+- All Bun-specific operations include proper error handling
+- Automatic fallback from Bun to Node.js APIs when needed
 
 ## Usage
 
@@ -65,9 +103,9 @@ if (await pathExists("dist/index.ts")) {
 }
 ```
 
-- ✨ Everything’s bundled — modern, async, and type-safe.
+- ✨ Everything's bundled — modern, async, and type-safe.
 - 🧼 No more boilerplate like `promisify(fs.removeSync)` or using `mkdirp`, `ncp`, or `rimraf`.
-- 🌱 No more weird `try/catch` for common errors like “file not found.”  
+- 🌱 No more weird `try/catch` for common errors like "file not found."  
 - ✌️ Just clean, predictable APIs built for 2025 and beyond.
 
 ## Example
@@ -118,7 +156,7 @@ All async methods return a `Promise` if no callback is passed.
 - Compatible with Node.js 16+, best with 22+
 - Async methods are built from the sync versions — no wrappers, no bloat
 
-## What’s Inside?
+## What's Inside?
 
 - All async methods follow the `Promise` pattern by default.
 - All sync methods are safe and throw errors when needed.
@@ -181,7 +219,7 @@ All async methods return a `Promise` if no callback is passed.
 - [isSymlink](https://uwx-node-modules.github.io/fsxt/functions/isSymlink.html)
 - [~~lchmod~~](https://uwx-node-modules.github.io/fsxt/functions/lchmod.html)
 - [lchown](https://uwx-node-modules.github.io/fsxt/functions/lchown.html)
-- [link](https://uwx-node-modules.github.io/fsxt/functions/link.html)
+- [`link`](https://uwx-node-modules.github.io/fsxt/functions/link.html)
 - [lstat](https://uwx-node-modules.github.io/fsxt/functions/lstat.html)
 - [lutimes](https://uwx-node-modules.github.io/fsxt/functions/lutimes.html)
 - [mapChildren](https://uwx-node-modules.github.io/fsxt/functions/mapChildren.html)
@@ -270,6 +308,53 @@ All async methods return a `Promise` if no callback is passed.
 - [utimesSync](https://uwx-node-modules.github.io/fsxt/functions/utimesSync.html)
 - [writevSync](https://uwx-node-modules.github.io/fsxt/functions/writevSync.html)
 
+## Bun Integration
+
+Relifso provides first-class support for Bun with automatic fallbacks to Node.js APIs. Here's how it works:
+
+### Automatic Runtime Detection
+
+```ts
+import { isBun } from "@reliverse/relifso";
+
+if (isBun) {
+  console.log("Running in Bun!");
+} else {
+  console.log("Running in Node.js");
+}
+```
+
+### Optimized File Operations
+
+When running in Bun, relifso automatically uses Bun's optimized file system APIs:
+
+- `Bun.file()` for file operations
+- Native file existence checks
+- Optimized file size and type detection
+- Fast last modified time access
+
+### Graceful Fallbacks
+
+All Bun-specific operations include automatic fallbacks to Node.js APIs:
+
+```ts
+import { getStats } from "@reliverse/relifso";
+
+// In Bun: Uses Bun.file() for faster stats
+// In Node.js: Falls back to fs.stat()
+const stats = await getStats("file.txt");
+```
+
+### Available Bun-Specific Utilities
+
+- `getFile(path)` - Get a Bun file reference
+- `exists(path)` - Check file existence using Bun's API
+- `size(path)` - Get file size using Bun's API
+- `type(path)` - Get file MIME type using Bun's API
+- `lastModified(path)` - Get file last modified time
+- `getStats(path)` - Get file stats with Bun optimization
+- `getStatsSync(path)` - Synchronous version of getStats
+
 ## Contributing
 
 ...
@@ -282,10 +367,11 @@ All async methods return a `Promise` if no callback is passed.
 - [ ] Pass all `fs-extra` tests with Bun (+ fix & improve them).
 - [ ] Convert all jsdoc comments to TypeScript types.
 - [ ] Fully improve all `fs-extra` codebase files.
+- [ ] In [docs.reliverse.org](https://docs.reliverse.org) implement feature and performance comparison table with `fs-extra`.
 
 ## Shoutouts
 
-Relifso wouldn’t be so cool without these gems:
+Relifso wouldn't be so cool without these gems:
 
 - [`node:fs`](https://nodejs.org/api/fs.html)+[`node:path`](https://nodejs.org/api/path.html) — origins
 - [`fs-extra`](https://github.com/jprichardson/node-fs-extra) — classic, reliable

package/bin/impl/bun.d.ts

@@ -0,0 +1,11 @@
+export declare const isBun: string | false;
+/**
+ * Get a file reference with validation and error handling
+ * Uses Bun's optimized API when available, throws error otherwise
+ */
+export declare function getFileBun(path: string): Bun.BunFile;
+/**
+ * Get file type
+ * Uses Bun's optimized API when available, throws error otherwise
+ */
+export declare function getFileTypeBun(path: string): Promise<string>;

package/bin/impl/bun.js

@@ -0,0 +1,23 @@
+import { logInternal } from "../utils/log.js";
+export const isBun = typeof process !== "undefined" && process.versions.bun;
+export function getFileBun(path) {
+  if (!isBun) {
+    throw new Error("Bun runtime not detected");
+  }
+  try {
+    return Bun.file(path);
+  } catch (error) {
+    throw error;
+  }
+}
+export async function getFileTypeBun(path) {
+  if (!isBun) {
+    throw new Error("Bun runtime not detected");
+  }
+  try {
+    const file = Bun.file(path);
+    return file.type;
+  } catch (error) {
+    throw error;
+  }
+}

package/bin/impl/{node/copy.d.ts → copy.d.ts}

@@ -1,12 +1,24 @@
 export interface CopyOptions {
+    /** Whether to overwrite existing files. Default: true */
+    force?: boolean;
+    /** Whether to overwrite existing files. Alias for force. Default: true */
     overwrite?: boolean;
     /** @deprecated Use `overwrite`. */
     clobber?: boolean;
+    /** Whether to preserve timestamps. Default: false */
     preserveTimestamps?: boolean;
-    /** @deprecated Not used. */
-    errorOnExist?: boolean;
-    /** @deprecated Not used. */
+    /** Whether to recursively copy directories. Default: false */
+    recursive?: boolean;
+    /** Whether to dereference symlinks. Default: false */
     dereference?: boolean;
+    /** Whether to throw an error if the destination exists. Default: false */
+    errorOnExist?: boolean;
+    /** Whether to ensure source exists before copying (default: true) */
+    ensureSource?: boolean;
+    /** Whether to ensure destination directory exists (default: true) */
+    ensureDest?: boolean;
+    /** Whether to verify operation success (default: true) */
+    verify?: boolean;
     /** @deprecated Not used. */
     filter?: (src: string, dest: string) => boolean;
 }

package/bin/impl/copy.js

@@ -0,0 +1,229 @@
+import {
+  copyFileSync,
+  statSync,
+  constants as fsConstants,
+  readdirSync,
+  rmSync,
+  lstatSync,
+  readlinkSync,
+  symlinkSync
+} from "node:fs";
+import {
+  stat as statAsync,
+  copyFile as copyFileAsync,
+  constants as fsConstantsAsync,
+  readdir,
+  rm,
+  lstat,
+  readlink,
+  symlink
+} from "node:fs/promises";
+import { dirname, join as joinPath } from "node:path";
+import { mkdirsSync } from "./mkdirs.js";
+import { mkdirs } from "./mkdirs.js";
+import { logInternal } from "../utils/log.js";
+import { isBun, getFileBun } from "./bun.js";
+import { pathExists, pathExistsSync } from "./path-exists.js";
+import { getStats, getStatsSync } from "./stats.js";
+export function copySync(src, dest, options = {}) {
+  const {
+    overwrite = options.clobber ?? true,
+    force = true,
+    recursive = false,
+    dereference = false,
+    errorOnExist = false,
+    ensureSource = true,
+    ensureDest = true,
+    verify = true
+  } = options;
+  if (ensureSource && !pathExistsSync(src)) {
+    throw new Error(`Source ${src} does not exist.`);
+  }
+  if (isBun && !dereference) {
+    try {
+      const srcStat2 = getStatsSync(src);
+      if (!srcStat2.isDirectory()) {
+        try {
+          const destStat = getStatsSync(dest);
+          if (destStat) {
+            if (errorOnExist) {
+              throw new Error(`Destination ${dest} already exists.`);
+            }
+            if (!force && !overwrite) {
+              throw new Error(`Destination ${dest} already exists and overwrite is false.`);
+            }
+            if (force || overwrite) {
+              rmSync(dest, { force: true });
+            }
+          }
+        } catch (_error) {
+        }
+        if (ensureDest) {
+          const destDir = dirname(dest);
+          mkdirsSync(destDir);
+        }
+        try {
+          copyFileSync(src, dest, fsConstants.COPYFILE_FICLONE);
+          if (verify && !pathExistsSync(dest)) {
+            throw new Error(`Copy operation failed: destination ${dest} does not exist after copy`);
+          }
+          return;
+        } catch (error) {
+        }
+      }
+    } catch (error) {
+    }
+  }
+  const srcStat = dereference ? statSync(src, { throwIfNoEntry: true }) : lstatSync(src, { throwIfNoEntry: true });
+  if (srcStat.isDirectory()) {
+    if (!recursive) {
+      throw new Error(`Cannot copy directory ${src} without recursive flag`);
+    }
+    if (ensureDest) {
+      mkdirsSync(dest);
+    }
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = joinPath(src, entry.name);
+      const destPath = joinPath(dest, entry.name);
+      if (entry.isDirectory()) {
+        copySync(srcPath, destPath, options);
+      } else if (entry.isFile()) {
+        copyFileSync(srcPath, destPath, fsConstants.COPYFILE_FICLONE);
+      } else if (entry.isSymbolicLink()) {
+        const target = readlinkSync(srcPath);
+        symlinkSync(target, destPath);
+      }
+    }
+    if (verify && !pathExistsSync(dest)) {
+      throw new Error(`Copy operation failed: destination directory ${dest} does not exist after copy`);
+    }
+  } else {
+    if (ensureDest) {
+      mkdirsSync(dirname(dest));
+    }
+    const destExists = statSync(dest, { throwIfNoEntry: false });
+    if (destExists) {
+      if (errorOnExist) {
+        throw new Error(`Destination ${dest} already exists.`);
+      }
+      if (!force && !overwrite) {
+        throw new Error(`Destination ${dest} already exists and overwrite is false.`);
+      }
+      if (force || overwrite) {
+        rmSync(dest, { force: true });
+      }
+    }
+    copyFileSync(src, dest, fsConstants.COPYFILE_FICLONE);
+    if (verify && !pathExistsSync(dest)) {
+      throw new Error(`Copy operation failed: destination file ${dest} does not exist after copy`);
+    }
+  }
+}
+export async function copy(src, dest, options = {}) {
+  const {
+    overwrite = options.clobber ?? true,
+    force = true,
+    recursive = false,
+    dereference = false,
+    errorOnExist = false,
+    ensureSource = true,
+    ensureDest = true,
+    verify = true
+  } = options;
+  if (ensureSource && !await pathExists(src)) {
+    throw new Error(`Source ${src} does not exist.`);
+  }
+  if (isBun && !dereference) {
+    try {
+      const srcStat2 = await getStats(src);
+      if (!srcStat2.isDirectory()) {
+        const srcFile = getFileBun(src);
+        const destFile = getFileBun(dest);
+        try {
+          const destStat = await getStats(dest);
+          if (destStat) {
+            if (errorOnExist) {
+              throw new Error(`Destination ${dest} already exists.`);
+            }
+            if (!force && !overwrite) {
+              throw new Error(`Destination ${dest} already exists and overwrite is false.`);
+            }
+            if (force || overwrite) {
+              await rm(dest, { force: true });
+            }
+          }
+        } catch (_error) {
+        }
+        if (ensureDest) {
+          const destDir = dirname(dest);
+          await mkdirs(destDir);
+        }
+        try {
+          const content = await srcFile?.text();
+          await Bun.write(destFile, content);
+          if (verify && !await pathExists(dest)) {
+            throw new Error(`Bun write failed: destination ${dest} does not exist after write`);
+          }
+          return;
+        } catch (error) {
+        }
+      }
+    } catch (error) {
+    }
+  }
+  const srcStat = await (dereference ? statAsync(src) : lstat(src)).catch((e) => {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  });
+  if (!srcStat) {
+    throw new Error(`Source ${src} does not exist`);
+  }
+  if (srcStat.isDirectory()) {
+    if (!recursive) {
+      throw new Error(`Cannot copy directory ${src} without recursive flag`);
+    }
+    if (ensureDest) {
+      await mkdirs(dest);
+    }
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = joinPath(src, entry.name);
+      const destPath = joinPath(dest, entry.name);
+      if (entry.isDirectory()) {
+        await copy(srcPath, destPath, options);
+      } else if (entry.isFile()) {
+        await copyFileAsync(srcPath, destPath, fsConstantsAsync.COPYFILE_FICLONE);
+      } else if (entry.isSymbolicLink()) {
+        const target = await readlink(srcPath);
+        await symlink(target, destPath);
+      }
+    }
+    if (verify && !await pathExists(dest)) {
+      throw new Error(`Copy operation failed: destination directory ${dest} does not exist after copy`);
+    }
+  } else {
+    if (ensureDest) {
+      await mkdirs(dirname(dest));
+    }
+    const destExists = await statAsync(dest).catch((e) => {
+      if (e.code === "ENOENT") return null;
+      throw e;
+    });
+    if (destExists) {
+      if (errorOnExist) {
+        throw new Error(`Destination ${dest} already exists.`);
+      }
+      if (!force && !overwrite) {
+        throw new Error(`Destination ${dest} already exists and overwrite is false.`);
+      }
+      if (force || overwrite) {
+        await rm(dest, { force: true });
+      }
+    }
+    await copyFileAsync(src, dest, fsConstantsAsync.COPYFILE_FICLONE);
+    if (verify && !await pathExists(dest)) {
+      throw new Error(`Copy operation failed: destination file ${dest} does not exist after copy`);
+    }
+  }
+}

package/bin/impl/create.d.ts

@@ -0,0 +1,34 @@
+export declare function createFileSync(file: string, content?: string): void;
+export declare function createFile(file: string, content?: string): Promise<void>;
+/**
+ * Creates a single directory if it doesn't exist
+ * @param dir Path to the directory to create
+ */
+export declare function createDir(dir: string): Promise<void>;
+/**
+ * Creates multiple directories if they don't exist
+ * @param dirs Array of directory paths to create
+ */
+export declare function createDirs(dirs: string[]): Promise<void>;
+/**
+ * Creates multiple files with optional content
+ * @param files Array of file paths to create
+ * @param content Optional content to write to each file
+ */
+export declare function createFiles(files: string[], content?: string): Promise<void>;
+/**
+ * Synchronous version of createDir
+ * @param dir Path to the directory to create
+ */
+export declare function createDirSync(dir: string): void;
+/**
+ * Synchronous version of createDirs
+ * @param dirs Array of directory paths to create
+ */
+export declare function createDirsSync(dirs: string[]): void;
+/**
+ * Synchronous version of createFiles
+ * @param files Array of file paths to create
+ * @param content Optional content to write to each file
+ */
+export declare function createFilesSync(files: string[], content?: string): void;

package/bin/impl/create.js

@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { stat, mkdir } from "node:fs/promises";
+import { writeFileSync } from "./write-file.js";
+import { writeFile } from "./write-file.js";
+export function createFileSync(file, content = "") {
+  if (existsSync(file)) {
+    return;
+  }
+  return writeFileSync(file, content);
+}
+export async function createFile(file, content = "") {
+  try {
+    await stat(file);
+    return;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return writeFile(file, content);
+    }
+    throw error;
+  }
+}
+export async function createDir(dir) {
+  try {
+    await stat(dir);
+    return;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await mkdir(dir, { recursive: true });
+    } else {
+      throw error;
+    }
+  }
+}
+export async function createDirs(dirs) {
+  await Promise.all(dirs.map((dir) => createDir(dir)));
+}
+export async function createFiles(files, content = "") {
+  await Promise.all(files.map((file) => createFile(file, content)));
+}
+export function createDirSync(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+export function createDirsSync(dirs) {
+  for (const dir of dirs) {
+    createDirSync(dir);
+  }
+}
+export function createFilesSync(files, content = "") {
+  for (const file of files) {
+    createFileSync(file, content);
+  }
+}

package/bin/impl/{node/dive.d.ts → dive.d.ts}

@@ -1,3 +1,4 @@
+import type { Stats } from "node:fs";
 import { statSync } from "node:fs";
 export interface DiveOptions {
     all?: boolean;
@@ -15,3 +16,12 @@ export interface DiveOptions {
  * @param options - Options for the dive operation if a callback is provided as the second argument.
  */
 export declare function diveSync(dir: string, callbackOrOptions?: ((path: string, stat: ReturnType<typeof statSync>) => void) | DiveOptions, options?: DiveOptions): Generator<string, void, unknown>;
+/**
+ * Recursively dives into a directory and yields files and directories.
+ * @param directory - The directory to dive into.
+ * @param action - An optional callback function to execute for each file or directory.
+ * @param options - An optional object containing options for the dive.
+ * @returns A Promise that resolves to an array of file paths if no action is provided, or void if an action is provided.
+ */
+export declare function dive(directory: string, action: (file: string, stat: Stats) => void | Promise<void>, options?: DiveOptions): Promise<void>;
+export declare function dive(directory: string, options?: DiveOptions): Promise<string[]>;