@reliverse/relifso 1.1.3 → 1.2.1

package/README.md

@@ -16,6 +16,12 @@
 - ✌️ **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
 
+## Heads Up
+
+- **Most of the things** mentioned in this doc **aren’t implemented yet** — they’re part of the vision for ~`v1.3.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!
+
 ## Install
 
 ```bash
@@ -282,7 +288,6 @@ 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
 - [`fsxt`](https://github.com/uwx-node-modules/fsxt) — full fs-extra overhaul
-- [`fs-lite`](https://github.com/baooab/node-fs-lite) — no-deps, fully-typed
 
 ## Show Some Love
 

package/bin/impl/copy.d.ts

@@ -0,0 +1,28 @@
+export interface CopyOptions {
+    overwrite?: boolean;
+    /** @deprecated Use `overwrite`. */
+    clobber?: boolean;
+    preserveTimestamps?: boolean;
+    /** @deprecated Not used. */
+    errorOnExist?: boolean;
+    /** @deprecated Not used. */
+    dereference?: boolean;
+    /** @deprecated Not used. */
+    filter?: (src: string, dest: string) => boolean;
+}
+/**
+ * Copies a file or directory. The directory can have contents. Like `cp -r`.
+ *
+ * @param src - The source path.
+ * @param dest - The destination path.
+ * @param options - Options for the copy operation.
+ */
+export declare function copySync(src: string, dest: string, options?: CopyOptions): void;
+/**
+ * Asynchronously copies a file or directory. The directory can have contents. Like `cp -r`.
+ *
+ * @param src - The source path.
+ * @param dest - The destination path.
+ * @param options - Options for the copy operation.
+ */
+export declare function copy(src: string, dest: string, options?: CopyOptions): Promise<void>;

package/bin/impl/copy.js

@@ -0,0 +1,64 @@
+import { copyFileSync, statSync, constants as fsConstants } from "node:fs";
+import { stat as statAsync, copyFile as copyFileAsync, constants as fsConstantsAsync } from "node:fs/promises";
+import { dirname, join as joinPath, basename as basenamePath } from "node:path";
+import { mkdirsSync } from "./mkdirs.js";
+import { mkdirs } from "./mkdirs.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 (destStat?.isDirectory()) {
+    destFinal = joinPath(dest, basenamePath(src));
+  }
+  const destExists = statSync(destFinal, { throwIfNoEntry: false });
+  if (destExists && !overwrite) {
+    throw new Error(`Destination ${destFinal} already exists and overwrite is false.`);
+  }
+  const destDir = dirname(destFinal);
+  mkdirsSync(destDir);
+  if (srcStat.isDirectory()) {
+    mkdirsSync(destFinal);
+  } else {
+    copyFileSync(src, destFinal, preserveTimestamps ? fsConstants.COPYFILE_FICLONE : 0);
+    if (preserveTimestamps) {
+      console.warn("preserveTimestamps: utimesSync is not implemented for the moment.");
+    }
+  }
+}
+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) {
+  }
+  let destFinal = dest;
+  const destStat = await statAsync(dest).catch((e) => {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  });
+  if (destStat?.isDirectory()) {
+    destFinal = joinPath(dest, basenamePath(src));
+  }
+  const destExists = await statAsync(destFinal).catch((e) => {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  });
+  if (destExists && !overwrite) {
+    throw new Error(`Destination ${destFinal} already exists and overwrite is false.`);
+  }
+  const destDir = dirname(destFinal);
+  await mkdirs(destDir);
+  if (srcStat?.isDirectory()) {
+    await mkdirs(destFinal);
+  } else {
+    await copyFileAsync(src, destFinal, preserveTimestamps ? fsConstantsAsync.COPYFILE_FICLONE : 0);
+    if (preserveTimestamps) {
+      console.warn("preserveTimestamps: utimes is not implemented for the moment.");
+    }
+  }
+}

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

@@ -0,0 +1,2 @@
+export declare function createFileSync(file: string, content?: string): void;
+export declare function createFile(file: string, content?: string): Promise<void>;

package/bin/impl/create-file.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { stat } 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;
+  }
+}

package/bin/impl/dive.d.ts

