@endo/compartment-mapper 1.3.1 → 1.5.0

package/src/map-parser.js

@@ -1,15 +1,8 @@
 /**
- * Exports {@link makeMapParsers}, which creates a function which matches a
+ * @module Exports {@link makeMapParsers}, which creates a function which matches a
  * module to a parser based on reasons.
- *
- * @module
  */
 
-// @ts-check
-
-import { syncTrampoline, asyncTrampoline } from '@endo/trampoline';
-import { parseExtension } from './extension.js';
-
 /**
  * @import {
  *   LanguageForExtension,
@@ -19,14 +12,20 @@ import { parseExtension } from './extension.js';
  *   ModuleTransform,
  *   ModuleTransforms,
  *   ParseFn,
- *   ParseFnAsync,
+ *   AsyncParseFn,
  *   ParseResult,
  *   ParserForLanguage,
  *   SyncModuleTransform,
  *   SyncModuleTransforms
  * } from './types.js';
+ * @import {
+ *   EReturn
+ * } from '@endo/eventual-send';
  */
 
+import { syncTrampoline, asyncTrampoline } from '@endo/trampoline';
+import { parseExtension } from './extension.js';
+
 const { entries, fromEntries, keys, hasOwnProperty, values } = Object;
 const { apply } = Reflect;
 // q, as in quote, for strings in error messages.
@@ -64,7 +63,7 @@ const extensionImpliesLanguage = extension => extension !== 'js';
  * @param {ParserForLanguage} parserForLanguage
  * @param {ModuleTransforms} moduleTransforms
  * @param {SyncModuleTransforms} syncModuleTransforms
