@reliverse/relifso 1.3.0 → 1.4.0

package/README.md

@@ -1,26 +1,26 @@
 # 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.
-
 [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
 
 - 🪄 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 ([4 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
+- ✌️ Bun v1.2+ ready — ships with Bun-aware enhancements out of the box
+- 🔥 Bun-specific features are exposed via `fs.*` when running on Bun
 
 ## 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!
 
@@ -65,9 +65,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 +118,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 +181,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 +270,61 @@ 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
+
+### 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
 
 ...
@@ -285,7 +340,7 @@ All async methods return a `Promise` if no callback is passed.
 
 ## 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,34 @@
+import type { Stats } from "node:fs";
+export declare const isBun: string | false;
+/**
+ * Get a Bun file reference with validation and error handling
+ */
+export declare function getFileBun(path: string): Bun.BunFile;
+/**
+ * Check if a file exists using Bun's optimized API
+ */
+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;

package/bin/impl/bun.js

@@ -0,0 +1,147 @@
+import { statSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { logInternal } from "./logger.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 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) {
+  if (!isBun) {
+    throw new Error("Bun runtime not detected");
+  }
+  try {
+    const file = Bun.file(path);
+    return file.type;
+  } catch (error) {
+    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.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

@@ -1,94 +1,228 @@
-import { copyFileSync, statSync, constants as fsConstants, readdirSync, rmSync } from "node:fs";
+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
+  rm,
+  lstat,
+  readlink,
+  symlink
 } from "node:fs/promises";
-import { dirname, join as joinPath, basename as basenamePath } from "node:path";
+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 { pathExists, pathExistsSync } from "./path-exists.js";
 export function copySync(src, dest, options = {}) {
-  const { overwrite = options.clobber || false, preserveTimestamps = false } = options;
-  const srcStat = statSync(src, { throwIfNoEntry: true });
-  if (!srcStat) {
-  }
-  let destFinal = dest;
-  const destStat = statSync(dest, { throwIfNoEntry: false });
-  if (!srcStat.isDirectory() && destStat?.isDirectory()) {
-    destFinal = joinPath(dest, basenamePath(src));
+  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.`);
   }
-  const destExists = statSync(destFinal, { throwIfNoEntry: false });
-  if (destExists && !overwrite) {
-    throw new Error(`Destination ${destFinal} already exists and overwrite is false.`);
+  if (isBun && !dereference) {
+    try {
+      const srcStat2 = getStatsSyncBun(src);
+      if (!srcStat2.isDirectory()) {
+        try {
+          const destStat = getStatsSyncBun(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 destDir = dirname(destFinal);
-  mkdirsSync(destDir);
+  const srcStat = dereference ? statSync(src, { throwIfNoEntry: true }) : lstatSync(src, { throwIfNoEntry: true });
   if (srcStat.isDirectory()) {
-    if (overwrite && destExists) {
-      rmSync(destFinal, { recursive: true, force: true });
+    if (!recursive) {
+      throw new Error(`Cannot copy directory ${src} without recursive flag`);
+    }
+    if (ensureDest) {
+      mkdirsSync(dest);
     }
-    mkdirsSync(destFinal);
-    const entries = readdirSync(src);
+    const entries = readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
-      const srcEntry = joinPath(src, entry);
-      const destEntry = joinPath(destFinal, entry);
-      copySync(srcEntry, destEntry, options);
+      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 (overwrite && destExists) {
-      rmSync(destFinal, { force: true });
+    if (ensureDest) {
+      mkdirsSync(dirname(dest));
     }
-    copyFileSync(src, destFinal, preserveTimestamps ? fsConstants.COPYFILE_FICLONE : 0);
-    if (preserveTimestamps) {
-      console.warn("preserveTimestamps: utimesSync is not implemented for the moment.");
+    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 || false, preserveTimestamps = false } = options;
-  const srcStat = await statAsync(src).catch((e) => {
-    if (e.code === "ENOENT") return null;
-    throw e;
-  });
-  if (!srcStat) {
+  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.`);
   }
-  let destFinal = dest;
-  const destStat = await statAsync(dest).catch((e) => {
-    if (e.code === "ENOENT") return null;
-    throw e;
-  });
-  if (!srcStat?.isDirectory() && destStat?.isDirectory()) {
-    destFinal = joinPath(dest, basenamePath(src));
+  if (isBun && !dereference) {
+    try {
+      const srcStat2 = await getStatsBun(src);
+      if (!srcStat2.isDirectory()) {
+        const srcFile = getFileBun(src);
+        const destFile = getFileBun(dest);
+        try {
+          const destStat = await getStatsBun(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 destExists = await statAsync(destFinal).catch((e) => {
+  const srcStat = await (dereference ? statAsync(src) : lstat(src)).catch((e) => {
     if (e.code === "ENOENT") return null;
     throw e;
   });
-  if (destExists && !overwrite) {
-    throw new Error(`Destination ${destFinal} already exists and overwrite is false.`);
+  if (!srcStat) {
+    throw new Error(`Source ${src} does not exist`);
   }
-  const destDir = dirname(destFinal);
-  await mkdirs(destDir);
-  if (srcStat?.isDirectory()) {
-    if (overwrite && destExists) {
-      await rm(destFinal, { recursive: true, force: true });
-    }
-    await mkdirs(destFinal);
-    const entries = await readdir(src);
+  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 srcEntry = joinPath(src, entry);
-      const destEntry = joinPath(destFinal, entry);
-      await copy(srcEntry, destEntry, options);
+      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 (overwrite && destExists) {
-      await rm(destFinal, { force: true });
+    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, destFinal, preserveTimestamps ? fsConstantsAsync.COPYFILE_FICLONE : 0);
-    if (preserveTimestamps) {
-      console.warn("preserveTimestamps: utimes is not implemented for the moment.");
+    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/dive-async.d.ts

@@ -0,0 +1,11 @@
+import type { Stats } from "node:fs";
+import type { DiveOptions } from "./dive.js";
+/**
+ * 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[]>;