@@ -0,0 +1,17 @@
+import { statSync } from "node:fs";
+export interface DiveOptions {
+    all?: boolean;
+    recursive?: boolean;
+    directories?: boolean;
+    files?: boolean;
+    ignore?: string[] | RegExp;
+    depth?: number;
+}
+/**
+ * Synchronously walks a directory and yields each file and/or directory path.
+ *
+ * @param dir - The directory to walk.
+ * @param callbackOrOptions - A callback function to execute for each entry, or options object.
+ * @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>;

package/bin/impl/dive.js

@@ -0,0 +1,56 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function* diveSync(dir, callbackOrOptions, options) {
+  const currentDepth = 0;
+  let actualOptions = {
+    recursive: true,
+    files: true,
+    directories: false
+    // fs-extra's dive by default only yields files
+  };
+  let callback;
+  if (typeof callbackOrOptions === "function") {
+    callback = callbackOrOptions;
+    if (options) {
+      actualOptions = { ...actualOptions, ...options };
+    }
+  } else if (typeof callbackOrOptions === "object") {
+    actualOptions = { ...actualOptions, ...callbackOrOptions };
+  }
+  function* walk(currentPath, depth) {
+    if (actualOptions.depth !== void 0 && depth > actualOptions.depth) {
+      return;
+    }
+    const entries = readdirSync(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = join(currentPath, entry.name);
+      if (!actualOptions.all && entry.name.startsWith(".")) {
+        continue;
+      }
+      if (actualOptions.ignore) {
+        if (Array.isArray(actualOptions.ignore) && actualOptions.ignore.includes(entry.name)) {
+          continue;
+        }
+        if (actualOptions.ignore instanceof RegExp && actualOptions.ignore.test(entryPath)) {
+          continue;
+        }
+      }
+      const stat = statSync(entryPath);
+      if (entry.isFile()) {
+        if (actualOptions.files) {
+          if (callback) callback(entryPath, stat);
+          yield entryPath;
+        }
+      } else if (entry.isDirectory()) {
+        if (actualOptions.directories) {
+          if (callback) callback(entryPath, stat);
+          yield entryPath;
+        }
+        if (actualOptions.recursive) {
+          yield* walk(entryPath, depth + 1);
+        }
+      }
+    }
+  }
+  yield* walk(dir, currentDepth);
+}

package/bin/impl/empty-dir.d.ts

@@ -0,0 +1,2 @@
+export declare function emptyDirSync(dir: string): void;
+export declare function emptyDir(dir: string): Promise<void>;

package/bin/impl/empty-dir.js

@@ -0,0 +1,24 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { readdir, rm, stat } 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 });
+  }
+}

package/bin/impl/mkdirs.d.ts

@@ -0,0 +1,2 @@
+export declare function mkdirsSync(dir: string): string | undefined;
+export declare function mkdirs(dir: string): Promise<string | undefined>;

package/bin/impl/mkdirs.js

@@ -0,0 +1,19 @@
+import { mkdirSync, existsSync } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+export function mkdirsSync(dir) {
+  if (existsSync(dir)) {
+    return;
+  }
+  return mkdirSync(dir, { recursive: true });
+}
+export async function mkdirs(dir) {
+  try {
+    await stat(dir);
+    return void 0;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return mkdir(dir, { recursive: true });
+    }
+    throw error;
+  }
+}

package/bin/impl/move.d.ts

@@ -0,0 +1,15 @@
+export interface MoveOptions {
+    overwrite?: boolean;
+    /** @deprecated Use `overwrite`. */
+    clobber?: boolean;
+}
+/**
+ * Moves a file or directory. If the destination is a directory, the source is moved into it.
+ * If the destination exists and is a file, it will be overwritten if `overwrite` is true.
+ *
+ * @param src - The source path.
+ * @param dest - The destination path.
+ * @param options - Options for the move operation.
+ */
+export declare function moveSync(src: string, dest: string, options?: MoveOptions): void;
+export declare function move(src: string, dest: string, options?: MoveOptions): Promise<void>;

package/bin/impl/move.js

