index.js

const { opendir, stat } = require("fs/promises");
const { opendirSync, statSync } = require("fs");

/**
 * Check if a directory is empty (async)
 * @param {string|string[]} dirPath - Path(s) to directory to check
 * @param {Object|Function} [options] - Options object or callback
 * @param {Array<string|RegExp|Function>} [options.ignore] - Patterns to ignore
 * @param {boolean} [options.followSymlinks] - Whether to follow symbolic links
 * @param {Function} [callback] - Node-style callback: (err, result) => void
 * @returns {Promise<boolean>|undefined} - Promise result or undefined when callback is used
 */
function isEmptyDir(dirPath, options = {}, callback) {
  if (typeof options === "function") {
    callback = options;
    options = {};
  }

  if (callback !== undefined && typeof callback !== "function") {
    throw new TypeError("Expected callback to be a function");
  }

  const promise = isEmptyDirCore(dirPath, options);

  if (callback) {
    promise.then((result) => callback(null, result)).catch((error) => callback(error));
    return undefined;
  }

  return promise;
}

async function isEmptyDirCore(dirPath, options = {}) {
  const { ignore = [], followSymlinks = false } = options;

  validateDirPathInput(dirPath);

  if (Array.isArray(dirPath)) {
    for (const singlePath of dirPath) {
      const isEmpty = await isEmptySingleDir(singlePath, { ignore, followSymlinks });
      if (!isEmpty) {
        return false;
      }
    }
    return true;
  }

  return isEmptySingleDir(dirPath, { ignore, followSymlinks });
}

/**
 * Check if a directory is empty (sync)
 * @param {string|string[]} dirPath - Path(s) to directory to check
 * @param {Object} [options] - Options object
 * @param {Array<string|RegExp|Function>} [options.ignore] - Patterns to ignore
 * @param {boolean} [options.followSymlinks] - Whether to follow symbolic links
 * @returns {boolean} - True if ALL given directories are empty or only contain ignored files
 */
function isEmptyDirSync(dirPath, options = {}) {
  const { ignore = [], followSymlinks = false } = options;

  validateDirPathInput(dirPath);

  if (Array.isArray(dirPath)) {
    return dirPath.every((singlePath) => isEmptySingleDirSync(singlePath, { ignore, followSymlinks }));
  }

  return isEmptySingleDirSync(dirPath, { ignore, followSymlinks });
}

async function isEmptySingleDir(dirPath, { ignore, followSymlinks }) {
  let stats;
  try {
    stats = await stat(dirPath);
  } catch (error) {
    throw mapFsError(error, dirPath);
  }

  if (!stats.isDirectory()) {
    throw new Error(`Path is not a directory: ${dirPath}`);
  }

  let dir;
  try {
    dir = await opendir(dirPath);
  } catch (error) {
    throw mapFsError(error, dirPath);
  }

  try {
    // Iterate lazily so large directories can short-circuit early.
    for await (const file of dir) {
      if (shouldIgnore(file.name, ignore)) {
        continue;
      }

      if (!followSymlinks && file.isSymbolicLink()) {
        continue;
      }

      return false; // Found an entry that shouldn't be ignored
    }
  } finally {
    await closeDir(dir);
  }

  return true;
}

function isEmptySingleDirSync(dirPath, { ignore, followSymlinks }) {
  let stats;
  try {
    stats = statSync(dirPath);
  } catch (error) {
    throw mapFsError(error, dirPath);
  }

  if (!stats.isDirectory()) {
    throw new Error(`Path is not a directory: ${dirPath}`);
  }

  let dir;
  try {
    dir = opendirSync(dirPath);
  } catch (error) {
    throw mapFsError(error, dirPath);
  }

  try {
    let file;
    while ((file = dir.readSync()) !== null) {
      if (shouldIgnore(file.name, ignore)) {
        continue;
      }

      if (!followSymlinks && file.isSymbolicLink()) {
        continue;
      }

      return false; // Found an entry that shouldn't be ignored
    }
  } finally {
    closeDirSync(dir);
  }

  return true;
}

function shouldIgnore(filename, ignorePatterns) {
  if (!Array.isArray(ignorePatterns)) {
    return false;
  }

  return ignorePatterns.some((pattern) => {
    if (typeof pattern === "string") {
      return filename === pattern;
    }
    if (pattern instanceof RegExp) {
      return pattern.test(filename);
    }
    if (typeof pattern === "function") {
      return pattern(filename);
    }
    throw new TypeError(
      `ignore patterns must be a string, RegExp, or function; got ${typeof pattern}`,
    );
  });
}

function validateDirPathInput(dirPath) {
  if (!(typeof dirPath === "string" || Array.isArray(dirPath))) {
    throw new TypeError("Expected dirPath to be a string or an array of strings");
  }

  if (typeof dirPath === "string") {
    if (dirPath.length === 0) {
      throw new TypeError("Expected dirPath to be a non-empty string");
    }
    return;
  }

  if (dirPath.length === 0) {
    throw new TypeError("Expected dirPath array to contain at least one path");
  }

  for (const currentPath of dirPath) {
    if (typeof currentPath !== "string" || currentPath.length === 0) {
      throw new TypeError("Expected each dirPath entry to be a non-empty string");
    }
  }
}

function mapFsError(error, targetPath) {
  if (error && error.code === "ENOENT") {
    return new Error(`Directory does not exist: ${targetPath}`);
  }
  if (error && (error.code === "EACCES" || error.code === "EPERM")) {
    return new Error(`Permission denied: ${targetPath}`);
  }
  return error;
}

async function closeDir(dir) {
  try {
    await dir.close();
  } catch {
    // Ignore close errors; iteration already produced the meaningful failure.
  }
}

function closeDirSync(dir) {
  try {
    dir.closeSync();
  } catch {
    // Ignore close errors; iteration already produced the meaningful failure.
  }
}

// CommonJS exports
module.exports = isEmptyDir;
module.exports.isEmptyDir = isEmptyDir;
module.exports.isEmptyDirSync = isEmptyDirSync;

// ES modules exports (will be handled by build script)
module.exports.default = isEmptyDir;