als-file-list/readme.md

Generates filtered and sorted list of all file paths in a directory and its subdirectories.

# als-file-list

`als-file-list` is a Node.js package providing functions to generate filtered and sorted list of all file paths in a given directory and its subdirectories up to defined level. 
It supports both synchronous and asynchronous operations and is compatible with ES Modules and CommonJS.

## Installation

Install `als-file-list` using npm:

```bash
npm install als-file-list
```

## Basic usage

The `fileList` and `fileListSync` functions return an array of file paths relative to the specified directory, providing a convenient way to get a snapshot of all files within a directory structure.

```javascript
import { fileList, fileListSync } from "als-file-list";
// or
const { fileList, fileListSync } = require("als-file-list");

const dirPath = "/path/to/directory"

// Asynchronous
(async () => {
  const files = await fileList(dirPath);
  console.log(files); // array of file paths relative to dirPath
})();

// Synchronous
const files = fileListSync(dirPath);
console.log(files); // array of file paths relative to dirPath
```

## Advanced usage

The `fileList` function has two more parameters in addition to `dirPath`:

- `options`: Object with following properties
  - `level` (number, optional): The maximum depth level of directory traversal. Defaults to `Infinity`, which means all subdirectories are explored.
  - `level=0` - root
  - `where` (function, optional): A filter function applied to each file and directory. It must return `true` to include the file/directory in the result. 
    - Function parameters:
      - `relativePath` (string) - The relative path to `dirPath`
      - `stats` (object) - The file system statistics object
      - `isDir` (boolean) - `true` if the path is a directory, `false` if it's a file
  - `select` (string, optional): A space-separated string defining which file attributes should be included in the result.
    - If specified, the result is an array of objects with `{relativePath}` and the selected attributes.
  - `limit` (number, optional): The maximum number of files to return. Defaults to `Infinity`.
  - `sort` (string, optional): The attribute to sort the results by.
  - `skip` (number, optional): Number of files to skip before starting to add files to the result.
- `errors` (array, optional): An array to which any errors encountered during the function's execution will be added.

Example:

```js
const { fileList } = require('als-file-list');

async function exampleUsage() {
  const dirPath = '/path/to/directory';
  const errors = [];
  const options = {
    level: 2, // Traverse up to level 2
    where: (relativePath, stats, isDir) => isDir || stats.size > 1024, // Only files larger than 1024 bytes
    select: 'atimeMs mtimeMs', // Return {relativePath, atimeMs, mtimeMs}
    limit: 10,
    sort: 'mtimeMs',
    skip: 2
  };
  const files = await fileList(dirPath, options, errors);
  if (errors.length > 0) {
    console.error(errors);
  }
  console.log(files);
}

exampleUsage();
```

> On `select` use, returned result include array of objects with {relativPath,...selectedKeys}
> In the `where` function, you receive both folders and files. You must return `true` for `isDir` if you want to include folders. The `stats` object includes all file system statistics properties (like `mtime`, `birthtime`, `ino`, etc.)

Typically, the `stats` object includes properties such as:
```js
[
  'dev',     'mode',
  'nlink',   'uid',
  'gid',     'rdev',
  'blksize', 'ino',
  'size',    'blocks',
  'atimeMs', 'mtimeMs',
  'ctimeMs', 'birthtimeMs',
  'atime',   'mtime',
  'ctime',   'birthtime'
]
```