@@ -0,0 +1,93 @@
+import { renameSync, statSync, unlinkSync, copyFileSync } from "node:fs";
+import { rename, stat, unlink, copyFile } from "node:fs/promises";
+import { dirname, basename, join as joinPath } from "node:path";
+import { mkdirsSync } from "./mkdirs.js";
+import { mkdirs } from "./mkdirs.js";
+export function moveSync(src, dest, options = {}) {
+  let overwrite;
+  if (options.overwrite !== void 0) {
+    overwrite = options.overwrite;
+  } else if (options.clobber !== void 0) {
+    console.warn(
+      "Warning: The 'clobber' option in moveSync is deprecated and will be removed in a future version. Please use 'overwrite' instead."
+    );
+    overwrite = options.clobber;
+  } else {
+    overwrite = false;
+  }
+  const srcStat = statSync(src, { throwIfNoEntry: true });
+  if (!srcStat) {
+  }
+  let destFinal = dest;
+  const destStat = statSync(dest, { throwIfNoEntry: false });
+  if (destStat?.isDirectory()) {
+    destFinal = joinPath(dest, basename(src));
+  }
+  if (statSync(destFinal, { throwIfNoEntry: false }) && !overwrite) {
+    throw new Error(`Destination ${destFinal} already exists and overwrite is false.`);
+  }
+  const destDir = dirname(destFinal);
+  mkdirsSync(destDir);
+  try {
+    renameSync(src, destFinal);
+  } catch (err) {
+    if (err.code === "EXDEV") {
+      copyFileSync(src, destFinal);
+      unlinkSync(src);
+    } else if (err.code === "EISDIR" || err.code === "EPERM") {
+      copyFileSync(src, destFinal);
+      unlinkSync(src);
+    } else {
+      throw err;
+    }
+  }
+}
+export async function move(src, dest, options = {}) {
+  let overwrite;
+  if (options.overwrite !== void 0) {
+    overwrite = options.overwrite;
+  } else if (options.clobber !== void 0) {
+    console.warn(
+      "Warning: The 'clobber' option in move is deprecated and will be removed in a future version. Please use 'overwrite' instead."
+    );
+    overwrite = options.clobber;
+  } else {
+    overwrite = false;
+  }
+  const srcStat = await stat(src).catch((e) => {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  });
+  if (!srcStat) {
+  }
+  let destFinal = dest;
+  const destStat = await stat(dest).catch((e) => {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  });
+  if (destStat?.isDirectory()) {
+    destFinal = joinPath(dest, basename(src));
+  }
+  const destFinalStat = await stat(destFinal).catch((e) => {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  });
+  if (destFinalStat && !overwrite) {
+    throw new Error(`Destination ${destFinal} already exists and overwrite is false.`);
+  }
+  const destDir = dirname(destFinal);
+  await mkdirs(destDir);
+  try {
+    await rename(src, destFinal);
+  } catch (err) {
+    if (err.code === "EXDEV") {
+      await copyFile(src, destFinal);
+      await unlink(src);
+    } else if (err.code === "EISDIR" || err.code === "EPERM") {
+      await copyFile(src, destFinal);
+      await unlink(src);
+    } else {
+      throw err;
+    }
+  }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Ensures that the directory for the file exists and then writes the data to the file.
+ *
+ * @param file - The path to the file.
+ * @param data - The data to write.
+ * @param options - Options for writing the file (e.g., encoding, mode, flag).
+ */
+export declare function outputFileSync(file: string, data: string | Uint8Array, options?: unknown): void;
+/**
+ * Ensures that the directory for the file exists and then asynchronously writes the data to the file.
+ *
+ * @param file - The path to the file.
+ * @param data - The data to write.
+ * @param options - Options for writing the file (e.g., encoding, mode, flag).
+ */
+export declare function outputFile(file: string, data: string | Uint8Array, options?: unknown): Promise<void>;

package/bin/impl/output-file.js

@@ -0,0 +1,15 @@
+import { dirname } from "node:path";
+import { mkdirsSync } from "./mkdirs.js";
+import { mkdirs } from "./mkdirs.js";
+import { writeFileSync } from "./write-file.js";
+import { writeFile } from "./write-file.js";
+export function outputFileSync(file, data, options) {
+  const dir = dirname(file);
+  mkdirsSync(dir);
+  writeFileSync(file, data, options);
+}
+export async function outputFile(file, data, options) {
+  const dir = dirname(file);
+  await mkdirs(dir);
+  await writeFile(file, data, options);
+}

package/bin/impl/output-json.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ensures that the directory for the JSON file exists and then writes the JSON data to the file.
+ *
+ * @param file - The path to the file.
+ * @param data - The JSON data to write.
+ * @param options - Options for writing the JSON file (e.g., replacer, space).
+ */
+export declare function outputJsonSync(file: string, data: unknown, options?: unknown): void;
+/**
+ * Ensures that the directory for the JSON file exists and then asynchronously writes the JSON data to the file.
+ *
+ * @param file - The path to the file.
+ * @param data - The JSON data to write.
+ * @param options - Options for writing the JSON file (e.g., replacer, space).
+ */
+export declare function outputJson(file: string, data: unknown, options?: unknown): Promise<void>;

package/bin/impl/output-json.js

@@ -0,0 +1,15 @@
+import { dirname } from "node:path";
+import { mkdirsSync } from "./mkdirs.js";
+import { mkdirs } from "./mkdirs.js";
+import { writeJsonSync } from "./write-json.js";
+import { writeJson } from "./write-json.js";
+export function outputJsonSync(file, data, options) {
+  const dir = dirname(file);
+  mkdirsSync(dir);
+  writeJsonSync(file, data, options);
+}
+export async function outputJson(file, data, options) {
+  const dir = dirname(file);
+  await mkdirs(dir);
+  await writeJson(file, data, options);
+}

package/bin/impl/path-exists.d.ts

@@ -0,0 +1,2 @@
+export declare function pathExistsSync(path: string): boolean;
+export declare function pathExists(path: string): Promise<boolean>;

package/bin/impl/path-exists.js

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+export function pathExistsSync(path) {
+  return existsSync(path);
+}
+export async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}

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

