Readonly
This option lists both regular files and directories in the output. +You can also use other number types for alias, like:
+LS_A: 0b01 | 0o01 | 0x01 // Each equivalent to 1
+
+This option filters the output to include only directory entries. +You can also use other number types for alias, like:
+LS_D: 0b10 | 0o02 | 0x02 // Each equivalent to 2
+
+This option filters the output to include only regular files (non-directories). +You can also use other number types for alias, like:
+LS_F: 0b100 | 0o04 | 0x04 // Each equivalent to 4
+
+Generated using TypeDoc v0.25.12
+
+
+
Lists files and/or directories in a specified directory path, filtering by a +regular expression pattern.
+The returned entries are configurable using the additional options, +such as listing recursively to subdirectories, and filter specific file and/or +directory names using a regular expression.
+The additional options
can be an object or a regex pattern to specify only
+the match field. If passed as a RegExp
object, the rest
+options (except the match
field) for reading the directory will uses default options.
If the options
argument not specified (or undefined
), then it uses the
+default value:
[LsOptions]: {
encoding: 'utf8',
recursive: false,
match: /.+/,
exclude: undefined
}
+
+As of version 1.0.0, this function now accepts file URL paths. This can be
+either a string URL path or a URL
object, and it must follow the 'file:'
protocol.
+An URIError
will be thrown if the specified file URL path has invalid file
+URL syntax or is used with unsupported protocols.
Added in version 0.1.0.
+The directory path to search, must be a Node path + (i.e., similar to POSIX path) or a valid file URL path.
+Optional
options: RegExp | LsOptionsAdditional options for reading the directory. Refer to + LsOptions documentation for more details.
+Optional
type: LsTypesA type to specify the returned file system type to be included.
+ If not specified or set to 0
, then it will includes all types
+ (including regular files and directories).
+ See lsTypes to check all supported types.
A promise that resolves with an array of string representing the
+ entries result excluding '.'
and '..'
or an empty array ([]
)
+ if any files and directories does not match with the specified filter options.
Error - + If there is an error occurred while reading a directory.
+URIError - + If the given URL path contains invalid file URL scheme or using + unsupported protocols.
+// List all installed packages in 'node_modules' directory
ls('node_modules', { exclude: /\.bin/ }, lsTypes.LS_D)
.then((dirs) => console.log(dirs));
+
+// List current directory using an URL object
const { pathToFileURL } = require('node:url');
// ESM: import { pathToFileURL } from 'node:url';
ls(pathToFileURL('.')).then((entries) =>
console.log(entries));
+
+0.1.0
+Generated using TypeDoc v0.25.12
+
+
+
Lists files in the specified directory path, filtering by a regular +expression pattern.
+The returned entries are configurable using the additional options, +such as listing recursively to subdirectories, and filter specific file and/or +directory names using a regular expression.
+The additional options
can be an object or a regex pattern to specify only
+the match field. If passed as a RegExp
object, the rest
+options (except the match
field) for reading the directory will uses default options.
If the options
argument not specified (or undefined
), then it uses the
+default value:
[LsOptions]: {
encoding: 'utf8',
recursive: false,
match: /.+/,
exclude: undefined
}
+
+As of version 1.0.0, this function now accepts file URL paths. This can be
+either a string URL path or a URL
object, and it must follow the 'file:'
protocol.
+An URIError
will be thrown if the specified file URL path has invalid file
+URL syntax or is used with unsupported protocols.
Added in version 0.1.0.
+A promise that resolves with an array of string representing the
+ entries result excluding '.'
and '..'
or an empty array ([]
)
+ if any files and directories does not match with the specified filter options.
Error - + If there is an error occurred while reading a directory.
+URIError - + If the given URL path contains invalid file URL scheme or using + unsupported protocols.
+// Search and list directory named 'foo' in 'src' directory
lsDirs('src', {
recursive: false,
match: /[\/\\]\bfoo\b/,
}).then((files) => console.log(files));
+
+0.1.0
+Generated using TypeDoc v0.25.12
+
+
+
Lists files in the specified directory path, filtering by a regular +expression pattern.
+The returned entries are configurable using the additional options, +such as listing recursively to subdirectories, and filter specific file and/or +directory names using a regular expression.
+The additional options
can be an object or a regex pattern to specify only
+the match field. If passed as a RegExp
object, the rest
+options (except the match
field) for reading the directory will uses default options.
If the options
argument not specified (or undefined
), then it uses the
+default value:
[LsOptions]: {
encoding: 'utf8',
recursive: false,
match: /.+/,
exclude: undefined
}
+
+As of version 1.0.0, this function now accepts file URL paths. This can be
+either a string URL path or a URL
object, and it must follow the 'file:'
protocol.
+An URIError
will be thrown if the specified file URL path has invalid file
+URL syntax or is used with unsupported protocols.
Added in version 0.1.0.
+A promise that resolves with an array of string representing the
+ entries result excluding '.'
and '..'
or an empty array ([]
)
+ if any files and directories does not match with the specified filter options.
Error - + If there is an error occurred while reading a directory.
+URIError - + If the given URL path contains invalid file URL scheme or using + unsupported protocols.
+// List all JavaScript files in current directory recursively,
// but excluding files from 'tests' directory
lsFiles('.', {
recursive: true,
match: /.+\.[cm]*js$/,
exclude: /[\/\\]\btests\b[\/\\]/
}).then((files) => console.log(files));
+
+0.1.0
+Generated using TypeDoc v0.25.12
+
+
+
Lists files and/or directories in a specified directory path, filtering by a +regular expression pattern.
+The returned entries are configurable using the additional options, +such as listing recursively to subdirectories, and filter specific file and/or +directory names using a regular expression.
+The additional options
can be an object or a regex pattern to specify only
+the match field. If passed as a RegExp
object, the rest
+options (except the match
field) for reading the directory will uses default options.
If the options
argument not specified (or undefined
), then it uses the
+default value:
[LsOptions]: {
encoding: 'utf8',
recursive: false,
match: /.+/,
exclude: undefined
}
+
+As of version 1.0.0, this function now accepts file URL paths. This can be
+either a string URL path or a URL
object, and it must follow the 'file:'
protocol.
+An URIError
will be thrown if the specified file URL path has invalid file
+URL syntax or is used with unsupported protocols.
Added in version 0.1.0.
+The directory path to search, must be a Node path + (i.e., similar to POSIX path) or a valid file URL path.
+Optional
options: RegExp | LsOptionsAdditional options for reading the directory. Refer to + LsOptions documentation for more details.
+Optional
type: LsTypesA type to specify the returned file system type to be included.
+ If not specified or set to 0
, then it will includes all types
+ (including regular files and directories).
+ See lsTypes to check all supported types.
A promise that resolves with an array of string representing the
+ entries result excluding '.'
and '..'
or an empty array ([]
)
+ if any files and directories does not match with the specified filter options.
Generated using TypeDoc v0.25.12
+
+
+
Lists files in the specified directory path, filtering by a regular +expression pattern.
+The returned entries are configurable using the additional options, +such as listing recursively to subdirectories, and filter specific file and/or +directory names using a regular expression.
+The additional options
can be an object or a regex pattern to specify only
+the match field. If passed as a RegExp
object, the rest
+options (except the match
field) for reading the directory will uses default options.
If the options
argument not specified (or undefined
), then it uses the
+default value:
[LsOptions]: {
encoding: 'utf8',
recursive: false,
match: /.+/,
exclude: undefined
}
+
+As of version 1.0.0, this function now accepts file URL paths. This can be
+either a string URL path or a URL
object, and it must follow the 'file:'
protocol.
+An URIError
will be thrown if the specified file URL path has invalid file
+URL syntax or is used with unsupported protocols.
Added in version 0.1.0.
+A promise that resolves with an array of string representing the
+ entries result excluding '.'
and '..'
or an empty array ([]
)
+ if any files and directories does not match with the specified filter options.
Generated using TypeDoc v0.25.12
+
+
+
Lists files in the specified directory path, filtering by a regular +expression pattern.
+The returned entries are configurable using the additional options, +such as listing recursively to subdirectories, and filter specific file and/or +directory names using a regular expression.
+The additional options
can be an object or a regex pattern to specify only
+the match field. If passed as a RegExp
object, the rest
+options (except the match
field) for reading the directory will uses default options.
If the options
argument not specified (or undefined
), then it uses the
+default value:
[LsOptions]: {
encoding: 'utf8',
recursive: false,
match: /.+/,
exclude: undefined
}
+
+As of version 1.0.0, this function now accepts file URL paths. This can be
+either a string URL path or a URL
object, and it must follow the 'file:'
protocol.
+An URIError
will be thrown if the specified file URL path has invalid file
+URL syntax or is used with unsupported protocols.
Added in version 0.1.0.
+A promise that resolves with an array of string representing the
+ entries result excluding '.'
and '..'
or an empty array ([]
)
+ if any files and directories does not match with the specified filter options.
Generated using TypeDoc v0.25.12
+
+
+
LSFND is an abbreviation for list (ls) files (f) and (n) directories (d), +a lightweight Node.js library designed to make listing files and directories more convenient. +It offers an efficient and simple way to explore through your directory structures +and retrieves the names of files and/or directories leveraging a configurable options +to modify the listing behavior, such as recursive searches and regular expression filters.
+This library's primary benefit is that every implemented API runs asynchronously, +guaranteeing that they will NEVER disrupt the execution of any other processes.
+++Important
+
Currently this library only focus on CommonJS (CJS) and ECMAScript Modules (ESM).As of version 1.0.0, this library has supported TypeScript projects with various +module types (i.e.,
+node16
,es6
, and many more). Previously, it was only supports +TypeScript projects with module type ofcommonjs
. All type declarations in this +library also has been enhanced to more robust and strict, thus improving type safety.
ls
Functionasync function ls(
dirpath: StringPath | URL,
options?: LsOptions | RegExp | undefined,
type?: LsTypes | undefined
): Promise<LsResult>
+
+The ls
function is an asynchronous function that retrieves a listing of files
+and/or directories within a specified directory path. It offers powerful customizable
+additional options to configures the listing behavior (see LsOptions
),
+filtering using regular expression and specify the type of returned results (i.e.,
+regular files or directories, or includes both).
dirpath
: { StringPath
| URL
}
The absolute or relative path to the directory you want to list. It can be a
+string path or a file URL path (either a URL string or a URL
object) with
+'file:'
protocol.
options
: { LsOptions
| RegExp
| undefined
} (nullable, optional)
An optional regular expression or object that configures the listing behavior. By
+supplying a regular expression to the match
and exclude
options, you may
+filter the file or directory names. You can also enable the recursive
option
+(i.e., set it to true
) to enable the ability to recursively traverse subdirectories.
+If passed with a RegExp
object, then it only supplied the match
option and
+the rest options will uses their default values. See LsOptions
+for further information in detail.
type
: { LsTypes
| undefined
} (nullable, optional)
An optional parameter that specifies the type of entries you want to include
+in the results. You can pass 0
(zero) as value which will be interpreted as
+default behavior (i.e., include both regular files type and directories type).
+Refer to lsTypes
to see all supported types.
Returns a promise that resolves to an array of string containing the entries result.
+It can be null
if an error occurred while listing a directory, or returns a
+promise with an empty array if any files and directories doesn't match with the
+specified filter options.
++Note
+
💡 Tip: You can combine options for more granular control. For example, +you can list directories and/or files recursively while filtering by either +specific extensions or names.
const { ls, lsTypes } = require('lsfnd');
(async () => {
// List all files and directories in the current directory
const allFiles = await ls('.');
console.log(allFiles);
// List only JavaScript files in the current directory recursively
const jsFiles = await ls('.', {
recursive: true,
match: /\.js$/
}, lsTypes.LS_F);
console.log(jsFiles);
})();
+
+import { ls, lsTypes } from 'lsfnd';
// List all files and directories in the current directory
const allFiles = await ls('.');
console.log(allFiles);
// List only JavaScript files in the current directory recursively
const jsFiles = await ls('.', {
recursive: true,
match: /\.js$/
}, lsTypes.LS_F);
console.log(jsFiles);
+
+lsFiles
Functionasync function lsFiles(
dirpath: StringPath | URL,
options?: LsOptions | RegExp | undefined
): Promise<LsResult>
+
+An asynchronous function that retrieves a listing of files within a specified
+directory path. This function behaves the same as ls
function,
+but this function only lists and retrieves the regular files type (i.e., excluding
+any directories type).
++This function is an alias for:
++// It uses LS_F to filter only the regular file type
ls(dirpath, options, lsTypes.LS_F); +
dirpath
: { StringPath
| URL
}
The absolute or relative path to the directory you want to list. It can be a
+string path or a file URL path (either a URL string or a URL
object) with
+'file:'
protocol.
options
: { LsOptions
| RegExp
| undefined
} (nullable, optional)
An optional regular expression or object that configures the listing behavior. By
+supplying a regular expression to the match
and exclude
options, you may
+filter the file or directory names. You can also enable the recursive
option
+(i.e., set it to true
) to enable the ability to recursively traverse subdirectories.
+If passed with a RegExp
object, then it only supplied the match
option and
+the rest options will uses their default values. See LsOptions
+for further information in detail.
Returns a promise that resolves to an array of string containing the entries result.
+It can be null
if an error occurred while listing a directory, or returns a
+promise with an empty array if any files doesn't match with the specified filter
+options.
const { lsFiles } = require('lsfnd');
(async () => {
// Search and list LICENSE and README file in current directory
const files = await lsFiles('.', /(README|LICENSE)(\.md|\.txt)*$/);
console.log(files);
})();
+
+import { lsFiles } from 'lsfnd';
// Search and list LICENSE and README file in current directory
const files = await lsFiles('.', /(README|LICENSE)(\.md|\.txt)*$/);
console.log(files);
+
+lsDirs
Functionasync function lsDirs(
dirpath: StringPath | URL,
options?: LsOptions | RegExp | undefined
): Promise<LsResult>
+
+An asynchronous function that retrieves a listing of directories within a specified
+directory path. This function behaves the same as ls
function, but this
+function only lists and retrieves the directories type (i.e., excluding any files type).
++This function is an alias for:
++// It uses LS_D to filter only the directory type
ls(dirpath, options, lsTypes.LS_D); +
dirpath
: { StringPath
| URL
}
The absolute or relative path to the directory you want to list. It can be a
+string path or a file URL path (either a URL string or a URL
object) with
+'file:'
protocol.
options
: { LsOptions
| RegExp
| undefined
} (nullable, optional)
An optional regular expression or object that configures the listing behavior. By
+supplying a regular expression to the match
and exclude
options, you may
+filter the file or directory names. You can also enable the recursive
option
+(i.e., set it to true
) to enable the ability to recursively traverse subdirectories.
+If passed with a RegExp
object, then it only supplied the match
option and
+the rest options will uses their default values. See LsOptions
+for further information in detail.
Returns a promise that resolves to an array of string containing the entries result.
+It can be null
if an error occurred while listing a directory, or returns a
+promise with an empty array if any directories doesn't match with the specified
+filter options.
const { lsDirs } = require('lsfnd');
(async () => {
// List all installed NPM packages in 'node_modules' directory
// excluding '.bin' directory and organization packages (prefixed with '@')
const npmPkgs = await lsDirs('node_modules', { exclude: /(\.bin|@.+)/ });
console.log(npmPkgs);
})();
+
+import { lsDirs } from 'lsfnd';
// List all installed NPM packages in 'node_modules' directory
// excluding '.bin' directory and organization packages (prefixed with '@')
const npmPkgs = await lsDirs('node_modules', { exclude: /(\.bin|@.+)/ });
console.log(npmPkgs);
+
+lsTypes
EnumAn enumeration defines the different types of listings supported by the
+ls
function. It specifies which file system entries should be
+included in the results. For more details documentation, refer to LsTypesInterface
+for the type documentation or lsTypes
for the actual enum documentation.
Name | +Description | +Value | +
---|---|---|
LS_A |
+Represents an option to includes all types (i.e., includes both regular files and directories type). | +0b01 |
+
LS_D |
+Represents an option to includes only the directories type. | +0b10 |
+
LS_F |
+Represents an option to includes only the regular files type. | +0b100 |
+
defaultLsOptions
ObjectA constant object containing all default values of LsOptions
+type, typically implicitly used when user not specified the options
argument in every ls*
+functions.
Name | +Default Value | +
---|---|
encoding |
+'utf8' |
+
recursive |
+false |
+
match |
+/.+/ |
+
exclude |
+undefined |
+
rootDir |
+process.cwd() |
+
absolute |
+false |
+
basename |
+false |
+
This project is licensed under the terms of MIT license.
+ +Generated using TypeDoc v0.25.12
+
+
+
Interface representing the configuration options for the build process.
+0.1.0
+The root directory of the project from where the build process starts. +This path should be a string representing a valid file system path.
+The output directory where the build process will place generated files. +This path should be a string representing a valid file system path.
+The path to the tsconfig.json
file that will be used during the build process.
+This path should be a string representing a valid file system path relative
+to the rootDir.
Configuration options for minification process.
+Generated using TypeDoc v0.25.12
+
+
+
Interface representing the configuration options for minification within the +build process.
+0.1.0
+A list of file paths (relative to the BuildPropConfig.rootDir) +to be included during minification. Each element in the array should be a +string representing a valid file system path.
+Generated using TypeDoc v0.25.12
+
+
+
Represents the default options type for the ls*
functions, used by
+defaultLsOptions
.
Readonly
encodingReadonly
recursiveReadonly
matchReadonly
excludeReadonly
rootReadonly
absoluteReadonly
basenameGenerated using TypeDoc v0.25.12
+
+
+
This interface defines the optional configuration options that can be passed
+to every ls*
functions. These options control the behavior of the directory listing.
0.1.0
+Optional
encodingSpecifies the character encoding to be used for the output encoding of +returned entries.
+'utf8'
0.1.0
+Optional
recursiveA boolean flag indicating whether to include subdirectories in the listing.
+false
0.1.0
+Optional
matchA regular expression or string pattern used to filter the listed entries. +Only entries matching the pattern will be included in the results.
+/.+/
(match all files)
0.1.0
+Optional
excludeA 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.
+undefined
0.1.0
+Optional
rootA 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.
'.'
or process.cwd()
1.0.0
+Optional
absoluteDetermines 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));
+
+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/'));
+
+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.
Optional
basenameWhether 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 usingls
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());
+
+Or even a bit more simple like this:
+// ...
const baseResults = results.map((res) => path.basename(res));
+
+Generated using TypeDoc v0.25.12
+
+
+
Readonly
Interface defining the lsTypes enum with string literal keys +representing different file types and their corresponding numeric values.
+0.1.0
+Readonly
LS_Represents an option to include all file types.
+0b01 << 0b00
(0b01
| 0o01
| 0x01
| 1
)
Readonly
LS_Represents an option to include only the directory type.
+0b01 << 0b01
(0b10
| 0o02
| 0x02
| 2
)
Readonly
LS_Represents an option to include only the file type.
+0b01 << 0b10
(0b100
| 0o04
| 0x04
| 4
)
Generated using TypeDoc v0.25.12
+
+
+
Type definitions for build.prop.*js
configuration file.
Project: lsfnd (https://github.com/mitsuki31/lsfnd.git)
Definitions by: Ryuu Mitsuki (https://github.com/mitsuki31)
Generated using TypeDoc v0.25.12
+
+
+
Generated using TypeDoc v0.25.12
+
+
+
A module that offers some functions to read and list files and/or directories +in a specified directory with support filtering using regular expression pattern.
+Copyright (c) 2024 Ryuu Mitsuki. All rights reserved.
+Generated using TypeDoc v0.25.12
+
+
+
Type definitions for lsfnd
package.
Project: lsfnd (https://github.com/mitsuki31/lsfnd.git)
Definitions by: Ryuu Mitsuki (https://github.com/mitsuki31)
Copyright (c) 2024 Ryuu Mitsuki. All rights reserved.
+Generated using TypeDoc v0.25.12
+
+
+
This type alias represents an array of StringPath. It is typically used to
+represent the list of file and/or directory entries returned by the ls*
functions.
+Each entry in the array represents the path of a file or directory within
+the listed directory.
0.1.0
+Generated using TypeDoc v0.25.12
+
+
+
Generated using TypeDoc v0.25.12
+
+
+
A combination union types containing all possible values used to specify the +returned results on ls function.
+Generated using TypeDoc v0.25.12
+
+
+
Type representing all possible keys of the lsTypes enum.
+Generated using TypeDoc v0.25.12
+
+
+
Type representing all possible values of the lsTypes enum.
+Generated using TypeDoc v0.25.12
+
+
+
Represents resolved options type for the ls*
functions, where all properties are
+required and both null
and undefined
values are omitted, except for the
+exclude
property which keeps the undefined
type.
Generated using TypeDoc v0.25.12
+
+
+
A type representing the string path.
+1.0.0
+Generated using TypeDoc v0.25.12
+
+
+
Const
An object containing all default values of LsOptions
type.
Generated using TypeDoc v0.25.12
+
+
+
Generated using TypeDoc v0.25.12
+
+
+
This enumeration defines the different types of listings supported by +the ls function. It specifies which file system entries should be +included in the results.
+Since
0.1.0
+See
ls
+