feat(hooks): GetFormatHook

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

src/hooks/__tests__/get-format.spec-d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file Type Tests - GetFormatHook
+ * @module esm-types/hooks/tests/unit-d/GetFormatHook
+ */
+
+import type { ResolvedModuleUrl } from '#src/types'
+import type TestSubject from '../get-format'
+import type GetFormatHookContext from '../get-format-context'
+import type GetFormatHookResult from '../get-format-result'
+
+describe('unit-d:hooks/GetFormatHook', () => {
+  it('should be callable with [ResolvedModuleUrl, GetFormatHookContext, GetFormatHook]', () => {
+    // Arrange
+    type Expected = [
+      url: ResolvedModuleUrl,
+      context: GetFormatHookContext,
+      defaultGetFormat: TestSubject
+    ]
+
+    // Expect
+    expectTypeOf<TestSubject>().parameters.toEqualTypeOf<Expected>()
+  })
+
+  it('should return Promise<GetFormatHookResult>', () => {
+    // Arrange
+    type Expected = Promise<GetFormatHookResult>
+
+    // Expect
+    expectTypeOf<TestSubject>().returns.toEqualTypeOf<Expected>()
+  })
+})

src/hooks/get-format.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Hooks - GetFormatHook
+ * @module esm-types/hooks/GetFormatHook
+ */
+
+import type { ResolvedModuleUrl } from '#src/types'
+import type GetFormatHookContext from './get-format-context'
+import type GetFormatHookResult from './get-format-result'
+
+/**
+ * Determines how the given module `url` should be interpreted.
+ *
+ * The `format` returned also affects what the acceptable forms of source values
+ * are for a module when parsing.
+ *
+ * @see {@linkcode GetFormatHookContext}
+ * @see {@linkcode GetFormatHookResult}
+ * @see {@linkcode ResolvedModuleUrl}
+ * @see https://nodejs.org/docs/latest-v14.x/api/esm.html#esm_getformat_url_context_defaultgetformat
+ *
+ * @async
+ *
+ * @param {ResolvedModuleUrl} url - Resolved module URL
+ * @param {GetFormatHookContext} context - Hook context
+ * @param {GetFormatHook} defaultGetFormat - Default Node.js hook
+ * @return {Promise<GetFormatHookResult>} Hook result
+ */
+type GetFormatHook = (
+  url: ResolvedModuleUrl,
+  context: GetFormatHookContext,
+  defaultGetFormat: GetFormatHook
+) => Promise<GetFormatHookResult>
+
+export type { GetFormatHook as default }

src/hooks/index.ts

@@ -3,5 +3,6 @@
  * @module esm-types/hooks
  */
 
+export type { default as GetFormatHook } from './get-format'
 export type { default as GetFormatHookContext } from './get-format-context'
 export type { default as GetFormatHookResult } from './get-format-result'