@@ -0,0 +1,30 @@
+export interface ReadFileOptions {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+}
+/**
+ * Reads the entire contents of a file.
+ *
+ * @param path - The path to the file.
+ * @param options - Options for reading the file. Can be an encoding string or an object.
+ * @returns The file content as a string or Buffer.
+ */
+export declare function readFileSync(path: string, options: BufferEncoding | (ReadFileOptions & {
+    encoding: BufferEncoding;
+})): string;
+export declare function readFileSync(path: string, options?: (ReadFileOptions & {
+    encoding?: null;
+}) | null): Buffer;
+/**
+ * Asynchronously reads the entire contents of a file.
+ *
+ * @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 file content as a string or Buffer.
+ */
+export declare function readFile(path: string, options: BufferEncoding | (ReadFileOptions & {
+    encoding: BufferEncoding;
+})): Promise<string>;
+export declare function readFile(path: string, options?: (ReadFileOptions & {
+    encoding?: null;
+}) | null): Promise<Buffer>;

package/bin/impl/read-file.js

@@ -0,0 +1,30 @@
+import { readFileSync as nodeReadFileSync } from "node:fs";
+import { readFile as nodeReadFileAsync } from "node:fs/promises";
+export function readFileSync(path, options) {
+  let encoding;
+  let flag;
+  if (typeof options === "string") {
+    encoding = options;
+  } else if (options) {
+    encoding = options.encoding;
+    flag = options.flag;
+  }
+  if (encoding) {
+    return nodeReadFileSync(path, { encoding, flag });
+  }
+  return nodeReadFileSync(path, { encoding: null, flag });
+}
+export async function readFile(path, options) {
+  let encoding;
+  let flag;
+  if (typeof options === "string") {
+    encoding = options;
+  } else if (options) {
+    encoding = options.encoding;
+    flag = options.flag;
+  }
+  if (encoding) {
+    return nodeReadFileAsync(path, { encoding, flag });
+  }
+  return nodeReadFileAsync(path, { encoding: null, flag });
+}

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

