feat(lib): createGetCanonicalFileName

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

Author: unicornware

README.md

@@ -20,8 +20,9 @@ Utilities for working with [`tsconfig`][tsconfig] files
 - [Use](#use)
 - [API](#api)
 - [Types](#types)
-  - [Interfaces](#interfaces)
   - [`tsconfig-types`](#tsconfig-types)
+  - [Interfaces](#interfaces)
+  - [Types](#types)
 - [Related](#related)
 - [Contribute](#contribute)
 
@@ -81,6 +82,7 @@ import {
 
 This package exports the following identifiers:
 
+- [`createGetCanonicalFileName`](./src/lib/create-get-canonical-file-name.mts)
 - [`createModuleResolutionHost`](./src/lib/create-module-resolution-host.mts)
 - [`createParseConfigHost`](./src/lib/create-parse-config-host.mts)
 - [`isResolvedTsconfig`](./src/lib/is-resolved-tsconfig.mts)
@@ -96,6 +98,11 @@ There is no default export.
 
 This package is fully typed with [TypeScript][].
 
+### `tsconfig-types`
+
+This package re-exports TypeScript definitions from [`tsconfig-types`][tsconfig-types]. This is primarily for the
+convenience of TypeScript users who do not hoist packages, but may need to `import` definitions used in this package.
+
 ### Interfaces
 
 - [`FileSystem`](./src/interfaces/file-system.mts)
@@ -109,10 +116,9 @@ This package is fully typed with [TypeScript][].
 - [`ResolvedTsconfig`](./src/interfaces/options-resolve-path.mts)
 - [`TsconfigHost`](./src/interfaces/tsconfig-host.mts)
 
-### `tsconfig-types`
+### Types
 
-This package re-exports TypeScript definitions from [`tsconfig-types`][tsconfig-types]. This is primarily for the
-convenience of TypeScript users who do not hoist packages, but may need to `import` definitions used in this package.
+- [`GetCanonicalFileName`](./src/types/get-canonical-file-name.mts)
 
 ## Related
 

package.json

@@ -80,7 +80,11 @@
       "tsconfig-utils": "./src/lib/*.mts",
       "default": "./dist/lib/*.mjs"
     },
-    "#tests/*": "./__tests__/*.mts"
+    "#tests/*": "./__tests__/*.mts",
+    "#types/*": {
+      "tsconfig-utils": "./src/types/*.mts",
+      "default": "./dist/types/*.d.mts"
+    }
   },
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",

src/__snapshots__/index.e2e.snap

@@ -2,6 +2,7 @@
 
 exports[`e2e:tsconfig-utils > should expose public api 1`] = `
 [
+  "createGetCanonicalFileName",
   "createModuleResolutionHost",
   "createParseConfigHost",
   "isResolvedTsconfig",

src/index.mts

@@ -5,4 +5,5 @@
 
 export type * from '#interfaces/index'
 export * from '#lib/index'
+export type * from '#types/index'
 export type * from '@flex-development/tsconfig-types'

src/internal/__snapshots__/to-path.snap

@@ -0,0 +1,5 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`unit:internal/toPath > should return \`input\` as path ("./tsconfig.json") 1`] = `"./tsconfig.json"`;
+
+exports[`unit:internal/toPath > should return \`input\` as path ("file:///tsconfig.json") 1`] = `"/tsconfig.json"`;

src/internal/__tests__/to-path.spec.mts

@@ -0,0 +1,41 @@
+/**
+ * @file Unit Tests - toPath
+ * @module tsconfig-utils/internal/tests/unit/toPath
+ */
+
+import testSubject from '#internal/to-path'
+import { codes, isNodeError, type NodeError } from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+
+describe('unit:internal/toPath', () => {
+  it.each<[URL | string]>([
+    [new URL('file:///tsconfig.json')],
+    [pathe.dot + pathe.sep + 'tsconfig.json']
+  ])('should return `input` as path (%j)', input => {
+    // Act
+    const result = testSubject(input)
+
+    // Expect
+    expect(result).toMatchSnapshot()
+  })
+
+  it.each<[URL | string]>([
+    ['node:test'],
+    [new URL('node:test/reporters')]
+  ])('should throw if `input` is not a path or `file:` URL (%j)', input => {
+    // Arrange
+    let error!: NodeError
+
+    // Act
+    try {
+      testSubject(input)
+    } catch (e: unknown) {
+      error = e as typeof error
+    }
+
+    // Expect
+    expect(error).to.satisfy(isNodeError)
+    expect(error).to.have.property('code', codes.ERR_INVALID_URL_SCHEME)
+    expect(error).to.have.property('message').match(/of scheme file/)
+  })
+})

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

@@ -0,0 +1,39 @@
+/**
+ * @file Unit Tests - validateURLString
+ * @module tsconfig-utils/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 `URL`', () => {
+    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/to-path.mts

@@ -0,0 +1,47 @@
+/**
+ * @file Internal - toPath
+ * @module tsconfig-utils/internal/toPath
+ */
+
+import validateURLString from '#internal/validate-url-string'
+import {
+  ERR_INVALID_URL_SCHEME,
+  type ErrInvalidUrlScheme
+} from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+
+export default toPath
+
+/**
+ * Convert `input` to a path.
+ *
+ * > 👉 **Note**: `input` is assumed to be a path if it a string and cannot be
+ * > parsed to an URL (checked using {@linkcode pathe.isURL}).
+ *
+ * @see {@linkcode ErrInvalidUrlScheme}
+ *
+ * @internal
+ *
+ * @this {void}
+ *
+ * @param {URL | string} input
+ *  The {@linkcode URL}, URL string, or path to convert
+ * @return {string}
+ *  `input` as path
+ * @throws {ErrInvalidUrlScheme}
+ *  If `input` is not a path or `file:` URL
+ */
+function toPath(
+  this: void,
+  input: URL | string
+): string {
+  validateURLString(input, 'input')
+
+  if (typeof input === 'string') {
+    if (!pathe.isURL(input)) return pathe.toPosix(input)
+    input = new URL(input)
+  }
+
+  if (input.protocol === 'file:') return pathe.fileURLToPath(input)
+  throw new ERR_INVALID_URL_SCHEME('file')
+}

src/internal/validate-url-string.mts

@@ -0,0 +1,36 @@
+/**
+ * @file Internal - validateURLString
+ * @module tsconfig-utils/internal/validateURLString
+ */
+
+import {
+  ERR_INVALID_ARG_TYPE,
+  type ErrInvalidArgType
+} from '@flex-development/errnode'
+import pathe from '@flex-development/pathe'
+
+/**
+ * Check if `value` is a {@linkcode URL} object or string.
+ *
+ * @see {@linkcode ErrInvalidArgType}
+ *
+ * @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 `URL` object or string
+ * @throws {ErrInvalidArgType}
+ *  If `value` is not `URL` object or string
+ */
+function validateURLString(
+  value: unknown,
+  name: string
+): value is URL | string {
+  if (typeof value === 'string' || pathe.isURL(value)) return true
+  throw new ERR_INVALID_ARG_TYPE(name, ['URL', 'string'], value)
+}
+
+export default validateURLString

src/lib/__tests__/create-get-canonical-file-name.spec.mts

@@ -0,0 +1,23 @@
+/**
+ * @file Unit Tests - createGetCanonicalFileName
+ * @module tsconfig-utils/lib/tests/unit/createGetCanonicalFileName
+ */
+
+import toPath from '#internal/to-path'
+import testSubject from '#lib/create-get-canonical-file-name'
+import pathe from '@flex-development/pathe'
+import { lowercase } from '@flex-development/tutils'
+
+describe('unit:lib/createGetCanonicalFileName', () => {
+  it('should return canonical filename of `id`', () => {
+    // Arrange
+    const id: URL = new URL('file:///creatE-geT-canonicaL-filE-namE.mts')
+
+    // Act
+    const result = testSubject()(id)
+
+    // Expect
+    expect(result).to.be.a('string').and.not.satisfy(pathe.isURL)
+    expect(lowercase(result)).to.eql(lowercase(toPath(id)))
+  })
+})