als-file-list v0.4.0

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:

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.

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:

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:

[
  'dev',     'mode',
  'nlink',   'uid',
  'gid',     'rdev',
  'blksize', 'ino',
  'size',    'blocks',
  'atimeMs', 'mtimeMs',
  'ctimeMs', 'birthtimeMs',
  'atime',   'mtime',
  'ctime',   'birthtime'
]