feat(api): Expand APIs with new customizable options and enhanced functionality

[mitsuki31]

Overview

This pull request introduces several enhancements and additions to the LSFND package, focusing on enhancing APIs usage by introducing some additional options, and refining type declarations to more robust and compatible with these changes and future changes.

Notable Changes

• Addition of several new API options, including absolute, rootDir, and basename option to LsOptions (i.e., the options parameter of ls* functions).
• Introduced a new constant object represents the default options of LsOptions, this is publicly visible.
• Improvements to type declarations, ensuring type safety, compatibility, and improving code robustness.

Details

APIs Enhancements

• Introduced several new API options:
  • absolute: Determines whether to return absolute paths for all entries.
  • basename: Controls whether returned entries include only file and/or directory names.
  • rootDir: Specifies the root directory to resolve relative paths.

Note

These options have priority tiers, with the highest priority being at the top of the list. For example, if both rootDir and absolute are specified, absolute takes precedence.

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

Warning

THIS MIGHT BREAKING CHANGES!

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, the absolute 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 option.

• Added support for file URLs in the rootDir option. Note that only URLs with the 'file:' protocol are supported, and attempting to use other protocols will result in an error. This option uses the same logic resolution as the dirpath parameter, which you can pass a relative path of file URL string like this:

  lsDirs('file:./a/b/c', { rootDir: 'file:./a' });
  // Output: b/c

• Enhanced the resolution of the options parameter by defining a new internal function called resolveOptions. This improves flexibility and reduces code duplication while ensuring type strictness.

• Introduced the defaultLsOptions constant object, containing all default options for ls* functions.

Types Declaration

• Declared a new type called StringPath representing a path from a string.
• Refactored and improved type declarations, including changes to LsOptionsInterface, LsTypesValues, ResolvedLsOptions, and DefaultLsOptions.

Documentation

• Added TypeDoc documentation for the defaultLsOptions object and the resolveOptions internal function.

Summary

These changes significantly enhance the LSFND package by introducing new API options, improving options handling and documentation, and refining type declarations. These enhancements contribute to better usability, flexibility, and correctness of the package.