docs(readme): Update the README file

mitsuki31 · Apr 29, 2024 · 0a2ef9c · 0a2ef9c
1 parent c81c8b9
commit 0a2ef9c
Showing 1 changed file with 118 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -1,50 +1,66 @@
 # LSFND
 
-![Version](https://img.shields.io/github/package-json/v/mitsuki31/lsfnd?logo=npm&label=LSFND)
+[![Version](https://img.shields.io/npm/v/lsfnd?logo=npm&label=lsfnd)](https://npmjs.com/package/lsfnd)
+![Min. Node](https://img.shields.io/node/v-lts/lsfnd/latest?logo=node.js&label=node)
+[![Bundle size (minified)](https://img.shields.io/bundlephobia/min/lsfnd)](https://npmjs.com/package/lsfnd)<br>
 [![Test CI](https://github.com/mitsuki31/lsfnd/actions/workflows/test.yml/badge.svg)](https://github.com/mitsuki31/lsfnd/actions/workflows/test.yml)
 [![License](https://img.shields.io/github/license/mitsuki31/lsfnd?logo=github&logoColor=f9f9f9&label=License&labelColor=yellow&color=white)](https://github.com/mitsuki31/lsfnd/tree/master/LICENSE)
 
-**LSFND**, short for _list (ls) files (f) and (n) directories (d)_, is a small
-Node.js library designed to simplify file and directory listing tasks. It provides a
-lightweight and efficient way to explore your file system and retrieve information
-about files and directories with support filtering using regular expression.
+**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.
 
-The primary benefit of this library is that all implemented APIs execute asynchronously,
-therefore ensuring their execution will **NOT** block any other processes.
+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 project only focus on CommonJS (CJS) and ECMAScript Modules (ESM).
+> 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 of `commonjs`. All type declarations in this
+> library also has been enhanced to more robust and strict, thus improving type safety.
 
 ## APIs
 
 ### `ls` Function
 ```ts
 async function ls(
-  dirpath: string,
+  dirpath: StringPath | URL,
   options?: LsOptions | RegExp | undefined,
-  type?: lsTypes | LsTypesKeys | LsTypesValues | 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 used during listing the directory, filtering using regular
-expression and specify the type of returned results (i.e., regular files or directories,
-or includes both).
+additional options to configures the listing behavior (see [`LsOptions`][LsOptions]),
+filtering using regular expression and specify the type of returned results (i.e.,
+regular files or directories, or includes both).
 
 #### Parameters
 
-- `dirpath`\
-  The absolute or relative path to the directory you want to list.
-
-- `options` (_optional_)\
-  An optional object or regular expression used to configure the listing behavior.
-
-- `type` (_optional_)\
+- `dirpath` : { [`StringPath`][StringPath] | [`URL`][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`][URL] object) with
+  `'file:'` protocol.
+
+- `options` : { [`LsOptions`][LsOptions] | [`RegExp`][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`][RegExp] object, then it only supplied the `match` option and
+  the rest options will uses their default values. See [`LsOptions`][LsOptions]
+  for further information in detail.
+
+- `type` : { [`LsTypes`][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`](#lsTypes-enum) to see all supported types.
+  Refer to [`lsTypes`](#lstypes-enum) to see all supported types.
 
 #### Return
 
@@ -55,7 +71,8 @@ specified filter options.
 
 > [!NOTE]\
 > 💡 **Tip**: You can combine options for more granular control. For example,
-> you can list files recursively while filtering by a specific extension.
+> you can list directories and/or files recursively while filtering by either
+> specific extensions or names.
 
 <details>
 <summary>Example Usage (CJS)</summary>
@@ -100,28 +117,37 @@ console.log(jsFiles);
 ### `lsFiles` Function
 ```ts
 async function lsFiles(
-  dirpath: string,
+  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 behave the same as [`ls`](#ls-function) function,
-but this function only lists and retrieves the files type (i.e., excluding directories type).
+directory path. This function behaves the same as [`ls`](#ls-function) function,
+but this function only lists and retrieves the regular files type (i.e., excluding
+any directories type).
 
-This function is an alias for:
-```js
-// It uses LS_F to filter only the regular file type
-ls(dirpath, options, lsTypes.LS_F);
-```
+> This function is an alias for:
+> ```js
+> // It uses LS_F to filter only the regular file type
+> ls(dirpath, options, lsTypes.LS_F);
+> ```
 
 #### Parameters
 
-- `dirpath`\
-  The absolute or relative path to the directory you want to list.
+- `dirpath` : { [`StringPath`][StringPath] | [`URL`][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`][URL] object) with
+  `'file:'` protocol.
 
-- `options` (_optional_)\
-  An optional object or regular expression used to configure the listing behavior.
+- `options` : { [`LsOptions`][LsOptions] | [`RegExp`][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`][RegExp] object, then it only supplied the `match` option and
+  the rest options will uses their default values. See [`LsOptions`][LsOptions]
+  for further information in detail.
 
 #### Return
 
@@ -130,10 +156,6 @@ 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.
 
-> [!NOTE]\
-> 💡 **Tip**: You can combine options for more granular control. For example,
-> you can list files recursively while filtering by a specific extension.
-
 <details>
 <summary>Example Usage (CJS)</summary>
 
@@ -155,30 +177,44 @@ const { lsFiles } = require('lsfnd');
 import { lsFiles } from 'lsfnd';
 
 // Search and list LICENSE and README file in current directory
-const files = await lsFiles('.', /(README|LICENSE)(\.md)*$/);
+const files = await lsFiles('.', /(README|LICENSE)(\.md|\.txt)*$/);
 console.log(files);
 ```
 </details>
 
 ### `lsDirs` Function
+```ts
+async 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 behave the same as [`ls`](#ls-function) function, but this
-function only lists and retrieves the directories type (i.e., excluding files type).
+directory path. This function behaves the same as [`ls`](#ls-function) function, but this
+function only lists and retrieves the directories type (i.e., excluding any files type).
 
-This function is an alias for:
-```js
-// It uses LS_D to filter only the directory type
-ls(dirpath, options, lsTypes.LS_D);
-```
+> This function is an alias for:
+> ```js
+> // It uses LS_D to filter only the directory type
+> ls(dirpath, options, lsTypes.LS_D);
+> ```
 
 #### Parameters
 
-- `dirpath`\
-  The absolute or relative path to the directory you want to list.
+- `dirpath` : { [`StringPath`][StringPath] | [`URL`][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`][URL] object) with
+  `'file:'` protocol.
 
-- `options` (_optional_)\
-  An optional object or regular expression used to configure the listing behavior.
+- `options` : { [`LsOptions`][LsOptions] | [`RegExp`][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`][RegExp] object, then it only supplied the `match` option and
+  the rest options will uses their default values. See [`LsOptions`][LsOptions]
+  for further information in detail.
 
 #### Return
 
@@ -219,16 +255,44 @@ console.log(npmPkgs);
 
 An enumeration defines the different types of listings supported by the
 [`ls`](#ls-function) function. It specifies which file system entries should be
-included in the results.
+included in the results. For more details documentation, refer to [`LsTypesInterface`][LsTypesInterface]
+for the type documentation or [`lsTypes`][lsTypes] for the actual enum documentation.
 
 #### Properties
 
 |   Name   |   Description   |   Value   |
 | -------- | --------------- | --------- |
-| `LS_A`   | Represents an option to include all file types (i.e., including both regular files and directories). | `0b01` |
-| `LS_D`   | Represents an option to include only the directory type. | `0b10` |
-| `LS_F`   | Represents an option to include only the regular file type. | `0b100` |
+| `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` Object
+
+A constant object containing all default values of [`LsOptions`][LsOptions]
+type, typically implicitly used when user not specified the `options` argument in every `ls*`
+functions.
+
+#### Properties
+
+|    Name     |  Default Value  |
+| ----------- | --------------- |
+| `encoding`  | `'utf8'`        |
+| `recursive` | `false`         |
+| `match`     | `/.+/`          |
+| `exclude`   | `undefined`     |
+| `rootDir`   | `process.cwd()` |
+| `absolute`  | `false`         |
+| `basename`  | `false`         |
 
 ## License
 
 This project is licensed under the terms of [MIT](./LICENSE) license.
+
+<!-- Links -->
+[StringPath]: https://mitsuki31.github.io/lsfnd/types/types.StringPath.html
+[LsOptions]: https://mitsuki31.github.io/lsfnd/interfaces/types.LsOptions.html
+[LsTypesInterface]: https://mitsuki31.github.io/lsfnd/interfaces/types.LsTypesInterface.html
+[LsTypes]: https://mitsuki31.github.io/lsfnd/types/types.LsTypes.html
+[lsTypes]: https://mitsuki31.github.io/lsfnd/enums/lsTypes.lsTypes.html
+[URL]: https://nodejs.org/api/url.html#class-url
+[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp