@liquid-labs/find-plus v1.0.1

find-plus

A zero-dependency file finder with features similar to Linux find.

Instalation

npm i @liquid-labs/find-plus

Usage

import { find } from '@liquid-labs/find-plus' // ESM
// const { find } = require('@liquid-labs/find-plus')  // CJS

const isaTXTFile = (f) => f.name.endsWith('.txt')
const files = find({ filesOnly: true, root: process.env.HOME, tests: [isaTXTFile] }

console.log(`You have ${files.length} text files under your home directory.`)

Options

find() takes the following options (only the root option is required):

Key options

• root: (required, string) the path from which to begin the search.
• noTraverseFailed: (boolean, default: false) by default, find will traverse directories even if the directories themselves are not included in the results (e.g., when onlyFiles is set to true). When noTraverseFailed is true, then directories which fail the requirements are not traversed. noTraverseFailed cannot be combined with noDirs or any of the only-options except onlyDirs because then the search would be trivially empty.
• sort: (string, default: 'breadth') specifies the sort to apply to the results. Possible options are 'breadth', 'depth', 'alpha', and 'none'. The 'none' option returns the order in which the files were discovered on disk and is primarily useful to speed things slightly when you don't care about the order.
• tests: (array of functions, default: []) an array of functions which take (dirEnt, depth) where dirEnt is a fs.DirEnt-like* object (may be a DirEnt or modified fs.Stats with name and path properties added) and depth is the depth of the file relative to the root (which is depth 0).

*: In Node 19.x, DirEnts lack the path field, but we normalize all DirEnts to include this field in all versions.

Depth and root handling options

• atDepth: (boolean, default: false) if true, then limits the results to those at depth.
• depth: (int, default: undefined) will only descend 'depth' directories past the search root (which is depth 0). Negatvie values are equivalent to 0.
• excludeRoot: (boolean, default: false) if true, then root is excluded from the search results.

No-options

The following options default to false and may be set true to exclude the particular type of file. Setting all the regular no-options to true will raise an error as the search would be trivially empty.

• noBlockDevices,
• noCharacterDevices,
• noDirs,
• noFIFOs,
• noFiles,
• noSockets,
• noSpecial: equivalent to noBlockDevcies, noCharacterDevices, noFIFOs, and noSockets,
• noSymbolicLinks

Only-options

The following options default to false and may be set 'true' to include only the particular type of file. Setting more than one only-option to true will raise an error as the search would be trivially empty.

• onlyBlockDevices,
• onlyCharacterDevices,
• onlyDirs,
• onlyFIFOs,
• onlyFiles,
• onlySockets,
• onlySymbolicLinks