@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/fs/read-dir.js

@@ -1,86 +1,109 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var read_dir_exports = {};
-__export(read_dir_exports, {
-  innerReadDirNames: () => innerReadDirNames,
-  readDirNames: () => readDirNames,
-  readDirNamesSync: () => readDirNamesSync
-});
-module.exports = __toCommonJS(read_dir_exports);
-var import_fs = require("../node/fs");
-var import_path = require("../node/path");
-var import_natural = require("../sorts/natural");
-var import_inspect = require("./inspect");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_node_fs = require('../node/fs.js');
+const require_node_path = require('../node/path.js');
+const require_sorts_natural = require('../sorts/natural.js');
+const require_fs_inspect = require('./inspect.js');
+
+//#region src/fs/read-dir.ts
+/**
+* @file Async/sync directory listing — returns directory names only (filtering
+*   out files), with optional emptiness suppression and natural-order sorting.
+*   Glob-based ignore patterns are evaluated only when `includeEmpty: false`
+*   triggers a per-entry emptiness probe.
+*/
+/**
+* Process directory entries and filter for directories. Filters entries to
+* include only directories, optionally excluding empty ones. Applies ignore
+* patterns and natural sorting.
+*
+* @param dirents - Directory entries from readdir.
+* @param dirname - Parent directory path.
+* @param options - Filtering and sorting options.
+*
+* @returns Array of directory names, optionally sorted
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function innerReadDirNames(dirents, dirname, options) {
-  const {
-    ignore,
-    includeEmpty = true,
-    sort = true
-  } = { __proto__: null, ...options };
-  const path = (0, import_path.getNodePath)();
-  const names = dirents.filter(
-    (d) => d.isDirectory() && (includeEmpty || !(0, import_inspect.isDirEmptySync)(path.join(dirname || d.parentPath, d.name), {
-      ignore
-    }))
-  ).map((d) => d.name);
-  return sort ? names.sort(import_natural.naturalCompare) : names;
+	const { ignore, includeEmpty = true, sort = true } = {
+		__proto__: null,
+		...options
+	};
+	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const names = dirents.filter((d) => d.isDirectory() && (includeEmpty || !/* @__PURE__ */ require_fs_inspect.isDirEmptySync(path.join(dirname || d.parentPath, d.name), { ignore }))).map((d) => d.name);
+	return sort ? names.sort(require_sorts_natural.naturalCompare) : names;
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Read directory names asynchronously with filtering and sorting. Returns only
+* directory names (not files), with optional filtering for empty directories
+* and glob-based ignore patterns. Results are naturally sorted by default.
+*
+* @example
+*   ;```ts
+*   // Get all subdirectories, sorted naturally
+*   const dirs = await readDirNames('./packages')
+*
+*   // Get non-empty directories only
+*   const nonEmpty = await readDirNames('./cache', { includeEmpty: false })
+*
+*   // Get directories without sorting
+*   const unsorted = await readDirNames('./src', { sort: false })
+*   ```
+*
+* @param dirname - Directory path to read.
+* @param options - Options for filtering and sorting.
+*
+* @returns Array of directory names, empty array on error
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function readDirNames(dirname, options) {
-  const fs = (0, import_fs.getNodeFs)();
-  try {
-    return /* @__PURE__ */ innerReadDirNames(
-      await fs.promises.readdir(dirname, {
-        __proto__: null,
-        encoding: "utf8",
-        withFileTypes: true
-      }),
-      String(dirname),
-      options
-    );
-  } catch {
-  }
-  return [];
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	try {
+		return /* @__PURE__ */ innerReadDirNames(await fs.promises.readdir(dirname, {
+			__proto__: null,
+			encoding: "utf8",
+			withFileTypes: true
+		}), String(dirname), options);
+	} catch {}
+	return [];
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Read directory names synchronously with filtering and sorting. Returns only
+* directory names (not files), with optional filtering for empty directories
+* and glob-based ignore patterns. Results are naturally sorted by default.
+*
+* @example
+*   ;```ts
+*   // Get all subdirectories, sorted naturally
+*   const dirs = readDirNamesSync('./packages')
+*
+*   // Get non-empty directories only, ignoring node_modules
+*   const nonEmpty = readDirNamesSync('./src', {
+*     includeEmpty: false,
+*     ignore: ['node_modules'],
+*   })
+*   ```
+*
+* @param dirname - Directory path to read.
+* @param options - Options for filtering and sorting.
+*
+* @returns Array of directory names, empty array on error
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function readDirNamesSync(dirname, options) {
-  const fs = (0, import_fs.getNodeFs)();
-  try {
-    return /* @__PURE__ */ innerReadDirNames(
-      fs.readdirSync(dirname, {
-        __proto__: null,
-        encoding: "utf8",
-        withFileTypes: true
-      }),
-      String(dirname),
-      options
-    );
-  } catch {
-  }
-  return [];
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	try {
+		return /* @__PURE__ */ innerReadDirNames(fs.readdirSync(dirname, {
+			__proto__: null,
+			encoding: "utf8",
+			withFileTypes: true
+		}), String(dirname), options);
+	} catch {}
+	return [];
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  innerReadDirNames,
-  readDirNames,
-  readDirNamesSync
-});
+
+//#endregion
+exports.innerReadDirNames = innerReadDirNames;
+exports.readDirNames = readDirNames;
+exports.readDirNamesSync = readDirNamesSync;

