@reliverse/relifso 1.4.1 → 1.4.3

package/README.md

@@ -13,7 +13,7 @@
 - 🧯 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 ([6 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
 - ✌️ Bun v1.2+ ready — ships with Bun-aware enhancements out of the box
@@ -129,6 +129,71 @@ console.log(config); // { hello: 'world' }
 await remove(".reliverse");
 ```
 
+## Run Example
+
+Install this repository locally and run the example by using `bun dev`:
+
+```bash
+$ bun e-mod.ts
+✓   Running examples with Bun...
+Created directory ./tests-runtime
+[env] writeJson was successfully executed in Bun (for JSON)
+Wrote JSON tests-runtime\config.json
+[env] readJson was successfully executed in Bun
+Read JSON {"hello":"world","ts":"2025-06-02T19:01:53.291Z"}
+[env] copy was successfully executed in Bun
+Moved → Copied (with overwrite) tests-runtime\config.old.json → tests-runtime\config.copy.json
+[env] readFile was successfully executed in Bun
+Wrote & read text file Hello Relifso!
+[env] writeFile was successfully executed in Bun
+[env] writeFile was successfully executed in Bun
+Ensured nested & output files
+[env] writeJson was successfully executed in Bun (for JSON)
+[env] readJson was successfully executed in Bun
+writeJson / readJson round-trip {"foo":"bar"}
+[env] writeJson was successfully executed in Bun (for JSONC)
+Wrote JSONC tests-runtime\config.jsonc
+[env] readJson was successfully executed in Bun
+Read JSONC {
+  "name": "relifso",
+  "version": "1.0.0",
+  "features": [
+    "file operations",
+    "directory operations",
+    "JSONC support"
+  ],
+  "settings": {
+    "debug": true,
+    "verbose": false
+  }
+}
+Emptied directory tests-runtime\empty-me
+[env] writeFileSync was successfully executed in Bun
+[env] writeJsonSync was successfully executed in Bun (for JSON)
+Sync JSON round-trip {"sync":true}
+[env] copySync was successfully executed in Bun
+copySync → moveSync → removeSync chain complete
+Directory structure via dive
+ • tests-runtime\config-sync.json
+ • tests-runtime\config.copy.json
+ • tests-runtime\config.jsonc
+ • tests-runtime\config.old.json
+ • tests-runtime\config2.json
+ • tests-runtime\hello.txt
+ • tests-runtime\nested\deep\file.txt
+ • tests-runtime\output-file.txt
+Directory structure via diveSync
+ • tests-runtime\config-sync.json
+ • tests-runtime\config.copy.json
+ • tests-runtime\config.jsonc
+ • tests-runtime\config.old.json
+ • tests-runtime\config2.json
+ • tests-runtime\hello.txt
+ • tests-runtime\nested\deep\file.txt
+ • tests-runtime\output-file.txt
+Removed directory ./tests-runtime
+```
+
 ## Sync vs Async vs Legacy
 
 You choose your flavor:

package/bin/impl/copy.d.ts

@@ -1,7 +1,7 @@
 export interface CopyOptions {
-    /** Whether to overwrite existing files. Default: true */
+    /** @deprecated Use `overwrite` instead. This option will be removed in a future. */
     force?: boolean;
-    /** Whether to overwrite existing files. Alias for force. Default: true */
+    /** Whether to overwrite existing files. Default: true */
     overwrite?: boolean;
     /** @deprecated Use `overwrite`. */
     clobber?: boolean;

package/bin/impl/copy.js

@@ -29,7 +29,7 @@ export function copySync(src, dest, options = {}) {
   const {
     overwrite = options.clobber ?? true,
     force = true,
-    recursive = false,
+    recursive = true,
     dereference = false,
     errorOnExist = false,
     ensureSource = true,
@@ -124,7 +124,7 @@ export async function copy(src, dest, options = {}) {
   const {
     overwrite = options.clobber ?? true,
     force = true,
-    recursive = false,
+    recursive = true,
     dereference = false,
     errorOnExist = false,
     ensureSource = true,

package/bin/impl/move.d.ts

@@ -1,4 +1,7 @@
 export interface MoveOptions {
+    /** @deprecated Use `overwrite` instead. This option will be removed in a future. */
+    force?: boolean;
+    /** Whether to overwrite existing files. Default: false */
     overwrite?: boolean;
     /** @deprecated Use `overwrite`. */
     clobber?: boolean;

package/bin/impl/read-file.d.ts

@@ -10,9 +10,9 @@ export interface ReadFileOptions {
  *
  * @param path - The path to the file.
  * @param options - Options for reading the file. Can be an encoding string or an object.
- * @returns The contents of the file.
+ * @returns The contents of the file as a string.
  */
-export declare function readFileSync(path: string, options?: BufferEncoding | ReadFileOptions): string | Buffer;
+export declare function readFileSync(path: string, options?: BufferEncoding | ReadFileOptions): string;
 export declare function readFileSync(path: string, encoding: BufferEncoding): string;
 export declare function readFileSync(path: string, options: {
     encoding: BufferEncoding;
@@ -22,9 +22,9 @@ export declare function readFileSync(path: string, options: {
  *
  * @param path - The path to the file.
  * @param options - Options for reading the file. Can be an encoding string or an object.
- * @returns A promise that resolves with the contents of the file.
+ * @returns A promise that resolves with the contents of the file as a string.
  */
-export declare function readFile(path: string, options?: BufferEncoding | ReadFileOptions): Promise<string | Buffer>;
+export declare function readFile(path: string, options?: BufferEncoding | ReadFileOptions): Promise<string>;
 export declare function readFile(path: string, encoding: BufferEncoding): Promise<string>;
 export declare function readFile(path: string, options: {
     encoding: BufferEncoding;

package/bin/impl/read-file.js

@@ -38,13 +38,13 @@ export function readFileSync(path, options) {
         if (buffer instanceof Promise) {
           throw new Error("Bun's arrayBuffer() returned a Promise in sync context");
         }
-        return Buffer.from(buffer);
+        return Buffer.from(buffer).toString(encoding || "utf8");
       } catch (_error) {
         const text = file.text();
         if (text instanceof Promise) {
           throw new Error("Bun's text() returned a Promise in sync context");
         }
-        return Buffer.from(text);
+        return text;
       }
     } catch (error) {
     }
@@ -52,7 +52,7 @@ export function readFileSync(path, options) {
   if (encoding) {
     return nodeReadFileSync(path, { encoding, flag });
   }
-  return nodeReadFileSync(path, { encoding: null, flag });
+  return nodeReadFileSync(path, { encoding: "utf8", flag });
 }
 export async function readFile(path, options) {
   let encoding;
@@ -77,10 +77,10 @@ export async function readFile(path, options) {
           const result = await file.text();
           if (isJson) {
             try {
-              return JSON.parse(result, reviver);
+              return JSON.stringify(JSON.parse(result, reviver));
             } catch (_parseError) {
               const repaired = jsonrepair(result);
-              return JSON.parse(repaired, reviver);
+              return JSON.stringify(JSON.parse(repaired, reviver));
             }
           }
           return result;
@@ -89,10 +89,10 @@ export async function readFile(path, options) {
           const text = Buffer.from(buffer).toString(encoding);
           if (isJson) {
             try {
-              return JSON.parse(text, reviver);
+              return JSON.stringify(JSON.parse(text, reviver));
             } catch (_parseError) {
               const repaired = jsonrepair(text);
-              return JSON.parse(repaired, reviver);
+              return JSON.stringify(JSON.parse(repaired, reviver));
             }
           }
           return text;
@@ -100,27 +100,27 @@ export async function readFile(path, options) {
       }
       try {
         const buffer = await file.arrayBuffer();
+        const text = Buffer.from(buffer).toString(encoding || "utf8");
         if (isJson) {
-          const text = Buffer.from(buffer).toString();
           try {
-            return JSON.parse(text, reviver);
+            return JSON.stringify(JSON.parse(text, reviver));
           } catch (_parseError) {
             const repaired = jsonrepair(text);
-            return JSON.parse(repaired, reviver);
+            return JSON.stringify(JSON.parse(repaired, reviver));
           }
         }
-        return Buffer.from(buffer);
+        return text;
       } catch (_error) {
         const text = await file.text();
         if (isJson) {
           try {
-            return JSON.parse(text, reviver);
+            return JSON.stringify(JSON.parse(text, reviver));
           } catch (_parseError) {
             const repaired = jsonrepair(text);
-            return JSON.parse(repaired, reviver);
+            return JSON.stringify(JSON.parse(repaired, reviver));
           }
         }
-        return Buffer.from(text);
+        return text;
       }
     } catch (error) {
     }
@@ -139,10 +139,10 @@ export async function readFile(path, options) {
       const text = chunks.join("");
       if (isJson) {
         try {
-          return JSON.parse(text, reviver);
+          return JSON.stringify(JSON.parse(text, reviver));
         } catch (_parseError) {
           const repaired = jsonrepair(text);
-          return JSON.parse(repaired, reviver);
+          return JSON.stringify(JSON.parse(repaired, reviver));
         }
       }
       return text;
@@ -153,13 +153,13 @@ export async function readFile(path, options) {
     const text = await nodeReadFileAsync(path, { encoding, flag });
     if (isJson) {
       try {
-        return JSON.parse(text, reviver);
+        return JSON.stringify(JSON.parse(text, reviver));
       } catch (_parseError) {
         const repaired = jsonrepair(text);
-        return JSON.parse(repaired, reviver);
+        return JSON.stringify(JSON.parse(repaired, reviver));
       }
     }
     return text;
   }
-  return nodeReadFileAsync(path, { encoding: null, flag });
+  return await nodeReadFileAsync(path, { encoding: "utf8", flag });
 }

package/bin/impl/write-file.d.ts

@@ -15,16 +15,16 @@ type WriteTarget = PathLike | number | URL | WriteStream;
  * Ensures the directory exists before writing.
  *
  * @param file - Path to the file, file descriptor, URL, or special streams (stdout/stderr).
- * @param data - The data to write. Can be a string, Buffer, Uint8Array, Blob, Response, or other ArrayBufferView.
+ * @param data - The data to write. Will be converted to string if not already a string.
  * @param options - Options for writing the file. Can be an encoding string or an object.
  */
-export declare function writeFileSync(file: WriteTarget, data: string | NodeJS.ArrayBufferView | Blob | Response, options?: WriteFileOptions): void;
+export declare function writeFileSync(file: WriteTarget, data: string | NodeJS.ArrayBufferView | Blob | Response | unknown, options?: WriteFileOptions): void;
 /**
  * Asynchronously writes data to a file, replacing the file if it already exists.
  * Ensures the directory exists before writing.
  *
  * @param file - Path to the file, file descriptor, URL, or special streams (stdout/stderr).
- * @param data - The data to write. Can be a string, Buffer, Uint8Array, Blob, Response, or other ArrayBufferView.
+ * @param data - The data to write. Will be converted to string if not already a string.
  * @param options - Options for writing the file. Can be an encoding string or an object.
  */
 export declare function writeFile(file: WriteTarget, data: string | NodeJS.ArrayBufferView | Blob | Response | unknown, options?: WriteFileOptions): Promise<void>;

package/bin/impl/write-file.js

@@ -1,5 +1,5 @@
 import { writeFileSync as nodeWriteFileSync, createWriteStream } from "node:fs";
-import { mkdir, writeFile as nodeWriteFileAsync, stat } from "node:fs/promises";
+import { mkdir, writeFile as nodeWriteFileAsync } from "node:fs/promises";
 import path from "node:path";
 import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -17,45 +17,53 @@ function isPathLike(target) {
   return !isStdStream(target) && !isFileDescriptor(target) && !(target instanceof URL);
 }
 export function writeFileSync(file, data, options) {
-  if (isStdStream(file)) {
-    if (typeof data === "string") {
-      file.write(data);
-    } else if (data instanceof Uint8Array) {
-      file.write(data);
-    } else if (data instanceof Blob || data instanceof Response) {
-      throw new Error("Blob and Response are not supported for stdout/stderr in sync context");
-    } else if (data instanceof ArrayBuffer) {
-      file.write(Buffer.from(new Uint8Array(data)));
-    } else if (ArrayBuffer.isView(data)) {
-      file.write(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
-    } else {
-      throw new Error("Unsupported data type for stream writing");
+  let isJson = false;
+  let replacer;
+  let spaces;
+  let encoding;
+  let mode;
+  let flag;
+  if (options) {
+    isJson = options.isJson ?? isJson;
+    replacer = options.replacer;
+    spaces = options.spaces;
+    encoding = options.encoding;
+    mode = options.mode ? Number(options.mode) : void 0;
+    flag = options.flag;
+  }
+  let stringData;
+  if (typeof data === "string") {
+    stringData = data;
+  } else if (data instanceof Uint8Array) {
+    stringData = Buffer.from(data).toString(encoding || "utf8");
+  } else if (data instanceof Blob || data instanceof Response) {
+    throw new Error("Blob and Response are not supported in sync context");
+  } else if (data instanceof ArrayBuffer) {
+    stringData = Buffer.from(new Uint8Array(data)).toString(encoding || "utf8");
+  } else if (ArrayBuffer.isView(data)) {
+    stringData = Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString(encoding || "utf8");
+  } else if (isJson) {
+    try {
+      stringData = JSON.stringify(data, replacer, spaces);
+      if (stringData === void 0) {
+        throw new Error("Failed to stringify JSON object");
+      }
+    } catch (err) {
+      throw new Error(`Failed to stringify JSON data: ${err}`);
     }
+  } else {
+    stringData = String(data);
+  }
+  if (isStdStream(file)) {
+    file.write(stringData);
     return;
   }
   if (isFileDescriptor(file)) {
     if (isBun) {
-      let writeData;
-      if (typeof data === "string") {
-        writeData = data;
-      } else if (data instanceof Uint8Array) {
-        writeData = data;
-      } else if (data instanceof Blob || data instanceof Response) {
-        throw new Error("Blob and Response are not supported in sync context with Bun");
-      } else if (data instanceof ArrayBuffer) {
-        writeData = new Uint8Array(data);
-      } else if (ArrayBuffer.isView(data)) {
-        writeData = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-      } else {
-        throw new Error("Unsupported data type for Bun file descriptor writing");
-      }
-      Bun.write(Bun.file(file), writeData);
+      Bun.write(Bun.file(file), stringData);
       return;
     }
-    if (data instanceof Blob || data instanceof Response) {
-      throw new Error("Blob and Response are not supported for file descriptors in sync context");
-    }
-    nodeWriteFileSync(file, data, options);
+    nodeWriteFileSync(file, stringData, { encoding: encoding || "utf8", mode, flag });
     return;
   }
   if (file instanceof URL) {
@@ -72,38 +80,12 @@ export function writeFileSync(file, data, options) {
   if (isBun) {
     try {
       const filePath = file.toString();
-      let writeData;
-      if (typeof data === "string") {
-        writeData = data;
-      } else if (data instanceof Uint8Array) {
-        writeData = data;
-      } else if (data instanceof Blob || data instanceof Response) {
-        throw new Error("Blob and Response are not supported in sync context with Bun");
-      } else if (data instanceof ArrayBuffer) {
-        writeData = new Uint8Array(data);
-      } else if (ArrayBuffer.isView(data)) {
-        writeData = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-      } else {
-        throw new Error("Unsupported data type for Bun file writing");
-      }
-      Bun.write(filePath, writeData);
+      Bun.write(filePath, stringData);
       return;
     } catch (_error) {
     }
   }
-  let nodeData;
-  if (data instanceof Blob || data instanceof Response) {
-    throw new Error("Blob and Response are not supported in sync context");
-  } else if (typeof data === "string") {
-    nodeData = data;
-  } else if (data instanceof ArrayBuffer) {
-    nodeData = Buffer.from(new Uint8Array(data));
-  } else if (ArrayBuffer.isView(data)) {
-    nodeData = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-  } else {
-    throw new Error("Unsupported data type for Node.js file writing");
-  }
-  nodeWriteFileSync(file, nodeData, options);
+  nodeWriteFileSync(file, stringData, { encoding: encoding || "utf8", mode, flag });
 }
 export async function writeFile(file, data, options) {
   let isJson = false;
@@ -122,56 +104,42 @@ export async function writeFile(file, data, options) {
     mode = options.mode ? Number(options.mode) : void 0;
     flag = options.flag;
   }
-  if (isJson && typeof data !== "string" && !(data instanceof Uint8Array) && !(data instanceof Blob) && !(data instanceof Response)) {
+  let stringData;
+  if (typeof data === "string") {
+    stringData = data;
+  } else if (data instanceof Uint8Array) {
+    stringData = Buffer.from(data).toString(encoding || "utf8");
+  } else if (data instanceof Blob) {
+    stringData = await data.text();
+  } else if (data instanceof Response) {
+    stringData = await data.text();
+  } else if (data instanceof ArrayBuffer) {
+    stringData = Buffer.from(new Uint8Array(data)).toString(encoding || "utf8");
+  } else if (ArrayBuffer.isView(data)) {
+    stringData = Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString(encoding || "utf8");
+  } else if (isJson) {
     try {
-      const jsonString = JSON.stringify(data, replacer, spaces);
-      if (jsonString === void 0) {
+      stringData = JSON.stringify(data, replacer, spaces);
+      if (stringData === void 0) {
         throw new Error("Failed to stringify JSON object");
       }
-      data = jsonString;
     } catch (err) {
       throw new Error(`Failed to stringify JSON data: ${err}`);
     }
+  } else {
+    stringData = String(data);
   }
   if (isStdStream(file)) {
-    if (typeof data === "string") {
-      file.write(data);
-    } else if (data instanceof Uint8Array) {
-      file.write(data);
-    } else if (data instanceof Blob || data instanceof Response) {
-      throw new Error("Blob and Response are not supported for stdout/stderr in sync context");
-    } else if (data instanceof ArrayBuffer) {
-      file.write(Buffer.from(new Uint8Array(data)));
-    } else if (ArrayBuffer.isView(data)) {
-      file.write(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
-    } else {
-      throw new Error("Unsupported data type for stream writing");
-    }
+    file.write(stringData);
     return;
   }
   if (isFileDescriptor(file)) {
     if (isBun) {
-      let writeData;
-      if (typeof data === "string") {
-        writeData = data;
-      } else if (data instanceof Uint8Array) {
-        writeData = data;
-      } else if (data instanceof Blob || data instanceof Response) {
-        throw new Error("Blob and Response are not supported in sync context with Bun");
-      } else if (data instanceof ArrayBuffer) {
-        writeData = new Uint8Array(data);
-      } else if (ArrayBuffer.isView(data)) {
-        writeData = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-      } else {
-        throw new Error("Unsupported data type for Bun file descriptor writing");
-      }
-      Bun.write(Bun.file(file), writeData);
+      await Bun.write(Bun.file(file), stringData);
       return;
     }
-    if (data instanceof Blob || data instanceof Response) {
-      throw new Error("Blob and Response are not supported for file descriptors in sync context");
-    }
-    return nodeWriteFileSync(file, data, options);
+    await nodeWriteFileAsync(file, stringData, { encoding: encoding || "utf8", mode, flag });
+    return;
   }
   if (file instanceof URL) {
     if (file.protocol !== "file:") {
@@ -183,30 +151,16 @@ export async function writeFile(file, data, options) {
     throw new Error("Invalid file target");
   }
   const dir = path.dirname(file.toString());
-  try {
-    await stat(dir);
-  } catch (_error) {
-    if (_error.code === "ENOENT") {
-      await mkdir(dir, { recursive: true });
-    } else {
-      throw _error;
-    }
-  }
-  if (useStreaming && typeof data === "string") {
+  await mkdir(dir, { recursive: true });
+  if (useStreaming) {
     try {
-      const writeStream = createWriteStream(file.toString(), {
-        encoding,
-        mode,
-        flags: flag
-      });
+      const writeStream = createWriteStream(file, { encoding: encoding || "utf8", mode, flags: flag });
       const transform = new Transform({
         transform(chunk, _encoding, callback) {
           callback(null, chunk);
         }
       });
-      transform.write(data);
-      transform.end();
-      await pipeline(transform, writeStream);
+      await pipeline(stringData, transform, writeStream);
       return;
     } catch (streamError) {
     }
@@ -214,44 +168,10 @@ export async function writeFile(file, data, options) {
   if (isBun) {
     try {
       const filePath = file.toString();
-      let writeData;
-      if (typeof data === "string") {
-        writeData = data;
-      } else if (data instanceof Uint8Array) {
-        writeData = data;
-      } else if (data instanceof Blob) {
-        const buffer = await data.arrayBuffer();
-        writeData = new Uint8Array(buffer);
-      } else if (data instanceof Response) {
-        const buffer = await data.arrayBuffer();
-        writeData = new Uint8Array(buffer);
-      } else if (data instanceof ArrayBuffer) {
-        writeData = new Uint8Array(data);
-      } else if (ArrayBuffer.isView(data)) {
-        writeData = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-      } else {
-        throw new Error("Unsupported data type for Bun file writing");
-      }
-      await Bun.write(filePath, writeData);
+      await Bun.write(filePath, stringData);
       return;
     } catch (_error) {
     }
   }
-  let nodeData;
-  if (data instanceof Blob) {
-    const buffer = await data.arrayBuffer();
-    nodeData = Buffer.from(buffer);
-  } else if (data instanceof Response) {
-    const buffer = await data.arrayBuffer();
-    nodeData = Buffer.from(buffer);
-  } else if (typeof data === "string") {
-    nodeData = data;
-  } else if (data instanceof ArrayBuffer) {
-    nodeData = Buffer.from(new Uint8Array(data));
-  } else if (ArrayBuffer.isView(data)) {
-    nodeData = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-  } else {
-    throw new Error("Unsupported data type for Node.js file writing");
-  }
-  await nodeWriteFileAsync(file, nodeData, options);
+  await nodeWriteFileAsync(file, stringData, { encoding: encoding || "utf8", mode, flag });
 }

package/package.json

@@ -5,7 +5,7 @@
   "license": "MIT",
   "name": "@reliverse/relifso",
   "type": "module",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "keywords": [
     "fs",
     "file",