- * @returns {ParseFnAsync|ParseFn}
+ * @returns {AsyncParseFn|ParseFn}
  */
 const makeExtensionParser = (
   preferSynchronous,
@@ -78,14 +77,15 @@ const makeExtensionParser = (
   let transforms;
 
   /**
-   * Function returning a generator which executes a parser for a module in either sync or async context.
+   * Function returning a generator which executes a parser for a module in
+   * either sync or async context.
    *
    * @param {Uint8Array} bytes
    * @param {string} specifier
    * @param {string} location
    * @param {string} packageLocation
    * @param {*} options
-   * @returns {Generator<ReturnType<ModuleTransform>|ReturnType<SyncModuleTransform>, ParseResult, Awaited<ReturnType<ModuleTransform>|ReturnType<SyncModuleTransform>>>}
+   * @returns {Generator<ReturnType<ModuleTransform>|ReturnType<SyncModuleTransform>, ParseResult, EReturn<ModuleTransform|SyncModuleTransform>>}
    */
   function* getParserGenerator(
     bytes,
@@ -104,6 +104,14 @@ const makeExtensionParser = (
     ) {
       language = languageForModuleSpecifier[specifier];
     } else {
+      // We should revisit this design decision:
+      // Defaulting the language to the extension conflates those namespaces.
+      // So, a transform keyed by extension can be used to coerce a language
+      // (e.g., .mts to mjs) as a shorthand for configuring a parser for that
+      // extension that pre-processes the file before handing off to the
+      // parser.
+      // But, this forces us to support the case of using weird language
+      // names like pre-mjs-json as valid, unconfigured extensions.
       language = languageForExtension[extension] || extension;
     }
 
@@ -169,7 +177,7 @@ const makeExtensionParser = (
   syncParser.isSyncParser = true;
 
   /**
-   * @type {ParseFnAsync}
+   * @type {AsyncParseFn}
    */
   const asyncParser = async (
     bytes,
@@ -190,7 +198,7 @@ const makeExtensionParser = (
 
   // Unfortunately, typescript was not smart enough to figure out the return
   // type depending on a boolean in arguments, so it has to be
-  // ParseFnAsync|ParseFn
+  // AsyncParseFn|ParseFn
   if (preferSynchronous) {
     transforms = syncModuleTransforms;
     return syncParser;
@@ -233,7 +241,7 @@ const makeExtensionParser = (
  * @param {ModuleTransforms} [moduleTransforms]
  * @param {SyncModuleTransforms} [syncModuleTransforms]
  * @param {false} [preferSynchronous]
- * @returns {ParseFnAsync}
+ * @returns {AsyncParseFn}
  */
 
 /**
@@ -245,7 +253,7 @@ const makeExtensionParser = (
  * @param {ModuleTransforms} [moduleTransforms]
  * @param {SyncModuleTransforms} [syncModuleTransforms]
  * @param {boolean} [preferSynchronous] If `true`, will create a `ParseFn`
- * @returns {ParseFnAsync|ParseFn}
+ * @returns {AsyncParseFn|ParseFn}
  */
 function mapParsers(
   languageForExtension,
@@ -300,7 +308,7 @@ export const makeMapParsers = ({
    * Async `mapParsers()` function; returned when a non-synchronous parser is
    * present _or_ when `moduleTransforms` is non-empty.
    *
-   * @type {MapParsersFn<ParseFnAsync>}
+   * @type {MapParsersFn<AsyncParseFn>}
    */
   const asyncParseFn = (languageForExtension, languageForModuleSpecifier) =>
     mapParsers(

package/src/node-module-specifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-module-specifier.d.ts","sourceRoot":"","sources":["node-module-specifier.js"],"names":[],"mappings":"AAyDO,8BAJI,MAAM,YACN,MAAM,GACJ,MAAM,CAiClB;AAeM,2BAJI,MAAM,QACN,MAAM,GACJ,MAAM,CA6BlB;AAaM,iCALI,MAAM,GAEJ,MAAM,CAclB"}
+{"version":3,"file":"node-module-specifier.d.ts","sourceRoot":"","sources":["node-module-specifier.js"],"names":[],"mappings":"AAwDO,8BAJI,MAAM,YACN,MAAM,GACJ,MAAM,CAiClB;AAeM,2BAJI,MAAM,QACN,MAAM,GACJ,MAAM,CA6BlB;AAaM,iCALI,MAAM,GAEJ,MAAM,CAclB"}

package/src/node-module-specifier.js

@@ -1,10 +1,9 @@
-/* Provides functions for interacting with Node.js module specifiers in
+/**
+ * @module Provides functions for interacting with Node.js module specifiers in
  * their canonical form.
  * This is a kind of path math that is platform-agnostic.
  */
 
-// @ts-check
-
 // q, as in quote, for error messages.
 const q = JSON.stringify;
 

package/src/node-modules.d.ts

@@ -1,11 +1,5 @@
-export function compartmentMapForNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, packageLocation: string, conditions: Set<string>, packageDescriptor: object, moduleSpecifier: string, options?: CompartmentMapForNodeModulesOptions | undefined): Promise<CompartmentMapDescriptor>;
-export function mapNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, moduleLocation: string, options?: {
-    tags?: Set<string> | undefined;
-    conditions?: Set<string> | undefined;
-    dev?: boolean | undefined;
-    commonDependencies?: object;
-    policy?: object;
-} | undefined): Promise<CompartmentMapDescriptor>;
+export function compartmentMapForNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, packageLocation: string, conditionsOption: Set<string>, packageDescriptor: object, moduleSpecifier: string, options?: CompartmentMapForNodeModulesOptions | undefined): Promise<CompartmentMapDescriptor>;
+export function mapNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, moduleLocation: string, options?: MapNodeModulesOptions | undefined): Promise<CompartmentMapDescriptor>;
 /**
  * The graph is an intermediate object model that the functions of this module
  * build by exploring the `node_modules` tree dropped by tools like npm and
@@ -37,6 +31,13 @@ export type Node = {
      */
     types: Record<string, Language>;
 };
+export type LanguageOptions = {
+    commonjsLanguageForExtension: LanguageForExtension;
+    moduleLanguageForExtension: LanguageForExtension;
+    workspaceCommonjsLanguageForExtension: LanguageForExtension;
+    workspaceModuleLanguageForExtension: LanguageForExtension;
+    languages: Set<string>;
+};
 export type CommonDependencyDescriptors = Record<string, {
     spec: string;
     alias: string;
@@ -47,6 +48,7 @@ import type { ReadPowers } from './types.js';
 import type { MaybeReadPowers } from './types.js';
 import type { CompartmentMapForNodeModulesOptions } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';
+import type { MapNodeModulesOptions } from './types.js';
 import type { LanguageForExtension } from './types.js';
 import type { Language } from './types.js';
 //# sourceMappingURL=node-modules.d.ts.map

package/src/node-modules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AAwvBO,yDARI,MAAM,GAAG,UAAU,GAAG,eAAe,mBACrC,MAAM,cACN,GAAG,CAAC,MAAM,CAAC,qBACX,MAAM,mBACN,MAAM,8DAEJ,OAAO,CAAC,wBAAwB,CAAC,CA+C7C;AAaM,2CAVI,MAAM,GAAG,UAAU,GAAG,eAAe,kBACrC,MAAM;;;;yBAKN,MAAM;aACN,MAAM;gBACJ,OAAO,CAAC,wBAAwB,CAAC,CAmC7C;;;;;;;oBAjzBY,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;;WAKnB,MAAM;UACN,MAAM;UACN,KAAK,CAAC,MAAM,CAAC;iBACb,KAAK,CAAC,MAAM,CAAC;qBACb,OAAO;qBACP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;qBACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;yBACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;aAEtB,oBAAoB;;;;;WAEpB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;;0CAKzB,MAAM,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;iDA+E/C,MAAM,KACJ,OAAO,CAAC,MAAM,CAAC;4BAhHF,YAAY;gCACR,YAAY;qCAHP,YAAY;yDAPQ,YAAY;8CAGvB,YAAY;0CAEhB,YAAY;8BADxB,YAAY"}
+{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AAs2BO,yDARI,MAAM,GAAG,UAAU,GAAG,eAAe,mBACrC,MAAM,oBACN,GAAG,CAAC,MAAM,CAAC,qBACX,MAAM,mBACN,MAAM,8DAEJ,OAAO,CAAC,wBAAwB,CAAC,CA+D7C;AAQM,2CALI,MAAM,GAAG,UAAU,GAAG,eAAe,kBACrC,MAAM,gDAEJ,OAAO,CAAC,wBAAwB,CAAC,CA6B7C;;;;;;;oBA/5BY,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;;WAKnB,MAAM;UACN,MAAM;UACN,KAAK,CAAC,MAAM,CAAC;iBACb,KAAK,CAAC,MAAM,CAAC;qBACb,OAAO;qBACP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;qBACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;yBACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;aAEtB,oBAAoB;;;;;WAEpB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;;;kCAMxB,oBAAoB;gCACpB,oBAAoB;2CACpB,oBAAoB;yCACpB,oBAAoB;eACpB,GAAG,CAAC,MAAM,CAAC;;0CAIZ,MAAM,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;iDA+E/C,MAAM,KACJ,OAAO,CAAC,MAAM,CAAC;4BAvHlB,YAAY;gCAAZ,YAAY;qCAAZ,YAAY;yDAAZ,YAAY;8CAAZ,YAAY;2CAAZ,YAAY;0CAAZ,YAAY;8BAAZ,YAAY"}