@reliverse/relifso 1.4.0 → 1.4.2

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,4 +1,4 @@
-# Relifso • Node.js Filesystem Toolkit Library
+# 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)
 
@@ -6,17 +6,18 @@
 
 ## 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
 - 🧯 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 ([4 kB](https://bundlephobia.com/package/@reliverse/relifso@latest)), zero deps, modern code, no monkey-patching
+- 🧼 Zero bloat — small size, 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: Ready for upcoming Node.js v22+ experimental features
 - ✌️ Bun v1.2+ ready — ships with Bun-aware enhancements out of the box
-- 🔥 Bun-specific features are exposed via `fs.*` when running on Bun
+- 🐦‍🔥 Finally! Your `fs.*` usage is now can correctly read/write JSON/JSONC!  
 
 ## Heads Up
 
@@ -42,12 +43,49 @@ bun rm @types/fs-extra
 # bun dler relifso fs-extra to relifso
 ```
 
-**Coming soon**:
+### 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
 
-```bash
-bun add -D @reliverse/dler
-bun dler relifso init ...
-```
+### 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
 
@@ -317,14 +355,6 @@ const stats = await getStats("file.txt");
 - `getStats(path)` - Get file stats with Bun optimization
 - `getStatsSync(path)` - Synchronous version of getStats
 
-### Error Handling
-
-All Bun-specific operations include proper error handling:
-
-- Runtime detection errors
-- File operation failures
-- Automatic fallback to Node.js APIs when needed
-
 ## Contributing
 
 ...
@@ -337,6 +367,7 @@ All Bun-specific operations include proper error handling:
 - [ ] 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
 

package/bin/impl/bun.d.ts

@@ -1,34 +1,11 @@
-import type { Stats } from "node:fs";
 export declare const isBun: string | false;
 /**
- * Get a Bun file reference with validation and error handling
+ * 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;
 /**
- * Check if a file exists using Bun's optimized API
+ * Get file type
+ * Uses Bun's optimized API when available, throws error otherwise
  */
-export declare function existsBun(path: string): Promise<boolean>;
-/**
- * Get file size using Bun's optimized API
- */
-export declare function sizeBun(path: string): Promise<number>;
-/**
- * Get file type using Bun's optimized API
- */
-export declare function typeBun(path: string): Promise<string>;
-/**
- * Get file last modified time using Bun's optimized API
- */
-export declare function lastModifiedBun(path: string): Promise<Date>;
-/**
- * Convert Bun file stats to Node.js Stats object
- */
-export declare function toNodeStatsBun(path: string): Promise<Stats>;
-/**
- * Get file stats using Bun's optimized API with fallback to Node.js
- */
-export declare function getStatsBun(path: string): Promise<Stats>;
-/**
- * Get file stats synchronously using Bun's optimized API with fallback to Node.js
- */
-export declare function getStatsSyncBun(path: string): Stats;
+export declare function getFileTypeBun(path: string): Promise<string>;

package/bin/impl/bun.js

@@ -1,6 +1,4 @@
-import { statSync } from "node:fs";
-import { stat } from "node:fs/promises";
-import { logInternal } from "./logger.js";
+import { logInternal } from "../utils/log.js";
 export const isBun = typeof process !== "undefined" && process.versions.bun;
 export function getFileBun(path) {
   if (!isBun) {
@@ -12,29 +10,7 @@ export function getFileBun(path) {
     throw error;
   }
 }
-export async function existsBun(path) {
-  if (!isBun) {
-    throw new Error("Bun runtime not detected");
-  }
-  try {
-    const file = Bun.file(path);
-    return await file.exists();
-  } catch (error) {
-    return false;
-  }
-}
-export async function sizeBun(path) {
-  if (!isBun) {
-    throw new Error("Bun runtime not detected");
-  }
-  try {
-    const file = Bun.file(path);
-    return file.size;
-  } catch (error) {
-    throw error;
-  }
-}
-export async function typeBun(path) {
+export async function getFileTypeBun(path) {
   if (!isBun) {
     throw new Error("Bun runtime not detected");
   }
@@ -45,103 +21,3 @@ export async function typeBun(path) {
     throw error;
   }
 }
-export async function lastModifiedBun(path) {
-  if (!isBun) {
-    throw new Error("Bun runtime not detected");
-  }
-  try {
-    const file = Bun.file(path);
-    return new Date(file.lastModified);
-  } catch (error) {
-    throw error;
-  }
-}
-export async function toNodeStatsBun(path) {
-  if (!isBun) {
-    throw new Error("Bun runtime not detected");
-  }
-  try {
-    const file = Bun.file(path);
-    const size = file.size;
-    const lastModified = new Date(file.lastModified);
-    return {
-      dev: 0,
-      ino: 0,
-      mode: 0,
-      nlink: 0,
-      uid: 0,
-      gid: 0,
-      rdev: 0,
-      size,
-      blksize: 0,
-      blocks: 0,
-      atimeMs: lastModified.getTime(),
-      mtimeMs: lastModified.getTime(),
-      ctimeMs: lastModified.getTime(),
-      birthtimeMs: lastModified.getTime(),
-      atime: lastModified,
-      mtime: lastModified,
-      ctime: lastModified,
-      birthtime: lastModified,
-      isDirectory: () => false,
-      // Bun doesn't provide this info directly
-      isFile: () => true,
-      isBlockDevice: () => false,
-      isCharacterDevice: () => false,
-      isSymbolicLink: () => false,
-      isFIFO: () => false,
-      isSocket: () => false
-    };
-  } catch (error) {
-    throw error;
-  }
-}
-export async function getStatsBun(path) {
-  if (!isBun) {
-    return stat(path);
-  }
-  try {
-    return await toNodeStatsBun(path);
-  } catch (error) {
-    return stat(path);
-  }
-}
-export function getStatsSyncBun(path) {
-  if (!isBun) {
-    return statSync(path);
-  }
-  try {
-    const file = Bun.file(path);
-    const size = file.size;
-    const lastModified = new Date(file.lastModified);
-    return {
-      dev: 0,
-      ino: 0,
-      mode: 0,
-      nlink: 0,
-      uid: 0,
-      gid: 0,
-      rdev: 0,
-      size,
-      blksize: 0,
-      blocks: 0,
-      atimeMs: lastModified.getTime(),
-      mtimeMs: lastModified.getTime(),
-      ctimeMs: lastModified.getTime(),
-      birthtimeMs: lastModified.getTime(),
-      atime: lastModified,
-      mtime: lastModified,
-      ctime: lastModified,
-      birthtime: lastModified,
-      isDirectory: () => false,
-      isFile: () => true,
-      isBlockDevice: () => false,
-      isCharacterDevice: () => false,
-      isSymbolicLink: () => false,
-      isFIFO: () => false,
-      isSocket: () => false
-    };
-  } catch (error) {
-    return statSync(path);
-  }
-}

package/bin/impl/copy.js

@@ -21,9 +21,10 @@ import {
 import { dirname, join as joinPath } from "node:path";
 import { mkdirsSync } from "./mkdirs.js";
 import { mkdirs } from "./mkdirs.js";
-import { isBun, getFileBun, getStatsBun, getStatsSyncBun } from "./bun.js";
-import { logInternal } from "./logger.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,
@@ -40,10 +41,10 @@ export function copySync(src, dest, options = {}) {
   }
   if (isBun && !dereference) {
     try {
-      const srcStat2 = getStatsSyncBun(src);
+      const srcStat2 = getStatsSync(src);
       if (!srcStat2.isDirectory()) {
         try {
-          const destStat = getStatsSyncBun(dest);
+          const destStat = getStatsSync(dest);
           if (destStat) {
             if (errorOnExist) {
               throw new Error(`Destination ${dest} already exists.`);
@@ -135,12 +136,12 @@ export async function copy(src, dest, options = {}) {
   }
   if (isBun && !dereference) {
     try {
-      const srcStat2 = await getStatsBun(src);
+      const srcStat2 = await getStats(src);
       if (!srcStat2.isDirectory()) {
         const srcFile = getFileBun(src);
         const destFile = getFileBun(dest);
         try {
-          const destStat = await getStatsBun(dest);
+          const destStat = await getStats(dest);
           if (destStat) {
             if (errorOnExist) {
               throw new Error(`Destination ${dest} already exists.`);
@@ -159,7 +160,7 @@ export async function copy(src, dest, options = {}) {
           await mkdirs(destDir);
         }
         try {
-          const content = await srcFile.text();
+          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`);

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/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[]>;

package/bin/impl/dive.js

@@ -1,5 +1,9 @@
 import { readdirSync, statSync } from "node:fs";
+import { readdir as nodeReaddirInternal, stat as nodeStatInternal } from "node:fs/promises";
 import { join } from "node:path";
+import { join as pathJoin } from "node:path";
+import { isBun } from "./bun.js";
+import { getStats } from "./stats.js";
 export function* diveSync(dir, callbackOrOptions, options) {
   const currentDepth = 0;
   let actualOptions = {
@@ -54,3 +58,88 @@ export function* diveSync(dir, callbackOrOptions, options) {
   }
   yield* walk(dir, currentDepth);
 }
+async function* _diveWorker(currentPath, options, currentDepth) {
+  const maxDepth = options.depth ?? Number.POSITIVE_INFINITY;
+  if (currentDepth > maxDepth) {
+    return;
+  }
+  let entries;
+  try {
+    entries = await nodeReaddirInternal(currentPath, { withFileTypes: true });
+  } catch (_err) {
+    return;
+  }
+  for (const entry of entries) {
+    const entryPath = pathJoin(currentPath, entry.name);
+    if (!(options.all ?? false) && entry.name.startsWith(".")) {
+      continue;
+    }
+    if (options.ignore) {
+      if (Array.isArray(options.ignore) && options.ignore.some((pattern) => entry.name.includes(pattern))) {
+        continue;
+      }
+      if (options.ignore instanceof RegExp && options.ignore.test(entryPath)) {
+        continue;
+      }
+    }
+    let entryStat;
+    try {
+      if (isBun) {
+        try {
+          entryStat = await getStats(entryPath);
+        } catch (_error) {
+          entryStat = await nodeStatInternal(entryPath);
+        }
+      } else {
+        entryStat = await nodeStatInternal(entryPath);
+      }
+    } catch (_err) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      if (options.directories ?? false) {
+        yield { file: entryPath, stat: entryStat };
+      }
+      if (options.recursive ?? true) {
+        if (currentDepth < maxDepth) {
+          yield* _diveWorker(entryPath, options, currentDepth + 1);
+        }
+      }
+    } else if (entry.isFile()) {
+      if (options.files ?? true) {
+        yield { file: entryPath, stat: entryStat };
+      }
+    }
+  }
+}
+export async function dive(directory, actionOrOptions, optionsOnly) {
+  let action;
+  let options;
+  if (typeof actionOrOptions === "function") {
+    action = actionOrOptions;
+    options = optionsOnly;
+  } else {
+    options = actionOrOptions;
+  }
+  const currentOptions = {
+    recursive: true,
+    files: true,
+    directories: false,
+    all: false,
+    depth: Number.POSITIVE_INFINITY,
+    ...options
+    // User options override defaults
+  };
+  if (action) {
+    for await (const { file, stat: entryStat } of _diveWorker(directory, currentOptions, 0)) {
+      await action(file, entryStat);
+    }
+    return;
+  } else {
+    const results = [];
+    for await (const { file } of _diveWorker(directory, currentOptions, 0)) {
+      results.push(file);
+    }
+    return results;
+  }
+}

package/bin/impl/empty.d.ts

@@ -0,0 +1,28 @@
+interface EmptyFileOptions {
+    /**
+     * If true, will replace all object literals with empty objects {}
+     * Only works with JSON files
+     */
+    emptyObjects?: boolean;
+}
+export declare function emptyDirSync(dir: string): void;
+export declare function emptyDir(dir: string): Promise<void>;
+/**
+ * Empties an object by removing all its properties
+ * @param obj The object to empty
+ * @returns The empty object
+ */
+export declare function emptyObject<T extends object>(obj: T): T;
+/**
+ * Empties a file by removing all its contents
+ * @param filePath Path to the file
+ * @param options Options for emptying the file
+ */
+export declare function emptyFile(filePath: string, options?: EmptyFileOptions): Promise<void>;
+/**
+ * Synchronous version of emptyFile
+ * @param filePath Path to the file
+ * @param options Options for emptying the file
+ */
+export declare function emptyFileSync(filePath: string, options?: EmptyFileOptions): void;
+export {};

package/bin/impl/empty.js

@@ -0,0 +1,75 @@
+import { existsSync, readdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { readdir, rm, stat, writeFile, readFile } from "node:fs/promises";
+import path from "node:path";
+export function emptyDirSync(dir) {
+  if (!existsSync(dir)) {
+    return;
+  }
+  for (const file of readdirSync(dir)) {
+    rmSync(path.resolve(dir, file), { recursive: true, force: true });
+  }
+}
+export async function emptyDir(dir) {
+  try {
+    await stat(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  for (const file of await readdir(dir)) {
+    await rm(path.resolve(dir, file), { recursive: true, force: true });
+  }
+}
+export function emptyObject(obj) {
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      delete obj[key];
+    }
+  }
+  return obj;
+}
+export async function emptyFile(filePath, options = {}) {
+  try {
+    await stat(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  if (options.emptyObjects && filePath.toLowerCase().endsWith(".json")) {
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const data = JSON.parse(content);
+      if (typeof data === "object" && data !== null) {
+        const emptyData = emptyObject(data);
+        await writeFile(filePath, JSON.stringify(emptyData, null, 2));
+        return;
+      }
+    } catch (error) {
+      console.warn(`Failed to parse JSON file ${filePath}, falling back to regular file emptying:`, error);
+    }
+  }
+  await writeFile(filePath, "");
+}
+export function emptyFileSync(filePath, options = {}) {
+  if (!existsSync(filePath)) {
+    return;
+  }
+  if (options.emptyObjects && filePath.toLowerCase().endsWith(".json")) {
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const data = JSON.parse(content);
+      if (typeof data === "object" && data !== null) {
+        const emptyData = emptyObject(data);
+        writeFileSync(filePath, JSON.stringify(emptyData, null, 2));
+        return;
+      }
+    } catch (error) {
+      console.warn(`Failed to parse JSON file ${filePath}, falling back to regular file emptying:`, error);
+    }
+  }
+  writeFileSync(filePath, "");
+}

package/bin/impl/extras.d.ts

@@ -1,7 +1,27 @@
 import { exec } from "node:child_process";
+export declare function readText(filePath: string, options?: BufferEncoding | {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+}): Promise<string>;
+export declare function readTextSync(filePath: string, options?: BufferEncoding | {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+}): string;
+export declare function readLines(filePath: string, options?: BufferEncoding | {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+}): Promise<string[]>;
+export declare function readLinesSync(filePath: string, options?: BufferEncoding | {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+}): string[];
+export declare function isDirectory(filePath: string): Promise<boolean>;
+export declare function isDirectorySync(filePath: string): boolean;
+export declare function isSymlink(filePath: string): Promise<boolean>;
+export declare function isSymlinkSync(filePath: string): boolean;
 export declare const execAsync: typeof exec.__promisify__;
-export declare function setHiddenAttributeOnWindows(folderPath: string): Promise<void>;
-export declare function isHidden(filePath: string): Promise<boolean>;
+export declare function setHiddenAttribute(folderPath: string): Promise<void>;
+export declare function isHiddenAttribute(filePath: string): Promise<boolean>;
 /**
  * Checks if a directory is empty
  * @param directory Path to the directory