feat(lib): createModuleResolutionHost

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

Author: unicornware

README.md

@@ -81,6 +81,7 @@ import {
 
 This package exports the following identifiers:
 
+- [`createModuleResolutionHost`](./src/lib/create-module-resolution-host.mts)
 - [`isResolvedTsconfig`](./src/lib/is-resolved-tsconfig.mts)
 - [`isTsconfigHost`](./src/lib/is-tsconfig-host.mts)
 - [`loadTsconfig`](./src/lib/load-tsconfig.mts)

package.json

@@ -66,8 +66,11 @@
         "tsconfig-utils": "./src/internal/fs.browser.mts",
         "default": "./dist/internal/fs.browser.mjs"
       },
-      "node": "fs/promises",
-      "default": "fs/promises"
+      "node": {
+        "tsconfig-utils": "./src/internal/fs.node.mts",
+        "default": "./dist/internal/fs.node.mjs"
+      },
+      "default": "./dist/internal/fs.node.mjs"
     },
     "#internal/*": {
       "tsconfig-utils": "./src/internal/*.mts",

src/__snapshots__/index.e2e.snap

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

src/interfaces/__tests__/file-system.spec-d.mts

@@ -10,4 +10,84 @@ describe('unit-d:interfaces/FileSystem', () => {
   it('should extend mlly.FileSystem', () => {
     expectTypeOf<TestSubject>().toMatchTypeOf<mlly.FileSystem>()
   })
+
+  describe('readFile', () => {
+    type Subject = TestSubject['readFile']
+
+    it('should match [this: void]', () => {
+      expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
+    })
+
+    describe('parameters', () => {
+      it('should be callable with [mlly.ModuleId]', () => {
+        expectTypeOf<Subject>().parameters.toEqualTypeOf<[mlly.ModuleId]>()
+      })
+    })
+
+    describe('returns', () => {
+      it('should return Buffer | string', () => {
+        expectTypeOf<Subject>().returns.toEqualTypeOf<Buffer | string>()
+      })
+    })
+  })
+
+  describe('readdir', () => {
+    type Subject = TestSubject['readdir']
+
+    it('should match [this: void]', () => {
+      expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
+    })
+
+    describe('parameters', () => {
+      it('should be callable with [mlly.ModuleId]', () => {
+        expectTypeOf<Subject>().parameters.toEqualTypeOf<[mlly.ModuleId]>()
+      })
+    })
+
+    describe('returns', () => {
+      it('should return string[]', () => {
+        expectTypeOf<Subject>().returns.toEqualTypeOf<string[]>()
+      })
+    })
+  })
+
+  describe('realpath', () => {
+    type Subject = TestSubject['realpath']
+
+    it('should match [this: void]', () => {
+      expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
+    })
+
+    describe('parameters', () => {
+      it('should be callable with [mlly.ModuleId]', () => {
+        expectTypeOf<Subject>().parameters.toEqualTypeOf<[mlly.ModuleId]>()
+      })
+    })
+
+    describe('returns', () => {
+      it('should return string', () => {
+        expectTypeOf<Subject>().returns.toEqualTypeOf<string>()
+      })
+    })
+  })
+
+  describe('stat', () => {
+    type Subject = TestSubject['stat']
+
+    it('should match [this: void]', () => {
+      expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
+    })
+
+    describe('parameters', () => {
+      it('should be callable with [mlly.ModuleId]', () => {
+        expectTypeOf<Subject>().parameters.toEqualTypeOf<[mlly.ModuleId]>()
+      })
+    })
+
+    describe('returns', () => {
+      it('should return mlly.Stats', () => {
+        expectTypeOf<Subject>().returns.toEqualTypeOf<mlly.Stats>()
+      })
+    })
+  })
 })

src/interfaces/file-system.mts

@@ -12,6 +12,69 @@ import type * as mlly from '@flex-development/mlly'
  *
  * @extends {mlly.FileSystem}
  */
-interface FileSystem extends mlly.FileSystem {}
+interface FileSystem extends mlly.FileSystem {
+  /**
+   * Get the contents of a file.
+   *
+   * @see {@linkcode Buffer}
+   * @see {@linkcode mlly.ModuleId}
+   *
+   * @override
+   *
+   * @this {void}
+   *
+   * @param {mlly.ModuleId} id
+   *  The path or `file:` URL to handle
+   * @return {Buffer | string}
+   *  File contents
+   */
+  readFile(this: void, id: mlly.ModuleId): Buffer | string
 
+  /**
+   * Read the contents of a directory.
+   *
+   * @see {@linkcode mlly.ModuleId}
+   *
+   * @this {void}
+   *
+   * @param {mlly.ModuleId} id
+   *  The path or `file:` URL to handle
+   * @return {string[]}
+   *  List of filenames
+   */
+  readdir(this: void, id: mlly.ModuleId): string[]
+
+  /**
+   * Get the canonical pathname of `id`.
+   *
+   * @see {@linkcode mlly.ModuleId}
+   *
+   * @override
+   *
+   * @this {void}
+   *
+   * @param {mlly.ModuleId} id
+   *  The path or `file:` URL to handle
+   * @return {string}
+   *  Canonical pathname of `id`
+   */
+  realpath(this: void, id: mlly.ModuleId): string
+
+  /**
+   * Get information about a directory or file.
+   *
+   * @see {@linkcode mlly.ModuleId}
+   * @see {@linkcode mlly.Stats}
+   *
+   * @override
+   *
+   * @this {void}
+   *
+   * @param {mlly.ModuleId} id
+   *  The path or `file:` URL to handle
+   * @return {mlly.Stats}
+   *  Info about `id`
+   */
+  stat(this: void, id: mlly.ModuleId): mlly.Stats
+}
 export type { FileSystem as default }

src/interfaces/host-module-resolution.mts

@@ -72,14 +72,14 @@ interface ModuleResolutionHost {
    * @this {void}
    *
    * @param {ModuleId} id
-   *  Module id of file
+   *  The file path or URL to read
    * @return {Buffer | string}
    *  File contents or `undefined` if file does not exist at `id`
    */
   readFile(this: void, id: ModuleId): string | undefined
 
   /**
-   * Get the resolved pathname for `id`.
+   * Get the canonical pathname of `id`.
    *
    * @see {@linkcode ModuleId}
    *
@@ -88,7 +88,7 @@ interface ModuleResolutionHost {
    * @param {ModuleId} id
    *  The path or `file:` URL to handle
    * @return {string}
-   *  Resolved pathname
+   *  Canonical pathname of `id`
    */
   realpath(this: void, id: ModuleId): string
 

src/internal/fs.browser.mts

@@ -12,7 +12,7 @@ import type { FileSystem } from '@flex-development/tsconfig-utils'
  */
 const fs: FileSystem = {
   /**
-   * Get the contents of a file.
+   * Synchronously get the contents of a file.
    *
    * @return {never}
    *  Never; not implemented
@@ -23,7 +23,18 @@ const fs: FileSystem = {
   },
 
   /**
-   * Get the resolved pathname of a file.
+   * Synchronously read the contents of a directory.
+   *
+   * @return {never}
+   *  Never; not implemented
+   * @throws {Error}
+   */
+  readdir(): never {
+    throw new Error('[readdir] not implemented')
+  },
+
+  /**
+   * Get the canonical pathname of a directory or file.
    *
    * @return {never}
    *  Never; not implemented
@@ -34,7 +45,7 @@ const fs: FileSystem = {
   },
 
   /**
-   * Get information about a file.
+   * Synchronously get information about a directory or file.
    *
    * @return {never}
    *  Never; not implemented

src/internal/fs.node.mts

@@ -0,0 +1,21 @@
+/**
+ * @file Internal - fs/node
+ * @module mkbuild/internal/fs/node
+ */
+
+import type { FileSystem } from '@flex-development/tsconfig-utils'
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+
+/**
+ * File system API.
+ *
+ * @const {FileSystem} fs
+ */
+const fs: FileSystem = {
+  readFile: readFileSync,
+  readdir: readdirSync,
+  realpath: realpathSync,
+  stat: statSync
+}
+
+export default fs

src/lib/__tests__/create-module-resolution-host.spec.mts

@@ -0,0 +1,111 @@
+/**
+ * @file Unit Tests - createModuleResolutionHost
+ * @module tsconfig-utils/lib/tests/unit/createModuleResolutionHost
+ */
+
+import testSubject from '#lib/create-module-resolution-host'
+import * as mlly from '@flex-development/mlly'
+import pathe from '@flex-development/pathe'
+import type { ModuleResolutionHost } from '@flex-development/tsconfig-utils'
+import ts from 'typescript'
+
+describe('unit:lib/createModuleResolutionHost', () => {
+  let subject: ModuleResolutionHost
+
+  beforeAll(() => {
+    subject = testSubject()
+  })
+
+  describe('host', () => {
+    describe('directoryExists', () => {
+      it.each<Parameters<ModuleResolutionHost['directoryExists']>>([
+        [import.meta.url],
+        [new URL('node:fs')]
+      ])('should return `false` if `id` is not a directory (%j)', id => {
+        expect(subject.directoryExists(id)).to.be.false
+      })
+
+      it.each<Parameters<ModuleResolutionHost['directoryExists']>>([
+        [String(pathe.cwd())],
+        [new URL(mlly.cwd())]
+      ])('should return `true` if `id` is a directory (%j)', id => {
+        expect(subject.directoryExists(id)).to.be.true
+      })
+    })
+
+    describe('fileExists', () => {
+      it.each<Parameters<ModuleResolutionHost['fileExists']>>([
+        ['package-lock.json'],
+        [String(pathe.cwd())],
+        [new URL(mlly.cwd())]
+      ])('should return `false` if `id` is not a file  (%j)', id => {
+        expect(subject.fileExists(id)).to.be.false
+      })
+
+      it.each<Parameters<ModuleResolutionHost['fileExists']>>([
+        ['package.json'],
+        [String(new URL('vitest.config.mts', mlly.cwd()))],
+        [import.meta.url]
+      ])('should return `true` if `id` is a file (%j)', id => {
+        expect(subject.fileExists(id)).to.be.true
+      })
+    })
+
+    describe('getCurrentDirectory', () => {
+      it('should return path to current working directory', () => {
+        expect(subject.getCurrentDirectory()).to.eq(pathe.cwd() + pathe.sep)
+      })
+    })
+
+    describe('getDirectories', () => {
+      it('should return list of subdirectory names', () => {
+        // Arrange
+        const id: string = pathe.dirname(pathe.dirname(import.meta.url))
+        const path: string = pathe.fileURLToPath(id)
+
+        // Act + Expect
+        expect(subject.getDirectories(id)).to.eql(ts.sys.getDirectories(path))
+      })
+    })
+
+    describe('readFile', () => {
+      it('should return `undefined` if file does not exist at `id`', () => {
+        // Arrange
+        const id: string = 'src/index.cts'
+
+        // Act + Expect
+        expect(subject.readFile(id)).to.eq(ts.sys.readFile(id)).and.be.undefined
+      })
+
+      it.each<Parameters<ModuleResolutionHost['readFile']>>([
+        ['src/index.mts'],
+        [import.meta.url]
+      ])('should return contents of file at `id` (%j)', id => {
+        // Arrange
+        const path: string = pathe.toPath(id)
+
+        // Act
+        const result = subject.readFile(id)
+
+        // Expect
+        expect(result).to.eq(ts.sys.readFile(path)).and.not.be.undefined
+      })
+    })
+
+    describe('realpath', () => {
+      it.each<Parameters<ModuleResolutionHost['realpath']>>([
+        ['src/lib/..'],
+        [pathe.dirname(import.meta.url) + pathe.sep + pathe.dot.repeat(2)]
+      ])('should return canonical pathname of `id` (%j)', id => {
+        // Arrange
+        const path: string = pathe.toPath(id)
+
+        // Act
+        const result = subject.realpath(id)
+
+        // Expect
+        expect(result).to.eq(ts.sys.realpath!(path)).and.not.be.undefined
+      })
+    })
+  })
+})