chore(compartment-mapper): Document introducing require.resolve support

endojs · Jun 28, 2022 · 50abfba · 50abfba
1 parent 39f867d
commit 50abfba
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 3 deletions.
diff --git a/packages/compartment-mapper/NEWS.md b/packages/compartment-mapper/NEWS.md
@@ -1,5 +1,9 @@
 User-visible changes to the compartment mapper:
+# Next release
 
+- Adds `require.resolve` support and provides its implementation from 
+  `readPowers.requireResolve` if available.
+
 # 0.7.6 (2022-06-10)
 
 - Adds support by default for "text" and "bytes" as file types with eponymous

diff --git a/packages/compartment-mapper/README.md b/packages/compartment-mapper/README.md
@@ -47,7 +47,22 @@ necessary).
 The compartment mapper is also not coupled specifically to Node.js IO and does
 not import any powerful modules like `fs`.
 The user must provide `read` and `write` functions from whatever IO powers they
-have.
+have. These powers can be provided as individual functions or as objects
+carrying functions. `ReadPowers` has optional functions which can be used to
+unlock compatibility features. When `fileURLToPath` is available, `__dirname`
+and `__filename` will be provided to CJS modules. If `requireResolve` is
+available, it will be called whenever a CJS module calls `require.resolve()`.
+
+```js
+type ReadPowers = {
+  read: (location: string) => Promise<Uint8Array>,
+  canonical: (location: string) => Promise<string>,
+  computeSha512: { (bytes: Uint8Array) => string }?,
+  fileURLToPath: { (url: string | URL) => string }?,
+  pathToFileURL: { (path: string) => URL }?,
+  requireResolve: { (from: string, request: string, options?: {}) => string }?
+}
+```
 
 > TODO
 >

diff --git a/packages/compartment-mapper/src/parse-cjs-shared-export-wrapper.js b/packages/compartment-mapper/src/parse-cjs-shared-export-wrapper.js
@@ -149,7 +149,7 @@ export const wrap = ({
   } else {
     require.resolve = freeze(specifier => {
       const error = Error(
-        `Cannot find module '${specifier}'\nPass ReadPowers with a requireResolve function to provide require.resolve`,
+        `Cannot find module '${specifier}'\nAdd requireResolve to Endo Compartment Mapper readPowers.`,
       );
       defineProperty(error, 'code', { value: 'MODULE_NOT_FOUND' });
       throw error;

diff --git a/packages/compartment-mapper/test/test-cjs-compat.js b/packages/compartment-mapper/test/test-cjs-compat.js
@@ -50,7 +50,7 @@ const assertFixture = (t, { namespace, testCategoryHint }) => {
       "Cannot find module 'app'",
       "Cannot find module 'fs'",
       "Cannot find module 'nested-export/callBound'",
-      'Pass ReadPowers with a requireResolve function to provide require.resolve',
+      'Add requireResolve to Endo Compartment Mapper readPowers.',
     ]);
   }
   t.pass();