Interface LsOptions

Specifies the character encoding to be used for the output encoding of returned entries.

Default Value

'utf8'

Since

0.1.0

A boolean flag indicating whether to include subdirectories in the listing.

Default Value

false

Since

0.1.0

A regular expression or string pattern used to filter the listed entries. Only entries matching the pattern will be included in the results.

Default Value

/.+/ (match all files)

Since

0.1.0

A regular expression or string pattern used to exclude entries from the listing. Any entries matching this pattern will be filtered out of the results, even if they match the match pattern.

Default Value

undefined

Since

0.1.0

A string path representing the root directory to resolve the results to relative paths.

This option will be ignored if either one of the absolute or basename option are enabled, this is due to their higher priority. This option have the lowest priority when compared with those options.

Default Value

'.' or process.cwd()

Since

1.0.0

Determines whether to return absolute paths for all entries.

When enabled (i.e., set to true), each entry of the returned results will be an absolute path. Otherwise, paths will be relative to the directory specified in the rootDir field.

Enabling this option are equivalent with the following code. Let's assume we want to list all files within a directory named 'foo':

const { resolve } = require('node:path');
const { lsFiles } = require('lsfnd');
// Or ESM:
// import { resolve } from 'node:path';
// import { lsFiles } from 'lsfnd';

const absfiles = (await lsFiles('foo/')).map((entry) => resolve(entry));
Copy

In previous release (prior to version 0.1.0) you can literally use an explicit method that makes the returned results as absolute paths entirely. That is by utilizing the path.resolve function, here is an example:

const absfiles = await lsFiles(path.resolve('foo/'));
Copy

In the above code, the directory path is resolved to an absolute path before being passed to the lsFiles function. As a result, the function treats the specified directory path as a relative path and does not attempt to resolve it back to a relative path, thus returning absolute paths. This approach was considered unstable and problematic due to inconsistencies in the internal logic. Therefore, this option was introduced as a replacement and will default returns relative paths when this option are disabled (set to false or unspecified), they will relative to the path specified in the rootDir field. Refer to rootDir option for more details.

Default Value

false

Since

1.0.0

See

rootDir

Whether to make the returned result paths only have their basenames, trimming any directories behind the path separator (i.e., \\ in Windows, and / in POSIX).

When set to true, the returned paths will only include the file and/or directory names itself. This can be useful if you need only the names while listing a directory.

If you enabled both this option and the absolute option, the absolute option will be treated instead due to its higher priority rather than this option's priority.

Note

Please note, that this option implicitly includes any directories on the returned entries. If you want to only include the filenames, then combine this option with LS_F type if you are using ls function, or use this option with lsFiles function for better flexibility.

This option achieves the same functionality as the following code:

const path = require('node:path');
// Or ESM:
// import * as path from 'node:path';

// Assume you have `results` variable contains all files paths
// from listing a directory using `lsFiles` function
const baseResults = results.map((res) => res.split(path.sep).pop());
Copy

Or even a bit more simple like this:

// ...
const baseResults = results.map((res) => path.basename(res));
Copy

Default Value

false

Since

1.0.0

See

rootDir