@@ -0,0 +1,22 @@
+export interface ReadJsonOptions {
+    encoding?: BufferEncoding | null;
+    flag?: string;
+    reviver?: (key: string, value: unknown) => unknown;
+    throws?: boolean;
+}
+/**
+ * Reads a JSON file and then parses it into an object.
+ *
+ * @param file - The path to the file.
+ * @param options - Options for reading the file or parsing JSON. Can be an encoding string or an object.
+ * @returns The parsed JSON object.
+ */
+export declare function readJsonSync<T = unknown>(file: string, options?: BufferEncoding | ReadJsonOptions): T;
+/**
+ * Asynchronously reads a JSON file and then parses it into an object.
+ *
+ * @param file - The path to the file.
+ * @param options - Options for reading the file or parsing JSON. Can be an encoding string or an object.
+ * @returns A promise that resolves with the parsed JSON object.
+ */
+export declare function readJson<T = unknown>(file: string, options?: BufferEncoding | ReadJsonOptions): Promise<T>;

package/bin/impl/read-json.js

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+export function readJsonSync(file, options) {
+  let encoding = "utf8";
+  let reviver;
+  let throws = true;
+  if (typeof options === "string") {
+    encoding = options;
+  } else if (options) {
+    encoding = options.encoding ?? encoding;
+    reviver = options.reviver;
+    if (options.throws !== void 0) {
+      throws = options.throws;
+    }
+  }
+  try {
+    const data = readFileSync(file, { encoding });
+    return JSON.parse(data, reviver);
+  } catch (err) {
+    if (throws) {
+      throw err;
+    }
+    return void 0;
+  }
+}
+export async function readJson(file, options) {
+  let encoding = "utf8";
+  let reviver;
+  let throws = true;
+  let flag;
+  if (typeof options === "string") {
+    encoding = options;
+  } else if (options) {
+    encoding = options.encoding ?? encoding;
+    reviver = options.reviver;
+    flag = options.flag;
+    if (options.throws !== void 0) {
+      throws = options.throws;
+    }
+  }
+  try {
+    const data = await readFile(file, { encoding, flag });
+    return JSON.parse(data, reviver);
+  } catch (err) {
+    if (throws) {
+      throw err;
+    }
+    return void 0;
+  }
+}

package/bin/impl/remove.d.ts

@@ -0,0 +1,2 @@
+export declare function removeSync(path: string): void;
+export declare function remove(path: string): Promise<void>;

package/bin/impl/remove.js

@@ -0,0 +1,8 @@
+import { rmSync } from "node:fs";
+import { rm } from "node:fs/promises";
+export function removeSync(path) {
+  return rmSync(path, { recursive: true, force: true });
+}
+export async function remove(path) {
+  return rm(path, { recursive: true, force: true });
+}

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

@@ -0,0 +1,20 @@
+import { type PathLike } from "node:fs";
+export type WriteFileOptions = import("node:fs").WriteFileOptions;
+/**
+ * Synchronously writes data to a file, replacing the file if it already exists.
+ * Ensures the directory exists before writing.
+ *
+ * @param file - Path to the file.
+ * @param data - The data to write. If something other than a Buffer or Uint8Array is provided, it is converted to a string.
+ * @param options - Options for writing the file. Can be an encoding string or an object.
+ */
+export declare function writeFileSync(file: PathLike | number, data: string | NodeJS.ArrayBufferView, 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.
+ * @param data - The data to write. If something other than a Buffer or Uint8Array is provided, it is converted to a string.
+ * @param options - Options for writing the file. Can be an encoding string or an object.
+ */
+export declare function writeFile(file: PathLike | number, data: string | NodeJS.ArrayBufferView, options?: WriteFileOptions): Promise<void>;

package/bin/impl/write-file.js

@@ -0,0 +1,23 @@
+import { existsSync, mkdirSync, writeFileSync as nodeWriteFileSync } from "node:fs";
+import { mkdir, writeFile as nodeWriteFileAsync, stat } from "node:fs/promises";
+import path from "node:path";
+export function writeFileSync(file, data, options) {
+  const dir = path.dirname(file.toString());
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  nodeWriteFileSync(file, data, options);
+}
+export async function writeFile(file, data, options) {
+  const dir = path.dirname(file.toString());
+  try {
+    await stat(dir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await mkdir(dir, { recursive: true });
+    } else {
+      throw error;
+    }
+  }
+  return nodeWriteFileAsync(file, data, options);
+}