feat: [toPosix] url support

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

.dictionary.txt

@@ -1,7 +1,9 @@
 abar
 attw
 barx
+cdir
 cefc
+cindex
 codecov
 commitlintrc
 dbar

src/interfaces/pathe.mts

@@ -5,7 +5,6 @@
 
 import type extname from '#lib/extname'
 import type {
-  ErrInvalidArgType,
   ErrInvalidArgValue,
   ErrInvalidFileUrlHost,
   ErrInvalidFileUrlPath,
@@ -36,8 +35,10 @@ interface Pathe extends PosixPlatformPath {
    * Does nothing if a file extension is not provided, or the
    * {@linkcode extname} of `path` is already `ext`.
    *
+   * @this {void}
+   *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @param {string | null | undefined} ext
    *  File extension to add
    * @return {string}
@@ -52,8 +53,10 @@ interface Pathe extends PosixPlatformPath {
    * If the file extension is an empty string, however, `path`'s file extension
    * will be removed.
    *
+   * @this {void}
+   *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @param {string | null | undefined} [ext]
    *  File extension to add
    * @return {string} `path` unmodified or with changed file extension
@@ -64,6 +67,8 @@ interface Pathe extends PosixPlatformPath {
   /**
    * Get the path to the current working directory.
    *
+   * @this {void}
+   *
    * @return {string}
    *  Absolute path to current working directory
    */
@@ -84,34 +89,37 @@ interface Pathe extends PosixPlatformPath {
    * @see {@linkcode Ext}
    * @see {@linkcode extname}
    *
+   * @this {void}
+   *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {Ext[]}
    *  List of extensions
    */
-  extnames(path: string): Ext[]
+  extnames(this: void, path: string): Ext[]
 
   /**
    * Convert a `file:` URL to a path.
    *
-   * @see {@linkcode ErrInvalidArgType}
    * @see {@linkcode ErrInvalidFileUrlHost}
    * @see {@linkcode ErrInvalidFileUrlPath}
    * @see {@linkcode ErrInvalidUrlScheme}
    * @see {@linkcode PlatformOptions}
    *
+   * @this {void}
+   *
    * @param {URL | string} url
    *  The file URL string or URL object to convert to a path
    * @param {PlatformOptions | null | undefined} [options]
    *  Platform options
    * @return {string}
    *  `url` as path
-   * @throws {ErrInvalidArgType}
    * @throws {ErrInvalidFileUrlHost}
    * @throws {ErrInvalidFileUrlPath}
    * @throws {ErrInvalidUrlScheme}
    */
   fileURLToPath(
+    this: void,
     url: URL | string,
     options?: PlatformOptions | null | undefined
   ): string
@@ -122,6 +130,8 @@ interface Pathe extends PosixPlatformPath {
    * @see {@linkcode EmptyString}
    * @see {@linkcode Ext}
    *
+   * @this {void}
+   *
    * @param {string | null | undefined} ext
    *  File extension to format
    * @return {EmptyString | Ext}
@@ -134,6 +144,8 @@ interface Pathe extends PosixPlatformPath {
    *
    * @see {@linkcode DeviceRoot}
    *
+   * @this {void}
+   *
    * @param {unknown} [value]
    *  Value to check
    * @return {value is DeviceRoot}
@@ -146,6 +158,8 @@ interface Pathe extends PosixPlatformPath {
    *
    * @see {@linkcode Sep}
    *
+   * @this {void}
+   *
    * @param {unknown} [value]
    *  Value to check
    * @return {value is Sep}
@@ -169,15 +183,18 @@ interface Pathe extends PosixPlatformPath {
    * @see {@linkcode ErrInvalidArgValue}
    * @see {@linkcode PlatformOptions}
    *
+   * @this {void}
+   *
    * @param {URL | string} path
-   *  Path to handle
+   *  The path to handle
    * @param {PlatformOptions | null | undefined} [options]
    *  Platform options
    * @return {URL}
    *  `path` as `file:` URL
    * @throws {ErrInvalidArgValue}
    */
   pathToFileURL(
+    this: void,
     path: string,
     options?: PlatformOptions | null | undefined
   ): URL
@@ -188,8 +205,10 @@ interface Pathe extends PosixPlatformPath {
    * Does nothing if `path` does not end with the provided file extension, or if
    * a file extension is not provided.
    *
+   * @this {void}
+   *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @param {string | null | undefined} ext
    *  File extension to remove
    * @return {string}
@@ -220,6 +239,8 @@ interface Pathe extends PosixPlatformPath {
    *
    * @see {@linkcode Cwd}
    *
+   * @this {void}
+   *
    * @param {ReadonlyArray<string> | string} paths
    *  Sequence of paths or path segments
    * @param {Cwd | null | undefined} [cwd]
@@ -239,31 +260,38 @@ interface Pathe extends PosixPlatformPath {
   /**
    * Get the root of `path`.
    *
+   * @this {void}
+   *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {string}
    *  Root of `path`
    */
   root(this: void, path: string): string
 
   /**
-   * Make `path` POSIX-compliant.
+   * Make separators in `path` POSIX-compliant.
    *
-   * This includes:
-   *
-   * - Converting Windows-style path delimiters (`;`) to POSIX (`:`)
-   * - Converting Windows-style path segment separators (`\`) to POSIX (`/`)
-   *
-   * @see https://nodejs.org/api/path.html#windows-vs-posix
-   * @see https://nodejs.org/api/path.html#pathdelimiter
-   * @see https://nodejs.org/api/path.html#pathsep
+   * @this {void}
    *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {string}
-   *  POSIX-compliant `path`
+   *  `path` with POSIX-compliant separators
    */
   toPosix(this: void, path: string): string
+
+  /**
+   * Make separators in `url` POSIX-compliant.
+   *
+   * @this {void}
+   *
+   * @param {string} url
+   *  The {@linkcode URL} to handle
+   * @return {URL}
+   *  `url` with POSIX-compliant separators
+   */
+  toPosix(this: void, url: URL): URL
 }
 
 export type { Pathe as default }

src/interfaces/platform-path.mts

@@ -60,7 +60,7 @@ interface PlatformPath {
    * [sep]: https://nodejs.org/api/path.html#pathsep
    *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @param {string | null | undefined} [suffix]
    *  Suffix to remove
    * @return {string}
@@ -76,7 +76,7 @@ interface PlatformPath {
    * [sep]: https://nodejs.org/api/path.html#pathsep
    *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {string}
    *  Directory name of `path`
    */
@@ -94,7 +94,7 @@ interface PlatformPath {
    * @see {@linkcode Ext}
    *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {EmptyString | Ext}
    *  Extension of `path` or empty string
    */
@@ -210,7 +210,7 @@ interface PlatformPath {
    * @see {@linkcode ParsedPath}
    *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {ParsedPath}
    *  Significant elements of `path`
    */
@@ -286,7 +286,7 @@ interface PlatformPath {
    * [unc]: https://learn.microsoft.com/dotnet/standard/io/file-path-formats#unc-paths
    *
    * @param {string} path
-   *  Path to handle
+   *  The path to handle
    * @return {string}
    *  Namespace-prefixed path or `path` without modifications
    */

src/internal/__tests__/validate-url-string.spec.mts

@@ -0,0 +1,39 @@
+/**
+ * @file Unit Tests - validateURLString
+ * @module pathe/internal/tests/unit/validateURLString
+ */
+
+import testSubject from '#internal/validate-url-string'
+import { codes, isNodeError, type NodeError } from '@flex-development/errnode'
+
+describe('unit:internal/validateURLString', () => {
+  let name: string
+
+  beforeAll(() => {
+    name = 'value'
+  })
+
+  it('should return `true` if `value` is a string', () => {
+    expect(testSubject(new URL(import.meta.url), name)).to.be.true
+  })
+
+  it('should return `true` if `value` is a string', () => {
+    expect(testSubject(import.meta.url, name)).to.be.true
+  })
+
+  it('should throw if `value` is not a `URL` or string', () => {
+    // Arrange
+    let error!: NodeError
+
+    // Act
+    try {
+      testSubject(null, name)
+    } catch (e: unknown) {
+      error = e as typeof error
+    }
+
+    // Expect
+    expect(error).to.satisfy(isNodeError)
+    expect(error).to.have.property('code', codes.ERR_INVALID_ARG_TYPE)
+  })
+})

src/internal/validate-string.mts

@@ -18,7 +18,7 @@ import {
  * @param {string} name
  *  Name of invalid argument or property
  * @return {value is string}
- *  `true` if `value` is a string, `false` otherwise
+ *  `true` if `value` is a string
  * @throws {ErrInvalidArgType}
  *  If `value` is not a string
  */

src/internal/validate-url-string.mts

@@ -0,0 +1,34 @@
+/**
+ * @file Internal - validateURLString
+ * @module pathe/internal/validateURLString
+ */
+
+import isURL from '#internal/is-url'
+import {
+  ERR_INVALID_ARG_TYPE,
+  type ErrInvalidArgType
+} from '@flex-development/errnode'
+
+/**
+ * Check if `value` is a {@linkcode URL} or string.
+ *
+ * @internal
+ *
+ * @param {unknown} value
+ *  Value to check
+ * @param {string} name
+ *  Name of invalid argument or property
+ * @return {value is URL | string}
+ *  `true` if `value` is a `URL` or string
+ * @throws {ErrInvalidArgType}
+ *  If `value` is not a `URL` or string
+ */
+function validateURLString(
+  value: unknown,
+  name: string
+): value is URL | string {
+  if (isURL(value) || typeof value === 'string') return true
+  throw new ERR_INVALID_ARG_TYPE(name, ['URL', 'string'], value)
+}
+
+export default validateURLString