refactor: async api

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

build/make.mts

@@ -183,7 +183,7 @@ async function make(
    *
    * @const {PackageJson | null} pkg
    */
-  const pkg: PackageJson | null = readPackageJson(
+  const pkg: PackageJson | null = await readPackageJson(
     pathe.pathToFileURL(absWorkingDir + pathe.sep)
   )
 

package.json

@@ -60,8 +60,8 @@
         "mlly": "./src/internal/fs.browser.mts",
         "default": "./dist/internal/fs.browser.mjs"
       },
-      "node": "fs",
-      "default": "fs"
+      "node": "fs/promises",
+      "default": "fs/promises"
     },
     "#internal/process": {
       "types": {

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

@@ -4,11 +4,11 @@
  */
 
 import type TestSubject from '#interfaces/file-system'
-import type { ModuleId, Stats } from '@flex-development/mlly'
+import type { Awaitable, ModuleId, Stats } from '@flex-development/mlly'
 
 describe('unit-d:interfaces/FileSystem', () => {
-  describe('readFileSync', () => {
-    type Subject = TestSubject['readFileSync']
+  describe('readFile', () => {
+    type Subject = TestSubject['readFile']
 
     it('should match [this: void]', () => {
       expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
@@ -21,14 +21,16 @@ describe('unit-d:interfaces/FileSystem', () => {
     })
 
     describe('returns', () => {
-      it('should return Buffer | string', () => {
-        expectTypeOf<Subject>().returns.toEqualTypeOf<Buffer | string>()
+      it('should return Awaitable<Buffer | string>', () => {
+        expectTypeOf<Subject>()
+          .returns
+          .toEqualTypeOf<Awaitable<Buffer | string>>()
       })
     })
   })
 
-  describe('realpathSync', () => {
-    type Subject = TestSubject['realpathSync']
+  describe('realpath', () => {
+    type Subject = TestSubject['realpath']
 
     it('should match [this: void]', () => {
       expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
@@ -41,14 +43,14 @@ describe('unit-d:interfaces/FileSystem', () => {
     })
 
     describe('returns', () => {
-      it('should return string', () => {
-        expectTypeOf<Subject>().returns.toEqualTypeOf<string>()
+      it('should return Awaitable<string>', () => {
+        expectTypeOf<Subject>().returns.toEqualTypeOf<Awaitable<string>>()
       })
     })
   })
 
-  describe('statSync', () => {
-    type Subject = TestSubject['statSync']
+  describe('stat', () => {
+    type Subject = TestSubject['stat']
 
     it('should match [this: void]', () => {
       expectTypeOf<Subject>().thisParameter.toEqualTypeOf<void>()
@@ -61,8 +63,8 @@ describe('unit-d:interfaces/FileSystem', () => {
     })
 
     describe('returns', () => {
-      it('should return Stats', () => {
-        expectTypeOf<Subject>().returns.toEqualTypeOf<Stats>()
+      it('should return Awaitable<Stats>', () => {
+        expectTypeOf<Subject>().returns.toEqualTypeOf<Awaitable<Stats>>()
       })
     })
   })

src/interfaces/file-system.mts

@@ -3,7 +3,7 @@
  * @module mlly/interfaces/FileSystem
  */
 
-import type { ModuleId, Stats } from '@flex-development/mlly'
+import type { Awaitable, ModuleId, Stats } from '@flex-development/mlly'
 
 /**
  * File system API.
@@ -12,47 +12,51 @@ interface FileSystem {
   /**
    * Get the contents of `id`.
    *
+   * @see {@linkcode Awaitable}
+   * @see {@linkcode Buffer}
    * @see {@linkcode ModuleId}
    * @see https://nodejs.org/api/fs.html#fsreadfilepath-options-callback
    *
    * @this {void}
    *
    * @param {ModuleId} id
    *  The path or `file:` URL to handle
-   * @return {Buffer | string}
+   * @return {Awaitable<Buffer | string>}
    *  File contents
    */
-  readFileSync(this: void, id: ModuleId): Buffer | string
+  readFile(this: void, id: ModuleId): Awaitable<Buffer | string>
 
   /**
    * Get the resolved pathname for `id`.
    *
+   * @see {@linkcode Awaitable}
    * @see {@linkcode ModuleId}
    * @see https://nodejs.org/api/fs.html#fsrealpathpath-options-callback
    *
    * @this {void}
    *
    * @param {ModuleId} id
    *  The path or `file:` URL to handle
-   * @return {string}
+   * @return {Awaitable<string>}
    *  Resolved pathname
    */
-  realpathSync(this: void, id: ModuleId): string
+  realpath(this: void, id: ModuleId): Awaitable<string>
 
   /**
    * Get information about a directory or file.
    *
+   * @see {@linkcode Awaitable}
    * @see {@linkcode ModuleId}
    * @see {@linkcode Stats}
    *
    * @this {void}
    *
    * @param {ModuleId} id
    *  The path or `file:` URL to handle
-   * @return {Stats}
+   * @return {Awaitable<Stats>}
    *  Info about `id`
    */
-  statSync(this: void, id: ModuleId): Stats
+  stat(this: void, id: ModuleId): Awaitable<Stats>
 }
 
 export type { FileSystem as default }

src/internal/fs.browser.mts

@@ -18,8 +18,8 @@ const fs: FileSystem = {
    *  Never; not implemented
    * @throws {Error}
    */
-  readFileSync(): never {
-    throw new Error('[readFileSync] not implemented')
+  readFile(): never {
+    throw new Error('[readFile] not implemented')
   },
 
   /**
@@ -29,8 +29,8 @@ const fs: FileSystem = {
    *  Never; not implemented
    * @throws {Error}
    */
-  realpathSync(): never {
-    throw new Error('[realpathSync] not implemented')
+  realpath(): never {
+    throw new Error('[realpath] not implemented')
   },
 
   /**
@@ -40,8 +40,8 @@ const fs: FileSystem = {
    *  Never; not implemented
    * @throws {Error}
    */
-  statSync(): never {
-    throw new Error('[statSync] not implemented')
+  stat(): never {
+    throw new Error('[stat] not implemented')
   }
 }
 

src/lib/__snapshots__/resolve-module.snap

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`unit:lib/resolveModule > should return resolved URL ("#internal/fs") 1`] = `"node:fs"`;
+exports[`unit:lib/resolveModule > should return resolved URL ("#internal/fs") 1`] = `"node:fs/promises"`;
 
 exports[`unit:lib/resolveModule > should return resolved URL ("../../../src") 1`] = `file://\${process.cwd()}/src/index.mts`;
 

src/lib/__snapshots__/resolver.snap

@@ -2,7 +2,7 @@
 
 exports[`unit:lib/resolver > legacyMainResolve > should throw if main entry point is not found 1`] = `Cannot find package '\${process.cwd()}/__fixtures__/node_modules/@flex-development/mlly/' imported from \${process.cwd()}/__fixtures__/parent.mts`;
 
-exports[`unit:lib/resolver > moduleResolve > should return resolved URL (0) 1`] = `"node:fs"`;
+exports[`unit:lib/resolver > moduleResolve > should return resolved URL (0) 1`] = `"node:fs/promises"`;
 
 exports[`unit:lib/resolver > moduleResolve > should return resolved URL (1) 1`] = `file://\${process.cwd()}/src/internal/fs.browser.mts`;
 

src/lib/__tests__/is-directory.spec.mts

@@ -7,21 +7,21 @@ import cwd from '#lib/cwd'
 import testSubject from '#lib/is-directory'
 import type { ModuleId } from '@flex-development/mlly'
 import { pathToFileURL } from '@flex-development/pathe'
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 
 describe('unit:lib/isDirectory', () => {
   it.each<ModuleId>([
     'directory',
     new URL('node:fs'),
     String(new URL('src/index.mts', cwd()))
-  ])('should return `false` if `id` is not a directory (%#)', id => {
-    expect(testSubject(id, fs)).to.be.false
+  ])('should return `false` if `id` is not a directory (%#)', async id => {
+    expect(await testSubject(id, fs)).to.be.false
   })
 
   it.each<ModuleId>([
     pathToFileURL('src'),
     String(cwd())
-  ])('should return `true` if `id` is a directory (%#)', id => {
-    expect(testSubject(id)).to.be.true
+  ])('should return `true` if `id` is a directory (%#)', async id => {
+    expect(await testSubject(id)).to.be.true
   })
 })

src/lib/__tests__/is-file.spec.mts

@@ -7,21 +7,21 @@ import cwd from '#lib/cwd'
 import testSubject from '#lib/is-file'
 import type { ModuleId } from '@flex-development/mlly'
 import { pathToFileURL } from '@flex-development/pathe'
-import fs from 'node:fs'
+import fs from 'node:fs/promises'
 
 describe('unit:lib/isFile', () => {
   it.each<ModuleId>([
     'file.mjs',
     new URL('node:fs'),
     String(cwd())
-  ])('should return `false` if `id` is not a file (%#)', id => {
-    expect(testSubject(id, fs)).to.be.false
+  ])('should return `false` if `id` is not a file (%#)', async id => {
+    expect(await testSubject(id, fs)).to.be.false
   })
 
   it.each<ModuleId>([
     pathToFileURL('package.json'),
     String(new URL('vitest.config.mts', cwd()))
-  ])('should return `true` if `id` is a file (%#)', id => {
-    expect(testSubject(id)).to.be.true
+  ])('should return `true` if `id` is a file (%#)', async id => {
+    expect(await testSubject(id)).to.be.true
   })
 })

src/lib/__tests__/lookup-package-scope.spec.mts

@@ -7,12 +7,12 @@ import testSubject from '#lib/lookup-package-scope'
 import { pathToFileURL, sep } from '@flex-development/pathe'
 
 describe('unit:lib/lookupPackageScope', () => {
-  it('should return `null` if package directory is not found', () => {
+  it('should return `null` if package directory is not found', async () => {
     // Arrange
     const url: URL = pathToFileURL('node_modules/@flex-development/404.mjs')
 
     // Act + Expect
-    expect(testSubject(url)).to.be.null
+    expect(await testSubject(url)).to.be.null
   })
 
   it.each<Parameters<typeof testSubject>>([
@@ -24,9 +24,9 @@ describe('unit:lib/lookupPackageScope', () => {
       'node_modules/@commitlint/cli/node_modules/@commitlint/config-validator/lib/validate.js'
     )],
     [pathToFileURL('node_modules/esbuild/lib/main.js')]
-  ])('should return URL of package directory (%#)', url => {
+  ])('should return URL of package directory (%#)', async url => {
     // Act
-    const result = testSubject(url)
+    const result = await testSubject(url)
     const resultStr = String(result)
 
     // Expect

src/lib/__tests__/read-package-json.spec.mts

@@ -14,18 +14,18 @@ import {
 import pkg from '@flex-development/mlly/package.json'
 
 describe('unit:lib/readPackageJson', () => {
-  it('should return `null` if `package.json` file is not found', () => {
-    expect(testSubject(import.meta.url)).to.be.null
+  it('should return `null` if `package.json` file is not found', async () => {
+    expect(await testSubject(import.meta.url)).to.be.null
   })
 
-  it('should return package manifest object', () => {
-    expect(testSubject(cwd())).to.eql(pkg)
+  it('should return package manifest object', async () => {
+    expect(await testSubject(cwd())).to.eql(pkg)
   })
 
   it.each<Parameters<typeof testSubject>>([
     [invalidJsonUrl, String(new URL('package.json', invalidJsonUrl))],
     [invalidJsonUrl, 'invalid-json', import.meta.url]
-  ])('should throw if package manifest does not parse as valid JSON (%#)', (
+  ])('should throw if package manifest is not valid JSON (%#)', async (
     id,
     specifier,
     parent
@@ -35,7 +35,7 @@ describe('unit:lib/readPackageJson', () => {
 
     // Act
     try {
-      testSubject(id, specifier, parent)
+      await testSubject(id, specifier, parent)
     } catch (e: unknown) {
       error = e as typeof error
     }

src/lib/__tests__/resolve-module.spec.mts

@@ -28,9 +28,9 @@ describe('unit:lib/resolveModule', () => {
     [legacyMain1.name, parent],
     [legacyMain2.name, parent],
     [pkg.name + '/package.json', import.meta.url]
-  ])('should return resolved URL (%j)', (specifier, parent, options) => {
+  ])('should return resolved URL (%j)', async (specifier, parent, options) => {
     // Act
-    const result = testSubject(specifier, parent, options)
+    const result = await testSubject(specifier, parent, options)
 
     // Expect
     expect(result).to.be.instanceof(URL)
@@ -40,7 +40,7 @@ describe('unit:lib/resolveModule', () => {
   it.each<Parameters<typeof testSubject>>([
     ['#app', import.meta.url],
     ['../../src', import.meta.url]
-  ])('should throw if `specifier` cannot be resolved (%#)', (
+  ])('should throw if `specifier` cannot be resolved (%#)', async (
     specifier,
     parent,
     options
@@ -50,7 +50,7 @@ describe('unit:lib/resolveModule', () => {
 
     // Act
     try {
-      testSubject(specifier, parent, options)
+      await testSubject(specifier, parent, options)
     } catch (e: unknown) {
       error = e as typeof error
     }