Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Enhance APIs with file URL path support #2

Merged
merged 6 commits into from
Apr 19, 2024

Conversation

mitsuki31
Copy link
Owner

Summary

This pull request brings new features, enhance the functionality APIs, improve documentation, and ensure compatibility across different environments.

Notable Changes

  • Implemented an internal function to convert file URLs. This function behaves similarly to NodeJS' url.fileURLToPath function but with added support for relative paths. It throws an URIError for non-file protocols or invalid path structures. This function will be utilized in ls* functions to support file URL paths.
  • Improved and updated the documentation for the APIs. Additionally, a history section has been added to document changes in each version.
  • Added support for file URLs in all ls* functions. Now, these functions can accept string URL paths or URL objects with the 'file:' protocol. However, please note that only the 'file:' protocol is currently supported for directory resolution and listing.
  • Fixed an issue with absolute path resolution on Windows systems. The resolution process now ensures that the path passed to fs.readdir adheres to the required format.
  • Included several assert functions from the node:assert module to enhance test coverage.
  • Added new test cases to ensure the correct behavior of the APIs regarding file URL paths and URL objects with the 'file:' protocol. Also, tests have been added to verify that an URIError is correctly thrown when unsupported protocols are used.

Description

New Features

This pull request brings a new feature to all ls* functions, that is a support to file URL path for dirpath parameter. It accepts both a string URL path or a URL object by following the 'file:' protocol, utilizing an internal function called fileUrlToPath to convert the file URLs.

"Why don't use the inbuilt function provided by Node.js itself?" Well, this function might behave the same with url.fileURLToPath function from node:url module, but this function are supports relative paths. Unlike url.fileURLToPath inbuilt function that doesn't accepts a string URL with relative path, attempting to do so will causing an error.

Here's some examples on how to use the new feature:

// List all files in 'fooBar' directory relative from current directory
lsFiles('file:./fooBar').then(entries => console.log(entries));
const path = require('node:path');
const { pathToFileURL } = require('node:url');
// ESM: import * as path from 'node:path';
//      import { pathToFileURL } from 'node:url';

// List all installed packages inside 'node_modules' directory
ls(pathToFileURL(path.posix.resolve('node_modules')), {
  recursive: false,
  exclude: /\.bin/
}, lsTypes.LS_D).then(entries => console.log(entries));

This new feature has been tested and the tests code are available in the project. If having any issues while using the feature, report to us by providing the issue details.

Test Environments

Introduced new test cases to ensure that the APIs correctly handle file URL paths and URL objects with the 'file:' protocol and also ensured that the APIs throws a URIError when provided with URL paths using unsupported protocols.

Documentation

Added a history section to document changes made to the APIs in each version and improved the documentation for the APIs.

This function behave the same as NodeJS `url.fileURLToPath` function, but that makes this function differ is that this function supports relative paths being passed in the argument (e.g., "file:./foo/bar"). If the given URL is have non-file protocols or contains invalid path structures, an URIError will be thrown.

This function will be used as part of `ls*` functions to support file URL paths. In addition to this change, I've also added the documentation for the function.
Now all `ls*` functions have supported file URL path, this can be a string URL path or an URL object with 'file:' protocol.

Note:
Please note, that this function currently only supported 'file:' protocol to resolve and list the specified directory.
Included functions (from 'node:assert' module):
  - doesNotThrow: assert.doesNotThrow,
  - rejects: assert.rejects,
  - doesNotReject: assert.doesNotReject,
  - match: assert.match,
  - doesNotMatch: assert.doesNotMatch
The path passed to `fs.readdir` function can't be a Windows path, instead it must a node path (i.e., similar to POSIX path). That's why we need to resolve the relative path to absolute with format of POSIX path, so the path can be used to the `fs.readdir` function without getting an internal error.
ALso added a history section to describe changes to the APIs in every versions.
Added new test cases to test the APIs whether it correctly accepts file URL path and a `URL` object with 'file:' protocol, and correctly throws an `URIError` if the provided URL path using unsupported protocols.
@mitsuki31 mitsuki31 self-assigned this Apr 19, 2024
@mitsuki31
Copy link
Owner Author

mitsuki31 commented Apr 19, 2024

Not a breaking changes, but I desired to make these changes and the new features to be a part of major update.

@mitsuki31 mitsuki31 added enhancement New feature or request major Major changes (BREAKING CHANGES) labels Apr 19, 2024
@mitsuki31 mitsuki31 merged commit 61748da into master Apr 19, 2024
3 checks passed
@mitsuki31 mitsuki31 deleted the feat/add-support-file-url-dirpath branch April 19, 2024 17:18
@mitsuki31 mitsuki31 added this to the v1.0.0 milestone Apr 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request major Major changes (BREAKING CHANGES)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant