feat(lib): fileURLToPath, pathToFileURL

Signed-off-by: Lexus Drumgold <[email protected]>

.codecov.yml

@@ -87,10 +87,6 @@ flags:
     carryforward: false
     paths:
       - src/
-  node20:
-    carryforward: false
-    paths:
-      - src/
 
 github_checks:
   annotations: true

.dictionary.txt

@@ -1,16 +1,21 @@
+abar
 attw
 barx
+cbar
 cefc
 codecov
 commitlintrc
+dbar
 dedupe
 deno
 dessant
 devlop
 docast
 dohm
 dprint
+fbar
 fbca
+fóóbàr
 ggshield
 gpgsign
 hmarr
@@ -35,4 +40,5 @@ unstub
 vates
 vfile
 vitest
+whatwg
 yarnrc

.github/infrastructure.yml

@@ -44,7 +44,6 @@ branches:
           - context: gitguardian
           - context: lint
           - context: spelling
-          - context: test (20)
           - context: test (22)
           - context: typescript (5.0.4)
           - context: typescript (5.4.5)

.github/workflows/ci.yml

@@ -299,7 +299,6 @@ jobs:
       matrix:
         node-version:
           - 22
-          - 20
     steps:
       - id: checkout
         name: Checkout ${{ env.REF_NAME }}

README.md

@@ -93,6 +93,7 @@ import {
   dirname,
   dot,
   extname,
+  fileURLToPath,
   format,
   formatExt,
   isAbsolute,
@@ -102,6 +103,7 @@ import {
   matchesGlob,
   normalize,
   parse,
+  pathToFileURL,
   relative,
   removeExt,
   resolve,
@@ -126,6 +128,7 @@ This package exports the following identifiers:
 - [`dot`](./src/lib/dot.ts)
 - [`extname`](./src/lib/extname.ts)
 - [`extnames`](./src/lib/extnames.ts)
+- [`fileURLToPath`](./src/lib/file-url-to-path.ts)
 - [`formatExt`](./src/lib/format-ext.ts)
 - [`format`](./src/lib/format.ts)
 - [`isAbsolute`](./src/lib/is-absolute.ts)
@@ -135,6 +138,7 @@ This package exports the following identifiers:
 - [`matchesGlob`](./src/lib/matches-glob.ts)
 - [`normalize`](./src/lib/normalize.ts)
 - [`parse`](./src/lib/parse.ts)
+- [`pathToFileURL`](./src/lib/path-to-file-url.ts)
 - [`posix`](./src/pathe.ts)
 - [`relative`](./src/lib/relative.ts)
 - [`removeExt`](./src/lib/remove-ext.ts)
@@ -164,13 +168,14 @@ This package is fully typed with [TypeScript][].
 - [`FormatInputPathObject`](src/interfaces/format-input-path-object.ts)
 - [`ParsedPath`](src/interfaces/parsed-path.ts)
 - [`Pathe`](src/interfaces/pathe.ts)
-- [`PlatformPath`](src/interfaces/platform-path-posix.ts)
+- [`PlatformOptions`](src/interfaces/platform-options.ts)
+- [`PlatformPath`](src/interfaces/platform-path.ts)
 - [`PosixDelimiter`](src/types/delimiter-posix.ts)
-- [`PosixPlatformPath`](src/interfaces/platform-path-windows.ts)
+- [`PosixPlatformPath`](src/interfaces/platform-path-posix.ts)
 - [`PosixSep`](src/types/sep-posix.ts)
 - [`Sep`](src/types/sep.ts)
 - [`WindowsDelimiter`](src/types/delimiter-windows.ts)
-- [`WindowsPlatformPath`](src/interfaces/platform-path.ts)
+- [`WindowsPlatformPath`](src/interfaces/platform-path-windows.ts)
 - [`WindowsSep`](src/types/sep-windows.ts)
 
 ## Contribute

package.json

@@ -56,6 +56,18 @@
     "./win32": "./dist/win32.mjs"
   },
   "imports": {
+    "#internal/domain-to-ascii": {
+      "pathe": "./src/internal/domain-to-ascii.node.ts",
+      "browser": "./dist/internal/domain-to-ascii.browser.mjs",
+      "node": "./dist/internal/domain-to-ascii.node.mjs",
+      "default": "./dist/internal/domain-to-ascii.node.mjs"
+    },
+    "#internal/domain-to-unicode": {
+      "pathe": "./src/internal/domain-to-unicode.node.ts",
+      "browser": "./dist/internal/domain-to-unicode.browser.mjs",
+      "node": "./dist/internal/domain-to-unicode.node.mjs",
+      "default": "./dist/internal/domain-to-unicode.node.mjs"
+    },
     "#internal/process": {
       "browser": "./dist/internal/process.browser.mjs",
       "node": "process",
@@ -113,7 +125,8 @@
   "dependencies": {
     "@flex-development/errnode": "3.1.1",
     "@types/micromatch": "4.0.9",
-    "micromatch": "4.0.8"
+    "micromatch": "4.0.8",
+    "punycode.js": "2.3.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.16.4",

src/__snapshots__/index.e2e.snap

@@ -11,6 +11,7 @@ exports[`e2e:pathe > should expose public api 1`] = `
   "dot",
   "extname",
   "extnames",
+  "fileURLToPath",
   "format",
   "formatExt",
   "isAbsolute",
@@ -20,6 +21,7 @@ exports[`e2e:pathe > should expose public api 1`] = `
   "matchesGlob",
   "normalize",
   "parse",
+  "pathToFileURL",
   "relative",
   "removeExt",
   "resolve",

src/interfaces/__tests__/platform-options.spec-d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Unit Tests - PlatformOptions
+ * @module pathe/interfaces/tests/unit-d/PlatformOptions
+ */
+
+import type { Nilable } from '@flex-development/tutils'
+import type TestSubject from '../platform-options'
+
+describe('unit-d:interfaces/PlatformOptions', () => {
+  it('should match [windows?: boolean | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('windows')
+      .toEqualTypeOf<Nilable<boolean>>()
+  })
+})

src/interfaces/index.ts

@@ -9,6 +9,7 @@ export type {
 } from './format-input-path-object'
 export type { default as ParsedPath } from './parsed-path'
 export type { default as Pathe } from './pathe'
+export type { default as PlatformOptions } from './platform-options'
 export type { default as PlatformPath } from './platform-path'
 export type { default as PosixPlatformPath } from './platform-path-posix'
 export type { default as WindowsPlatformPath } from './platform-path-windows'

src/interfaces/pathe.ts

@@ -4,6 +4,13 @@
  */
 
 import type extname from '#lib/extname'
+import type {
+  ErrInvalidArgType,
+  ErrInvalidArgValue,
+  ErrInvalidFileUrlHost,
+  ErrInvalidFileUrlPath,
+  ErrInvalidUrlScheme
+} from '@flex-development/errnode'
 import type {
   Cwd,
   DeviceRoot,
@@ -12,6 +19,7 @@ import type {
   Ext,
   Sep
 } from '@flex-development/pathe'
+import type PlatformOptions from './platform-options'
 import type PosixPlatformPath from './platform-path-posix'
 
 /**
@@ -70,19 +78,6 @@ interface Pathe extends PosixPlatformPath {
    */
   readonly dot: Dot
 
-  /**
-   * Format a file extension.
-   *
-   * @see {@linkcode EmptyString}
-   * @see {@linkcode Ext}
-   *
-   * @param {string | null | undefined} ext
-   *  File extension to format
-   * @return {EmptyString | Ext}
-   *  Formatted file extension or empty string
-   */
-  formatExt(this: void, ext: string | null | undefined): EmptyString | Ext
-
   /**
    * Get a list of file extensions for `path`.
    *
@@ -96,6 +91,44 @@ interface Pathe extends PosixPlatformPath {
    */
   extnames(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}
+   *
+   * @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(
+    url: URL | string,
+    options?: PlatformOptions | null | undefined
+  ): string
+
+  /**
+   * Format a file extension.
+   *
+   * @see {@linkcode EmptyString}
+   * @see {@linkcode Ext}
+   *
+   * @param {string | null | undefined} ext
+   *  File extension to format
+   * @return {EmptyString | Ext}
+   *  Formatted file extension or empty string
+   */
+  formatExt(this: void, ext: string | null | undefined): EmptyString | Ext
+
   /**
    * Check if `value` is a device root.
    *
@@ -120,6 +153,35 @@ interface Pathe extends PosixPlatformPath {
    */
   isSep(this: void, value: unknown): value is Sep
 
+  /**
+   * Convert a file `path` to a `file:` {@linkcode URL}.
+   *
+   * > The following characters are percent-encoded when converting from file
+   * > path to a `URL`:
+   * >
+   * > - %: Only character not encoded by the `pathname` setter
+   * > - CR: Stripped out by the `pathname` setter (see [`whatwg/url#419`][419])
+   * > - LF: Stripped out by the `pathname` setter (see [`whatwg/url#419`][419])
+   * > - TAB: Stripped out by the `pathname` setter
+   *
+   * [419]: https://github.com/whatwg/url/issues/419
+   *
+   * @see {@linkcode ErrInvalidArgValue}
+   * @see {@linkcode PlatformOptions}
+   *
+   * @param {URL | string} path
+   *  Path to handle
+   * @param {PlatformOptions | null | undefined} [options]
+   *  Platform options
+   * @return {URL}
+   *  `path` as `file:` URL
+   * @throws {ErrInvalidArgValue}
+   */
+  pathToFileURL(
+    path: string,
+    options?: PlatformOptions | null | undefined
+  ): URL
+
   /**
    * Remove the file extension of `path`.
    *

src/interfaces/platform-options.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Interfaces - PlatformOptions
+ * @module pathe/lib/PlatformOptions
+ */
+
+/**
+ * Platform-specific options.
+ */
+interface PlatformOptions {
+  /**
+   * Use windows-specific logic.
+   */
+  windows?: boolean | null | undefined
+}
+
+export type { PlatformOptions as default }

src/internal/__tests__/is-url.spec.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Unit Tests - isURL
+ * @module pathe/internal/tests/unit/isURL
+ */
+
+import testSubject from '../is-url'
+
+describe('unit:internal/isURL', () => {
+  it.each<Parameters<typeof testSubject>>([
+    [null],
+    ['https://github.com/flex-development/errnode'],
+    [{ href: 'file://host/a', path: '/a', pathname: '/a', protocol: 'file:' }]
+  ])('should return `false` if `value` is not URL-like (%#)', value => {
+    expect(testSubject(value)).to.be.false
+  })
+
+  it.each<Parameters<typeof testSubject>>([
+    [new URL('https://github.com/flex-development/pathe')],
+    [{ href: 'file:///', pathname: '/', protocol: 'file:' }]
+  ])('should return `true` if `value` is URL-like (%#)', value => {
+    expect(testSubject(value)).to.be.true
+  })
+})

src/internal/__tests__/validate-object.spec.ts

@@ -3,7 +3,7 @@
  * @module pathe/internal/tests/unit/validateObject
  */
 
-import { codes, type ErrInvalidArgType } from '@flex-development/errnode'
+import { codes, isNodeError, type NodeError } from '@flex-development/errnode'
 import testSubject from '../validate-object'
 
 describe('unit:internal/validateObject', () => {
@@ -19,7 +19,7 @@ describe('unit:internal/validateObject', () => {
 
   it('should throw if `value` is not curly-braced object', () => {
     // Arrange
-    let error!: ErrInvalidArgType
+    let error!: NodeError
 
     // Act
     try {
@@ -29,7 +29,7 @@ describe('unit:internal/validateObject', () => {
     }
 
     // Expect
-    expect(error).to.be.instanceof(TypeError)
+    expect(error).to.satisfy(isNodeError)
     expect(error).to.have.property('code', codes.ERR_INVALID_ARG_TYPE)
   })
 })

src/internal/__tests__/validate-string.spec.ts

@@ -3,7 +3,7 @@
  * @module pathe/internal/tests/unit/validateString
  */
 
-import { codes, type ErrInvalidArgType } from '@flex-development/errnode'
+import { codes, isNodeError, type NodeError } from '@flex-development/errnode'
 import testSubject from '../validate-string'
 
 describe('unit:internal/validateString', () => {
@@ -19,7 +19,7 @@ describe('unit:internal/validateString', () => {
 
   it('should throw if `value` is not a string', () => {
     // Arrange
-    let error!: ErrInvalidArgType
+    let error!: NodeError
 
     // Act
     try {
@@ -29,7 +29,7 @@ describe('unit:internal/validateString', () => {
     }
 
     // Expect
-    expect(error).to.be.instanceof(TypeError)
+    expect(error).to.satisfy(isNodeError)
     expect(error).to.have.property('code', codes.ERR_INVALID_ARG_TYPE)
   })
 })

src/internal/domain-to-ascii.browser.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Internal - domainToASCII
+ * @module pathe/internal/domainToASCII/browser
+ */
+
+export { toASCII as default } from 'punycode.js'