feat(utils): getSource

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

.cspell.json

@@ -30,7 +30,7 @@
     "patches/",
     "yarn.lock"
   ],
-  "ignoreRegExpList": [],
+  "ignoreRegExpList": ["/data:.+;base64,.+/"],
   "ignoreWords": [],
   "language": "en-US",
   "patterns": [],

README.md

@@ -68,6 +68,7 @@ import {
   defaultMainFields,
   extensionFormatMap,
   formats,
+  getSource,
   isAbsoluteSpecifier,
   isArrayIndex,
   isBareSpecifier,
@@ -106,6 +107,7 @@ This package exports the following identifiers:
 - [`defaultMainFields`](./src/lib/default-main-fields.mts)
 - [`extensionFormatMap`](./src/lib/extension-format-map.mts)
 - [`formats`](./src/lib/formats.mts)
+- [`getSource`](./src/lib/get-source.mts)
 - [`isAbsoluteSpecifier`](./src/lib/is-absolute-specifier.mts)
 - [`isArrayIndex`](./src/lib/is-array-index.mts)
 - [`isBareSpecifier`](./src/lib/is-bare-specifier.mts)

eslint.base.config.mjs

@@ -171,10 +171,12 @@ export default [
       globals: {
         ...globals.es2024,
         ...globals.node,
+        BufferEncoding: 'readonly',
         Chai: 'readonly',
         Console: 'readonly',
         NodeJS: 'readonly',
-        React: fs.existsSync('node_modules/react') ? 'readonly' : false
+        React: fs.existsSync('node_modules/react') ? 'readonly' : false,
+        RequestInit: 'readonly'
       },
       parser: /** @type {Parser} */ (ts.parser),
       parserOptions: {

package.json

@@ -63,6 +63,18 @@
       "node": "fs",
       "default": "fs"
     },
+    "#internal/process": {
+      "types": {
+        "mlly": "./src/internal/process.d.mts",
+        "default": "./dist/internal/process.d.mts"
+      },
+      "browser": {
+        "mlly": "./src/internal/process.browser.mts",
+        "default": "./dist/internal/process.browser.mjs"
+      },
+      "node": "process",
+      "default": "process"
+    },
     "#internal/*": {
       "mlly": "./src/internal/*.mts",
       "default": "./dist/internal/*.mjs"

src/__snapshots__/index.e2e.snap

@@ -9,6 +9,7 @@ exports[`e2e:mlly > should expose public api 1`] = `
   "defaultMainFields",
   "extensionFormatMap",
   "formats",
+  "getSource",
   "isAbsoluteSpecifier",
   "isArrayIndex",
   "isBareSpecifier",

src/interfaces/__tests__/context-get-source.spec-d.mts

@@ -0,0 +1,43 @@
+/**
+ * @file Type Tests - GetSourceContext
+ * @module mlly/interfaces/tests/unit-d/GetSourceContext
+ */
+
+import type TestSubject from '#interfaces/context-get-source'
+import type {
+  FileSystem,
+  GetSourceHandlers,
+  GetSourceOptions
+} from '@flex-development/mlly'
+
+describe('unit-d:interfaces/GetSourceContext', () => {
+  it('should extend GetSourceOptions', () => {
+    expectTypeOf<TestSubject>().toMatchTypeOf<GetSourceOptions>()
+  })
+
+  it('should match [error: boolean]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('error').toEqualTypeOf<boolean>()
+  })
+
+  it('should match [fs: FileSystem]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('fs').toEqualTypeOf<FileSystem>()
+  })
+
+  it('should match [handlers: GetSourceHandlers]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('handlers')
+      .toEqualTypeOf<GetSourceHandlers>()
+  })
+
+  it('should match [req: RequestInit]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('req')
+      .toEqualTypeOf<RequestInit>()
+  })
+
+  it('should match [schemes: Set<string>', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('schemes')
+      .toEqualTypeOf<Set<string>>()
+  })
+})

src/interfaces/__tests__/options-get-source.spec-d.mts

@@ -0,0 +1,54 @@
+/**
+ * @file Type Tests - GetSourceOptions
+ * @module mlly/interfaces/tests/unit-d/GetSourceOptions
+ */
+
+import type TestSubject from '#interfaces/options-get-source'
+import type {
+  FileSystem,
+  GetSourceHandlers,
+  ModuleFormat
+} from '@flex-development/mlly'
+import type { Nilable } from '@flex-development/tutils'
+
+describe('unit-d:interfaces/GetSourceOptions', () => {
+  it('should allow empty object', () => {
+    assertType<TestSubject>({})
+  })
+
+  it('should match [format?: ModuleFormat | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('format')
+      .toEqualTypeOf<Nilable<ModuleFormat>>()
+  })
+
+  it('should match [fs?: FileSystem | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('fs')
+      .toEqualTypeOf<Nilable<FileSystem>>()
+  })
+
+  it('should match [handlers?: GetSourceHandlers | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('handlers')
+      .toEqualTypeOf<Nilable<GetSourceHandlers>>()
+  })
+
+  it('should match [ignoreErrors?: boolean | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('ignoreErrors')
+      .toEqualTypeOf<Nilable<boolean>>()
+  })
+
+  it('should match [req?: RequestInit | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('req')
+      .toEqualTypeOf<Nilable<RequestInit>>()
+  })
+
+  it('should match [schemes?: Set<string> | readonly string[] | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('schemes')
+      .toEqualTypeOf<Nilable<Set<string> | readonly string[]>>()
+  })
+})

src/interfaces/__tests__/protocol-map.spec-d.mts

@@ -6,79 +6,91 @@
 import type TestSubject from '#interfaces/protocol-map'
 
 describe('unit-d:interfaces/ProtocolMap', () => {
-  it('should have property "blob:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('blob:')
+  it('should match [blob: "blob:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('blob').toEqualTypeOf<'blob:'>()
   })
 
-  it('should have property "content:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('content:')
+  it('should match [content: "content:"]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('content')
+      .toEqualTypeOf<'content:'>()
   })
 
-  it('should have property "cvs:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('cvs:')
+  it('should match [cvs: "cvs:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('cvs').toEqualTypeOf<'cvs:'>()
   })
 
-  it('should have property "data:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('data:')
+  it('should match [data: "data:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('data').toEqualTypeOf<'data:'>()
   })
 
-  it('should have property "dns:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('dns:')
+  it('should match [dns: "dns:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('dns').toEqualTypeOf<'dns:'>()
   })
 
-  it('should have property "file:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('file:')
+  it('should match [file: "file:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('file').toEqualTypeOf<'file:'>()
   })
 
-  it('should have property "fish:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('fish:')
+  it('should match [fish: "fish:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('fish').toEqualTypeOf<'fish:'>()
   })
 
-  it('should have property "ftp:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('ftp:')
+  it('should match [ftp: "ftp:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('ftp').toEqualTypeOf<'ftp:'>()
   })
 
-  it('should have property "git:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('git:')
+  it('should match [git: "git:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('git').toEqualTypeOf<'git:'>()
   })
 
-  it('should have property "http:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('http:')
+  it('should match [http: "http:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('http').toEqualTypeOf<'http:'>()
   })
 
-  it('should have property "https:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('https:')
+  it('should match [https: "https:"]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('https')
+      .toEqualTypeOf<'https:'>()
   })
 
-  it('should have property "mvn:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('mvn:')
+  it('should match [mvn: "mvn:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('mvn').toEqualTypeOf<'mvn:'>()
   })
 
-  it('should have property "redis:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('redis:')
+  it('should match [node: "node:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('node').toEqualTypeOf<'node:'>()
   })
 
-  it('should have property "sftp:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('sftp:')
+  it('should match [redis: "redis:"]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('redis')
+      .toEqualTypeOf<'redis:'>()
   })
 
-  it('should have property "ssh:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('ssh:')
+  it('should match [sftp: "sftp:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('sftp').toEqualTypeOf<'sftp:'>()
   })
 
-  it('should have property "svn:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('svn:')
+  it('should match [ssh: "ssh:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('ssh').toEqualTypeOf<'ssh:'>()
   })
 
-  it('should have property "view-source:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('view-source:')
+  it('should match [svn: "svn:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('svn').toEqualTypeOf<'svn:'>()
   })
 
-  it('should have property "ws:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('ws:')
+  it('should match [viewSource: "view-source:"]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('viewSource')
+      .toEqualTypeOf<'view-source:'>()
   })
 
-  it('should have property "wss:"', () => {
-    expectTypeOf<TestSubject>().toHaveProperty('wss:')
+  it('should match [ws: "ws:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('ws').toEqualTypeOf<'ws:'>()
+  })
+
+  it('should match [wss: "wss:"]', () => {
+    expectTypeOf<TestSubject>().toHaveProperty('wss').toEqualTypeOf<'wss:'>()
   })
 })

src/interfaces/context-get-source.mts

@@ -0,0 +1,63 @@
+/**
+ * @file Interfaces - GetSourceContext
+ * @module mlly/interfaces/GetSourceContext
+ */
+
+import type {
+  FileSystem,
+  GetSourceHandlers,
+  GetSourceOptions
+} from '@flex-development/mlly'
+
+/**
+ * Source code retrieval context.
+ *
+ * @see {@linkcode GetSourceOptions}
+ *
+ * @extends {GetSourceOptions}
+ */
+interface GetSourceContext extends GetSourceOptions {
+  /**
+   * Throw [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][err]?
+   *
+   * [err]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
+   */
+  error: boolean
+
+  /**
+   * File system API.
+   *
+   * @see {@linkcode FileSystem}
+   *
+   * @override
+   */
+  fs: FileSystem
+
+  /**
+   * URL handler map.
+   *
+   * @see {@linkcode GetSourceHandlers}
+   *
+   * @override
+   */
+  handlers: GetSourceHandlers
+
+  /**
+   * Request options for network based modules.
+   *
+   * > 👉 **Note**: Only applicable if {@linkcode network} is
+   * > enabled.
+   *
+   * @override
+   */
+  req: RequestInit
+
+  /**
+   * List of supported URL schemes.
+   *
+   * @override
+   */
+  schemes: Set<string>
+}
+
+export type { GetSourceContext as default }

src/interfaces/index.mts

@@ -4,9 +4,15 @@
  */
 
 export type { default as Aliases } from '#interfaces/aliases'
+export type {
+  default as GetSourceContext
+} from '#interfaces/context-get-source'
 export type { default as FileSystem } from '#interfaces/file-system'
 export type { default as MainFieldMap } from '#interfaces/main-field-map'
 export type { default as ModuleFormatMap } from '#interfaces/module-format-map'
+export type {
+  default as GetSourceOptions
+} from '#interfaces/options-get-source'
 export type {
   default as ResolveAliasOptions
 } from '#interfaces/options-resolve-alias'