https://github.com/opensly/is-empty-dir
A fast, reliable utility to check if a directory is empty or contains only files you want to ignore. Built with modern JavaScript and performance optimizations.
https://github.com/opensly/is-empty-dir
Last synced: 10 months ago
JSON representation
A fast, reliable utility to check if a directory is empty or contains only files you want to ignore. Built with modern JavaScript and performance optimizations.
- Host: GitHub
- URL: https://github.com/opensly/is-empty-dir
- Owner: opensly
- License: mit
- Created: 2025-07-17T11:39:17.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-22T12:11:01.000Z (11 months ago)
- Last Synced: 2025-07-22T14:19:23.180Z (11 months ago)
- Language: JavaScript
- Size: 4.88 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# is-empty-dir
A fast, reliable utility to check if a directory is empty or contains only files you want to ignore. Built with modern JavaScript and performance optimizations.
## Features
- **Fast**: Early exit optimization for large directories
- **Flexible**: Ignore files by name, RegExp, or custom function
- **Sync & Async**: Use in both callback and promise-based code
- **Cross-platform**: Works on Linux, macOS, and Windows
- **Supports CommonJS and ES Modules**
## Installation
```sh
npm install is-empty-dir
```
## Usage
### CommonJS
```js
const isEmptyDir = require('is-empty-dir');
(async () => {
const empty = await isEmptyDir('/path/to/dir');
console.log(empty); // true or false
})();
// Synchronous
const { isEmptyDirSync } = require('is-empty-dir');
const emptySync = isEmptyDirSync('/path/to/dir');
console.log(emptySync); // true or false
```
### ES Modules
```js
import isEmptyDir, { isEmptyDirSync } from 'is-empty-dir';
const empty = await isEmptyDir('/path/to/dir');
const emptySync = isEmptyDirSync('/path/to/dir');
```
## API
### `isEmptyDir(dirPath, options?)`
- `dirPath` (`string`): Path to the directory
- `options` (`object`, optional):
- `ignore` (`Array`): Patterns or functions to ignore files (default: `[]`)
- `followSymlinks` (`boolean`): Whether to follow symbolic links (default: `false`)
- **Returns**: `Promise`
### `isEmptyDirSync(dirPath, options?)`
- Same as above, but synchronous. Returns `boolean`.
#### Ignore Patterns
- **String**: Exact filename to ignore
- **RegExp**: Pattern to match filenames
- **Function**: `(filename) => boolean` custom logic
#### Example: Ignore dotfiles and `node_modules`
```js
const empty = await isEmptyDir('/dir', {
ignore: [/^\./, 'node_modules']
});
```
## Error Handling
- Throws if the path does not exist or is not a directory
- Throws on permission errors
## License
MIT © 2025 opensly
## Contributing
If you find a bug or have a feature request, please [raise an issue](https://github.com/opensly/is-empty-dir/issues).
Want to contribute? Fork the repository and [create a pull request](https://github.com/opensly/is-empty-dir/pulls) with your proposed changes!