package/dist/fs/read-file.js

@@ -1,131 +1,190 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var read_file_exports = {};
-__export(read_file_exports, {
-  readFileBinary: () => readFileBinary,
-  readFileBinarySync: () => readFileBinarySync,
-  readFileUtf8: () => readFileUtf8,
-  readFileUtf8Sync: () => readFileUtf8Sync,
-  safeReadFile: () => safeReadFile,
-  safeReadFileSync: () => safeReadFileSync
-});
-module.exports = __toCommonJS(read_file_exports);
-var import_abort = require("../process/abort");
-var import_fs = require("../node/fs");
-var import_buffer = require("../primordials/buffer");
-var import_encoding = require("./encoding");
-const abortSignal = (0, import_abort.getAbortSignal)();
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_buffer = require('../primordials/buffer.js');
+const require_node_fs = require('../node/fs.js');
+const require_process_abort = require('../process/abort.js');
+const require_fs_encoding = require('./encoding.js');
+
+//#region src/fs/read-file.ts
+/**
+* @file File-content readers — UTF-8 / binary / safe variants (sync + async).
+*   The `safe*` versions trap errors and return `undefined` (or a
+*   caller-supplied `defaultValue`) so they fit the non-throwing-fallback shape
+*   used elsewhere in the lib. The encoding `null` overload returns a `Buffer`;
+*   the default and any string encoding return a string. The runtime fast-path
+*   normalizes encoding once and forwards untouched options to `node:fs`.
+*/
+const abortSignal = require_process_abort.getAbortSignal();
+/**
+* Read a file as binary data asynchronously. Returns a Buffer without encoding
+* the contents. Useful for reading images, archives, or other binary formats.
+*
+* @example
+*   ;```ts
+*   // Read an image file
+*   const imageBuffer = await readFileBinary('./image.png')
+*
+*   // Read with abort signal
+*   const buffer = await readFileBinary('./data.bin', { signal: abortSignal })
+*   ```
+*
+* @param filepath - Path to file.
+* @param options - Read options (encoding is forced to null for binary)
+*
+* @returns Promise resolving to Buffer containing file contents
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function readFileBinary(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
-  const fs = (0, import_fs.getNodeFs)();
-  return await fs.promises.readFile(filepath, {
-    signal: abortSignal,
-    ...opts,
-    encoding: void 0
-  });
+	const opts = typeof options === "string" ? { encoding: options } : options;
+	return await (/* @__PURE__ */ require_node_fs.getNodeFs()).promises.readFile(filepath, {
+		signal: abortSignal,
+		...opts,
+		encoding: void 0
+	});
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Read a file as binary data synchronously. Returns a Buffer without encoding
+* the contents. Useful for reading images, archives, or other binary formats.
+*
+* @example
+*   ;```ts
+*   // Read an image file
+*   const imageBuffer = readFileBinarySync('./logo.png')
+*
+*   // Read a compressed file
+*   const gzipData = readFileBinarySync('./archive.gz')
+*   ```
+*
+* @param filepath - Path to file.
+* @param options - Read options (encoding is forced to null for binary)
+*
+* @returns Buffer containing file contents
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function readFileBinarySync(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
-  const fs = (0, import_fs.getNodeFs)();
-  return fs.readFileSync(filepath, {
-    ...opts,
-    encoding: void 0
-  });
+	const opts = typeof options === "string" ? { encoding: options } : options;
+	return (/* @__PURE__ */ require_node_fs.getNodeFs()).readFileSync(filepath, {
+		...opts,
+		encoding: void 0
+	});
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Read a file as UTF-8 text asynchronously. Returns a string with the file
+* contents decoded as UTF-8. This is the most common way to read text files.
+*
+* @example
+*   ;```ts
+*   // Read a text file
+*   const content = await readFileUtf8('./README.md')
+*
+*   // Read with custom encoding
+*   const content = await readFileUtf8('./data.txt', { encoding: 'utf-8' })
+*   ```
+*
+* @param filepath - Path to file.
+* @param options - Read options including encoding and abort signal.
+*
+* @returns Promise resolving to string containing file contents
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function readFileUtf8(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
-  const fs = (0, import_fs.getNodeFs)();
-  return await fs.promises.readFile(filepath, {
-    signal: abortSignal,
-    ...opts,
-    encoding: "utf8"
-  });
+	const opts = typeof options === "string" ? { encoding: options } : options;
+	return await (/* @__PURE__ */ require_node_fs.getNodeFs()).promises.readFile(filepath, {
+		signal: abortSignal,
+		...opts,
+		encoding: "utf8"
+	});
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Read a file as UTF-8 text synchronously. Returns a string with the file
+* contents decoded as UTF-8. This is the most common way to read text files
+* synchronously.
+*
+* @example
+*   ;```ts
+*   // Read a configuration file
+*   const config = readFileUtf8Sync('./config.txt')
+*
+*   // Read with custom options
+*   const data = readFileUtf8Sync('./data.txt', { encoding: 'utf8' })
+*   ```
+*
+* @param filepath - Path to file.
+* @param options - Read options including encoding.
+*
+* @returns String containing file contents
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function readFileUtf8Sync(filepath, options) {
-  const opts = typeof options === "string" ? { encoding: options } : options;
-  const fs = (0, import_fs.getNodeFs)();
-  return fs.readFileSync(filepath, {
-    ...opts,
-    encoding: "utf8"
-  });
+	const opts = typeof options === "string" ? { encoding: options } : options;
+	return (/* @__PURE__ */ require_node_fs.getNodeFs()).readFileSync(filepath, {
+		...opts,
+		encoding: "utf8"
+	});
 }
-// @__NO_SIDE_EFFECTS__
+/* @__NO_SIDE_EFFECTS__ */
 async function safeReadFile(filepath, options) {
-  const opts = typeof options === "string" ? { __proto__: null, encoding: options } : { __proto__: null, ...options };
-  const { defaultValue, ...rawReadOpts } = opts;
-  const readOpts = { __proto__: null, ...rawReadOpts };
-  const shouldReturnBuffer = readOpts.encoding === null;
-  const encoding = shouldReturnBuffer ? void 0 : (0, import_encoding.normalizeEncoding)(readOpts.encoding);
-  const fs = (0, import_fs.getNodeFs)();
-  try {
-    return await fs.promises.readFile(filepath, {
-      __proto__: null,
-      signal: abortSignal,
-      ...readOpts,
-      encoding
-    });
-  } catch {
-  }
-  if (defaultValue === void 0) {
-    return void 0;
-  }
-  if (shouldReturnBuffer) {
-    return (0, import_buffer.BufferIsBuffer)(defaultValue) ? defaultValue : void 0;
-  }
-  return typeof defaultValue === "string" ? defaultValue : String(defaultValue);
+	const { defaultValue, ...rawReadOpts } = typeof options === "string" ? {
+		__proto__: null,
+		encoding: options
+	} : {
+		__proto__: null,
+		...options
+	};
+	const readOpts = {
+		__proto__: null,
+		...rawReadOpts
+	};
+	const shouldReturnBuffer = readOpts.encoding === null;
+	/* c8 ignore next 3 */
+	const encoding = shouldReturnBuffer ? void 0 : /* @__PURE__ */ require_fs_encoding.normalizeEncoding(readOpts.encoding);
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	try {
+		return await fs.promises.readFile(filepath, {
+			__proto__: null,
+			signal: abortSignal,
+			...readOpts,
+			encoding
+		});
+	} catch {}
+	if (defaultValue === void 0) return;
+	if (shouldReturnBuffer) return require_primordials_buffer.BufferIsBuffer(defaultValue) ? defaultValue : void 0;
+	return typeof defaultValue === "string" ? defaultValue : String(defaultValue);
 }
-// @__NO_SIDE_EFFECTS__
+/* @__NO_SIDE_EFFECTS__ */
 function safeReadFileSync(filepath, options) {
-  const opts = typeof options === "string" ? { __proto__: null, encoding: options } : { __proto__: null, ...options };
-  const { defaultValue, ...rawReadOpts } = opts;
-  const readOpts = { __proto__: null, ...rawReadOpts };
-  const shouldReturnBuffer = readOpts.encoding === null;
-  const encoding = shouldReturnBuffer ? void 0 : (0, import_encoding.normalizeEncoding)(readOpts.encoding);
-  const fs = (0, import_fs.getNodeFs)();
-  try {
-    return fs.readFileSync(filepath, {
-      __proto__: null,
-      ...readOpts,
-      encoding
-    });
-  } catch {
-  }
-  if (defaultValue === void 0) {
-    return void 0;
-  }
-  if (shouldReturnBuffer) {
-    return (0, import_buffer.BufferIsBuffer)(defaultValue) ? defaultValue : void 0;
-  }
-  return typeof defaultValue === "string" ? defaultValue : String(defaultValue);
+	const { defaultValue, ...rawReadOpts } = typeof options === "string" ? {
+		__proto__: null,
+		encoding: options
+	} : {
+		__proto__: null,
+		...options
+	};
+	const readOpts = {
+		__proto__: null,
+		...rawReadOpts
+	};
+	const shouldReturnBuffer = readOpts.encoding === null;
+	/* c8 ignore next 3 */
+	const encoding = shouldReturnBuffer ? void 0 : /* @__PURE__ */ require_fs_encoding.normalizeEncoding(readOpts.encoding);
+	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	try {
+		return fs.readFileSync(filepath, {
+			__proto__: null,
+			...readOpts,
+			encoding
+		});
+	} catch {}
+	if (defaultValue === void 0) return;
+	if (shouldReturnBuffer) return require_primordials_buffer.BufferIsBuffer(defaultValue) ? defaultValue : void 0;
+	return typeof defaultValue === "string" ? defaultValue : String(defaultValue);
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  readFileBinary,
-  readFileBinarySync,
-  readFileUtf8,
-  readFileUtf8Sync,
-  safeReadFile,
-  safeReadFileSync
-});
+
+//#endregion
+exports.readFileBinary = readFileBinary;
+exports.readFileBinarySync = readFileBinarySync;
+exports.readFileUtf8 = readFileUtf8;
+exports.readFileUtf8Sync = readFileUtf8Sync;
+exports.safeReadFile = safeReadFile;
+exports.safeReadFileSync = safeReadFileSync;