feat!: url support

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

.dictionary.txt

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

.github/infrastructure.yml

@@ -32,7 +32,6 @@ branches:
           - context: gitguardian
           - context: lint
           - context: spelling
-          - context: test (22)
           - context: test (23)
           - context: typescript (5.6.3)
           - context: typescript (5.7.1-rc)

.github/workflows/ci.yml

@@ -309,7 +309,6 @@ jobs:
       matrix:
         node-version:
           - 23
-          - 22
     env:
       COVERAGE_SUMMARY: ./coverage/coverage-summary.json
       NODE_VERSION: ${{ matrix.node-version }}

README.md

@@ -25,7 +25,7 @@ Universal drop-in replacement for [`node:path`][node-path]
 This package is a universal drop-in replacement for Node.js' [`path`][node-path] module.
 
 It enforces consistency between POSIX and Windows operating systems and also provides additional utilities for working
-with file paths and extensions.
+with file URLs, paths, and extensions.
 
 ## When should I use this?
 
@@ -99,6 +99,7 @@ import {
   isAbsolute,
   isDeviceRoot,
   isSep,
+  isURL,
   join,
   matchesGlob,
   normalize,
@@ -111,6 +112,7 @@ import {
   root,
   sep,
   toNamespacedPath,
+  toPath,
   toPosix
 } from '@flex-development/pathe'
 ```
@@ -134,6 +136,7 @@ This package exports the following identifiers:
 - [`isAbsolute`](./src/lib/is-absolute.mts)
 - [`isDeviceRoot`](./src/lib/is-device-root.mts)
 - [`isSep`](./src/lib/is-sep.mts)
+- [`isURL`](./src/lib/is-url.mts)
 - [`join`](./src/lib/join.mts)
 - [`matchesGlob`](./src/lib/matches-glob.mts)
 - [`normalize`](./src/lib/normalize.mts)
@@ -147,6 +150,7 @@ This package exports the following identifiers:
 - [`root`](./src/lib/root.mts)
 - [`sep`](./src/lib/sep.mts)
 - [`toNamespacedPath`](./src/lib/to-namespaced-path.mts)
+- [`toPath`](./src/lib/to-path.mts)
 - [`toPosix`](./src/lib/to-posix.mts)
 - [`win32`](./src/pathe.mts)
 

__fixtures__/drive.mts

@@ -0,0 +1,15 @@
+/**
+ * @file Fixtures - DRIVE
+ * @module fixtures/drive
+ */
+
+import type { DriveLetter } from '@flex-development/pathe'
+
+/**
+ * Windows drive letter.
+ *
+ * @const {DriveLetter} DRIVE
+ */
+const DRIVE: DriveLetter = 'T:'
+
+export default DRIVE

__tests__/plugins/chai-path.mts

@@ -0,0 +1,62 @@
+/**
+ * @file Plugins - chaiPath
+ * @module tests/plugins/chaiPath
+ */
+
+import type Chai from 'chai'
+import path from 'node:path'
+
+export default plugin
+
+/**
+ * Chai assertion plugin for the Node.js [path][node-path] API.
+ *
+ * [node-path]: https://nodejs.org/api/path.html
+ *
+ * @see {@linkcode Chai.ChaiStatic}
+ * @see {@linkcode Chai.ChaiUtils}
+ *
+ * @param {ChaiStatic} chai
+ *  `chai` export
+ * @param {Chai.ChaiUtils} utils
+ *  `chai` utilities
+ * @return {undefined}
+ */
+function plugin(chai: Chai.ChaiStatic, utils: Chai.ChaiUtils): undefined {
+  utils.addMethod(chai.Assertion.prototype, extname.name, extname)
+
+  return void 0
+
+  /**
+   * Assert the return value of {@linkcode path.extname}.
+   *
+   * @this {Chai.Assertion}
+   *
+   * @param {unknown} expected
+   *  Expected file extension
+   * @return {undefined}
+   */
+  function extname(this: Chai.Assertion, expected: unknown): undefined {
+    /**
+     * Subject of assertion.
+     *
+     * @const {string} subject
+     */
+    const subject: string = utils.flag(this, 'object')
+
+    /**
+     * File extension.
+     *
+     * @const {string} ext
+     */
+    const actual: string = path.extname(subject)
+
+    return void this.assert(
+      actual === expected,
+      'expected extname of #{this} to be #{exp} but got #{act}',
+      'expected extname of #{this} to not be #{act}',
+      expected,
+      actual
+    )
+  }
+}

__tests__/setup/chai.mts

@@ -0,0 +1,17 @@
+/**
+ * @file Test Setup - chai
+ * @module tests/setup/chai
+ * @see https://chaijs.com
+ */
+
+import chaiPath from '#tests/plugins/chai-path'
+import chaiString from 'chai-string'
+import { chai } from 'vitest'
+
+/**
+ * initialize chai plugins.
+ *
+ * @see https://github.com/onechiporenko/chai-string
+ */
+chai.use(chaiPath)
+chai.use(chaiString)

__tests__/utils/cwd-windows.mts

@@ -0,0 +1,21 @@
+/**
+ * @file Test Utilities - cwdWindows
+ * @module tests/utils/cwdWindows
+ */
+
+import DRIVE from '#fixtures/drive'
+import { ok } from 'devlop'
+import { posix, win32 } from 'node:path'
+
+/**
+ * Get the path to the current working directory as a windows drive path.
+ *
+ * @return {string}
+ *  Absolute path to current working directory
+ */
+function cwdWindows(): string {
+  ok(typeof process.env['PWD'] === 'string', 'expected `process.env.PWD`')
+  return DRIVE + process.env['PWD'].replaceAll(posix.sep, win32.sep)
+}
+
+export default cwdWindows

package.json

@@ -182,6 +182,8 @@
     "@flex-development/tutils": "6.0.0-alpha.25",
     "@stylistic/eslint-plugin": "2.10.1",
     "@tsconfig/strictest": "2.0.5",
+    "@types/chai": "5.0.1",
+    "@types/chai-string": "1.4.5",
     "@types/eslint": "9.6.1",
     "@types/eslint__js": "8.42.3",
     "@types/is-ci": "3.0.4",
@@ -192,6 +194,8 @@
     "@vates/toggle-scripts": "1.0.0",
     "@vitest/coverage-v8": "2.1.4",
     "@vitest/ui": "2.1.4",
+    "chai": "5.1.2",
+    "chai-string": "1.5.0",
     "consola": "3.2.3",
     "cross-env": "7.0.3",
     "cspell": "8.16.0",

src/__snapshots__/index.e2e.snap

@@ -17,6 +17,7 @@ exports[`e2e:pathe > should expose public api 1`] = `
   "isAbsolute",
   "isDeviceRoot",
   "isSep",
+  "isURL",
   "join",
   "matchesGlob",
   "normalize",
@@ -29,6 +30,7 @@ exports[`e2e:pathe > should expose public api 1`] = `
   "root",
   "sep",
   "toNamespacedPath",
+  "toPath",
   "toPosix",
   "default",
   "posix",

src/interfaces/__tests__/file-url-to-path-options.spec-d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Unit Tests - FileUrlToPathOptions
+ * @module pathe/interfaces/tests/unit-d/FileUrlToPathOptions
+ */
+
+import type TestSubject from '#interfaces/file-url-to-path-options'
+import type { PlatformOptions } from '@flex-development/pathe'
+
+describe('unit-d:interfaces/FileUrlToPathOptions', () => {
+  it('should extend PlatformOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<PlatformOptions>()
+  })
+})

src/interfaces/__tests__/path-to-file-url-options.spec-d.mts

@@ -0,0 +1,20 @@
+/**
+ * @file Unit Tests - PathToFileUrlOptions
+ * @module pathe/interfaces/tests/unit-d/PathToFileUrlOptions
+ */
+
+import type TestSubject from '#interfaces/path-to-file-url-options'
+import type {
+  PlatformOptions,
+  ResolveWithOptions
+} from '@flex-development/pathe'
+
+describe('unit-d:interfaces/PathToFileUrlOptions', () => {
+  it('should extend PlatformOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<PlatformOptions>()
+  })
+
+  it('should extend ResolveWithOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<ResolveWithOptions>()
+  })
+})

src/interfaces/__tests__/relative-options.spec-d.mts

@@ -0,0 +1,13 @@
+/**
+ * @file Unit Tests - RelativeOptions
+ * @module pathe/interfaces/tests/unit-d/RelativeOptions
+ */
+
+import type TestSubject from '#interfaces/relative-options'
+import type { ResolveWithOptions } from '@flex-development/pathe'
+
+describe('unit-d:interfaces/RelativeOptions', () => {
+  it('should extend ResolveWithOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<ResolveWithOptions>()
+  })
+})

src/interfaces/__tests__/resolve-with-options.spec-d.mts

@@ -0,0 +1,22 @@
+/**
+ * @file Unit Tests - ResolveWithOptions
+ * @module pathe/interfaces/tests/unit-d/ResolveWithOptions
+ */
+
+import type TestSubject from '#interfaces/resolve-with-options'
+import type { Cwd } from '@flex-development/pathe'
+import type { Nilable } from '@flex-development/tutils'
+
+describe('unit-d:interfaces/ResolveWithOptions', () => {
+  it('should match [cwd?: Cwd | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('cwd')
+      .toEqualTypeOf<Nilable<Cwd>>()
+  })
+
+  it('should match [env?: Partial<Record<string, string>> | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('env')
+      .toEqualTypeOf<Nilable<Partial<Record<string, string>>>>()
+  })
+})

src/interfaces/__tests__/to-path-options.spec-d.mts

@@ -0,0 +1,20 @@
+/**
+ * @file Unit Tests - ToPathOptions
+ * @module pathe/interfaces/tests/unit-d/ToPathOptions
+ */
+
+import type TestSubject from '#interfaces/to-path-options'
+import type {
+  FileUrlToPathOptions,
+  PlatformOptions
+} from '@flex-development/pathe'
+
+describe('unit-d:interfaces/ToPathOptions', () => {
+  it('should extend FileUrlToPathOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<FileUrlToPathOptions>()
+  })
+
+  it('should extend PlatformOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<PlatformOptions>()
+  })
+})

src/interfaces/file-url-to-path-options.mts

@@ -0,0 +1,17 @@
+/**
+ * @file Interfaces - FileUrlToPathOptions
+ * @module pathe/interfaces/FileUrlToPathOptions
+ */
+
+import type { PlatformOptions } from '@flex-development/pathe'
+
+/**
+ * Options for converting `file:` URLs to paths.
+ *
+ * @see {@linkcode PlatformOptions}
+ *
+ * @extends {PlatformOptions}
+ */
+interface FileUrlToPathOptions extends PlatformOptions {}
+
+export type { FileUrlToPathOptions as default }

src/interfaces/index.mts

@@ -3,11 +3,17 @@
  * @module pathe/interfaces
  */
 
+export type {
+  default as FileUrlToPathOptions
+} from '#interfaces/file-url-to-path-options'
 export type {
   default as FormatInputPathObject,
   default as PathObject
 } from '#interfaces/format-input-path-object'
 export type { default as ParsedPath } from '#interfaces/parsed-path'
+export type {
+  default as PathToFileUrlOptions
+} from '#interfaces/path-to-file-url-options'
 export type { default as Pathe } from '#interfaces/pathe'
 export type { default as PlatformOptions } from '#interfaces/platform-options'
 export type { default as PlatformPath } from '#interfaces/platform-path'
@@ -17,3 +23,8 @@ export type {
 export type {
   default as WindowsPlatformPath
 } from '#interfaces/platform-path-windows'
+export type { default as RelativeOptions } from '#interfaces/relative-options'
+export type {
+  default as ResolveWithOptions
+} from '#interfaces/resolve-with-options'
+export type { default as ToPathOptions } from '#interfaces/to-path-options'