@endo/compartment-mapper 1.2.2 → 1.3.0

package/src/import-lite.d.ts

@@ -1,9 +1,26 @@
-export function loadFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: import("./types.js").ArchiveOptions | undefined): Promise<Application>;
+/**
+ * @overload
+ * @param {ReadNowPowers} readPowers
+ * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {SyncImportLocationOptions} [opts]
+ * @returns {Promise<Application>}
+ */
+export function loadFromMap(readPowers: ReadNowPowers, compartmentMap: CompartmentMapDescriptor, opts?: SyncImportLocationOptions | undefined): Promise<Application>;
+/**
+ * @overload
+ * @param {ReadFn | ReadPowers} readPowers
+ * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {ImportLocationOptions} [opts]
+ * @returns {Promise<Application>}
+ */
+export function loadFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, opts?: ImportLocationOptions | undefined): Promise<Application>;
 export function importFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ImportLocationOptions | undefined): Promise<SomeObject>;
-import type { ReadFn } from './types.js';
-import type { ReadPowers } from './types.js';
+import type { ReadNowPowers } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';
+import type { SyncImportLocationOptions } from './types.js';
 import type { Application } from './types.js';
+import type { ReadFn } from './types.js';
+import type { ReadPowers } from './types.js';
 import type { ImportLocationOptions } from './types.js';
 import type { SomeObject } from './types.js';
 //# sourceMappingURL=import-lite.d.ts.map

package/src/import-lite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-lite.d.ts","sourceRoot":"","sources":["import-lite.js"],"names":[],"mappings":"AA0CO,wCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,8DAEtB,OAAO,CAAC,WAAW,CAAC,CAgEhC;AASM,0CANI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,gDAEtB,OAAO,CAAC,UAAU,CAAC,CAU/B;4BAhGyB,YAAY;gCACR,YAAY;8CANE,YAAY;iCACzB,YAAY;2CACF,YAAY;gCAKvB,YAAY"}
+{"version":3,"file":"import-lite.d.ts","sourceRoot":"","sources":["import-lite.js"],"names":[],"mappings":";;;;;;;AAmEG,wCACQ,aAAa,kBACb,wBAAwB,iDAEtB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,wCACQ,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC,WAAW,CAAC,CAChC;AA2JM,0CANI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,gDAEtB,OAAO,CAAC,UAAU,CAAC,CAU/B;mCA5NgC,YAAY;8CAJD,YAAY;+CACX,YAAY;iCAI1B,YAAY;4BAGjB,YAAY;gCACR,YAAY;2CAHD,YAAY;gCAIvB,YAAY"}

package/src/import-lite.js

@@ -16,11 +16,13 @@
 
 // @ts-check
 /* eslint no-shadow: "off" */
-
 /** @import {CompartmentMapDescriptor} from './types.js' */
+/** @import {SyncImportLocationOptions} from './types.js' */
+/** @import {ImportNowHookMaker} from './types.js' */
+/** @import {ModuleTransforms} from './types.js' */
+/** @import {ReadNowPowers} from './types.js' */
 /** @import {Application} from './types.js' */
 /** @import {ImportLocationOptions} from './types.js' */
-/** @import {LoadLocationOptions} from './types.js' */
 /** @import {ExecuteFn} from './types.js' */
 /** @import {ReadFn} from './types.js' */
 /** @import {ReadPowers} from './types.js' */
@@ -30,19 +32,63 @@ import { link } from './link.js';
 import {
   exitModuleImportHookMaker,
   makeImportHookMaker,
+  makeImportNowHookMaker,
 } from './import-hook.js';
+import { isReadNowPowers } from './powers.js';
+
+const { assign, create, freeze, entries } = Object;
+
+/**
+ * Returns `true` if `value` is a {@link SyncImportLocationOptions}.
+ *
+ * The requirements here are:
+ * - `moduleTransforms` _is not_ present in `value`
+ * - `parserForLanguage` - if set, contains synchronous parsers only
+ *
+ * @param {ImportLocationOptions|SyncImportLocationOptions} value
+ * @returns {value is SyncImportLocationOptions}
+ */
+const isSyncOptions = value => {
+  if (!value || (typeof value === 'object' && !('moduleTransforms' in value))) {
+    if (value.parserForLanguage) {
+      for (const [_language, { synchronous }] of entries(
+        value.parserForLanguage,
+      )) {
+        if (!synchronous) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  return false;
+};
 
-const { assign, create, freeze } = Object;
+/**
+ * @overload
+ * @param {ReadNowPowers} readPowers
+ * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {SyncImportLocationOptions} [opts]
+ * @returns {Promise<Application>}
+ */
 
 /**
+ * @overload
  * @param {ReadFn | ReadPowers} readPowers
  * @param {CompartmentMapDescriptor} compartmentMap
- * @param {LoadLocationOptions} [options]
+ * @param {ImportLocationOptions} [opts]
  * @returns {Promise<Application>}
  */
+
+/**
+ * @param {ReadFn|ReadPowers|ReadNowPowers} readPowers
+ * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {ImportLocationOptions} [options]
+ * @returns {Promise<Application>}
+ */
+
 export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
   const {
-    moduleTransforms = {},
     searchSuffixes = undefined,
     parserForLanguage: parserForLanguageOption = {},
     languageForExtension: languageForExtensionOption = {},
@@ -55,6 +101,44 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
     assign(create(null), languageForExtensionOption),
   );
 
+  /**
+   * Object containing options and read powers that fulfills all requirements
+   * for creation of a {@link ImportNowHookMaker}, thus enabling dynamic import.
+   *
+   * @typedef SyncBehavior
+   * @property {ReadNowPowers} readPowers
+   * @property {SyncImportLocationOptions} options
+   * @property {'SYNC'} type
+   */
+
+  /**
+   * Object containing options and read powers which is incompatible with
+   * creation of an {@link ImportNowHookMaker}, thus disabling dynamic import.
+   *
+   * @typedef AsyncBehavior
+   * @property {ReadFn|ReadPowers} readPowers
+   * @property {ImportLocationOptions} options
+   * @property {'ASYNC'} type
+   */
+
+  /**
+   * When we must control flow based on _n_ type guards consdering _n_ discrete
+   * values, grouping the values into an object, then leveraging a discriminated
+   * union (the `type` property) is one way to approach the problem.
+   */
+  const behavior =
+    isReadNowPowers(readPowers) && isSyncOptions(options)
+      ? /** @type {SyncBehavior} */ ({
+          readPowers,
+          options: options || {},
+          type: 'SYNC',
+        })
+      : /** @type {AsyncBehavior} */ ({
+          readPowers,
+          options: options || {},
+          type: 'ASYNC',
+        });
+
   const {
     entry: { compartment: entryCompartmentName, module: entryModuleSpecifier },
   } = compartmentMap;
@@ -85,16 +169,54 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
         exitModuleImportHook: compartmentExitModuleImportHook,
       },
     );
-    const { compartment, pendingJobsPromise } = link(compartmentMap, {
-      makeImportHook,
-      parserForLanguage,
-      languageForExtension,
-      globals,
-      transforms,
-      moduleTransforms,
-      __shimTransforms__,
-      Compartment,
-    });
+
+    /** @type {ImportNowHookMaker | undefined} */
+    let makeImportNowHook;
+
+    /** @type {Compartment} */
+    let compartment;
+    /** @type {Promise<void>} */
+    let pendingJobsPromise;
+
+    if (behavior.type === 'SYNC') {
+      const { importNowHook: exitModuleImportNowHook, syncModuleTransforms } =
+        behavior.options;
+      makeImportNowHook = makeImportNowHookMaker(
+        /** @type {ReadNowPowers} */ (readPowers),
+        entryCompartmentName,
+        {
+          compartmentDescriptors: compartmentMap.compartments,
+          searchSuffixes,
+          exitModuleImportNowHook,
+        },
+      );
+      ({ compartment, pendingJobsPromise } = link(compartmentMap, {
+        makeImportHook,
+        makeImportNowHook,
+        parserForLanguage,
+        languageForExtension,
+        globals,
+        transforms,
+        syncModuleTransforms,
+        __shimTransforms__,
+        Compartment,
+      }));
+    } else {
+      // sync module transforms are allowed, because they are "compatible"
+      // with async module transforms (not vice-versa)
+      const { moduleTransforms, syncModuleTransforms } = behavior.options;
+      ({ compartment, pendingJobsPromise } = link(compartmentMap, {
+        makeImportHook,
+        parserForLanguage,
+        languageForExtension,
+        globals,
+        transforms,
+        moduleTransforms,
+        syncModuleTransforms,
+        __shimTransforms__,
+        Compartment,
+      }));
+    }
 
     await pendingJobsPromise;
 

package/src/import.d.ts

@@ -1,8 +1,48 @@
-export function loadLocation(readPowers: ReadFn | ReadPowers, moduleLocation: string, options?: ArchiveOptions | undefined): Promise<Application>;
-export function importLocation(readPowers: ReadFn | ReadPowers, moduleLocation: string, options?: (ExecuteOptions & ArchiveOptions) | undefined): Promise<import("./types.js").SomeObject>;
+/**
+ * @overload
+ * @param {ReadNowPowers} readPowers
+ * @param {string} moduleLocation
+ * @param {SyncArchiveOptions} options
+ * @returns {Promise<Application>}
+ */
+export function loadLocation(readPowers: ReadNowPowers, moduleLocation: string, options: SyncArchiveOptions): Promise<Application>;
+/**
+ * @overload
+ * @param {ReadFn | ReadPowers} readPowers
+ * @param {string} moduleLocation
+ * @param {LoadLocationOptions} [options]
+ * @returns {Promise<Application>}
+ */
+export function loadLocation(readPowers: ReadFn | ReadPowers, moduleLocation: string, options?: LoadLocationOptions | undefined): Promise<Application>;
+/**
+ * Allows dynamic requires
+ *
+ * @overload
+ * @param {ReadNowPowers} readPowers
+ * @param {string} moduleLocation
+ * @param {SyncImportLocationOptions} options
+ * @returns {Promise<SomeObject>} the object of the imported modules exported
+ * names.
+ */
+export function importLocation(readPowers: ReadNowPowers, moduleLocation: string, options: SyncImportLocationOptions): Promise<SomeObject>;
+/**
+ * Disallows dynamic requires
+ *
+ * @overload
+ * @param {ReadPowers|ReadFn} readPowers
+ * @param {string} moduleLocation
+ * @param {ImportLocationOptions} [options]
+ * @returns {Promise<SomeObject>} the object of the imported modules exported
+ * names.
+ */
+export function importLocation(readPowers: ReadPowers | ReadFn, moduleLocation: string, options?: ImportLocationOptions | undefined): Promise<SomeObject>;
+import type { ReadNowPowers } from './types.js';
+import type { SyncArchiveOptions } from './types.js';
+import type { Application } from './types.js';
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';
-import type { ArchiveOptions } from './types.js';
-import type { Application } from './types.js';
-import type { ExecuteOptions } from './types.js';
+import type { LoadLocationOptions } from './types.js';
+import type { SyncImportLocationOptions } from './types.js';
+import type { SomeObject } from './types.js';
+import type { ImportLocationOptions } from './types.js';
 //# sourceMappingURL=import.d.ts.map

package/src/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":"AA6CO,yCALI,MAAM,GAAG,UAAU,kBACnB,MAAM,yCAEJ,OAAO,CAAC,WAAW,CAAC,CAmBhC;AASM,2CANI,MAAM,GAAG,UAAU,kBACnB,MAAM,4DAEJ,OAAO,CAAC,OAAO,YAAY,EAAE,UAAU,CAAC,CAMpD;4BAnDyB,YAAY;gCACR,YAAY;oCAHR,YAAY;iCADf,YAAY;oCAET,YAAY"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":";;;;;;;AA6CG,yCACQ,aAAa,kBACb,MAAM,WACN,kBAAkB,GAChB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,yCACQ,MAAM,GAAG,UAAU,kBACnB,MAAM,8CAEJ,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;;;;AAiCE,2CACQ,aAAa,kBACb,MAAM,WACN,yBAAyB,GACvB,OAAO,CAAC,UAAU,CAAC,CAE/B;;;;;;;;;;;AAKE,2CACQ,UAAU,GAAC,MAAM,kBACjB,MAAM,gDAEJ,OAAO,CAAC,UAAU,CAAC,CAE/B;mCAlFgC,YAAY;wCAJP,YAAY;iCAFnB,YAAY;4BAQjB,YAAY;gCACR,YAAY;yCANH,YAAY;+CACN,YAAY;gCAC3B,YAAY;2CAJD,YAAY"}

package/src/import.js

@@ -19,8 +19,13 @@ import { loadFromMap } from './import-lite.js';
 const { assign, create, freeze } = Object;
 
 /** @import {Application} from './types.js' */
+/** @import {ImportLocationOptions} from './types.js' */
+/** @import {SyncArchiveOptions} from './types.js' */
+/** @import {LoadLocationOptions} from './types.js' */
+/** @import {SyncImportLocationOptions} from './types.js' */
+/** @import {SomeObject} from './types.js' */
+/** @import {ReadNowPowers} from './types.js' */
 /** @import {ArchiveOptions} from './types.js' */
-/** @import {ExecuteOptions} from './types.js' */
 /** @import {ReadFn} from './types.js' */
 /** @import {ReadPowers} from './types.js' */
 
@@ -38,9 +43,25 @@ const assignParserForLanguage = (options = {}) => {
 };
 
 /**
+ * @overload
+ * @param {ReadNowPowers} readPowers
+ * @param {string} moduleLocation
+ * @param {SyncArchiveOptions} options
+ * @returns {Promise<Application>}
+ */
+
+/**
+ * @overload
  * @param {ReadFn | ReadPowers} readPowers
  * @param {string} moduleLocation
- * @param {ArchiveOptions} [options]
+ * @param {LoadLocationOptions} [options]
+ * @returns {Promise<Application>}
+ */
+
+/**
+ * @param {ReadFn|ReadPowers|ReadNowPowers} readPowers
+ * @param {string} moduleLocation
+ * @param {LoadLocationOptions} [options]
  * @returns {Promise<Application>}
  */
 export const loadLocation = async (
@@ -48,7 +69,10 @@ export const loadLocation = async (
   moduleLocation,
   options = {},
 ) => {
-  const { dev, tags, conditions = tags, commonDependencies, policy } = options;
+  const { dev, tags, commonDependencies, policy } = options;
+  // conditions are not present in SyncArchiveOptions
+  const conditions =
+    'conditions' in options ? options.conditions || tags : tags;
   const compartmentMap = await mapNodeModules(readPowers, moduleLocation, {
     dev,
     conditions,
@@ -63,10 +87,32 @@ export const loadLocation = async (
 };
 
 /**
- * @param {ReadFn | ReadPowers} readPowers
+ * Allows dynamic requires
+ *
+ * @overload
+ * @param {ReadNowPowers} readPowers
+ * @param {string} moduleLocation
+ * @param {SyncImportLocationOptions} options
+ * @returns {Promise<SomeObject>} the object of the imported modules exported
+ * names.
+ */
+
+/**
+ * Disallows dynamic requires
+ *
+ * @overload
+ * @param {ReadPowers|ReadFn} readPowers
+ * @param {string} moduleLocation
+ * @param {ImportLocationOptions} [options]
+ * @returns {Promise<SomeObject>} the object of the imported modules exported
+ * names.
+ */
+
+/**
+ * @param {ReadPowers|ReadFn|ReadNowPowers} readPowers
  * @param {string} moduleLocation
- * @param {ExecuteOptions & ArchiveOptions} [options]
- * @returns {Promise<import('./types.js').SomeObject>} the object of the imported modules exported
+ * @param {ImportLocationOptions} [options]
+ * @returns {Promise<SomeObject>} the object of the imported modules exported
  * names.
  */
 export const importLocation = async (readPowers, moduleLocation, options) => {

package/src/link.d.ts

@@ -1,15 +1,6 @@
-export function mapParsers(languageForExtension: LanguageForExtension, languageForModuleSpecifier: Record<string, string>, parserForLanguage: ParserForLanguage, moduleTransforms?: ModuleTransforms): ParseFn;
-export function link({ entry, compartments: compartmentDescriptors }: CompartmentMapDescriptor, { resolve, makeImportHook, parserForLanguage: parserForLanguageOption, languageForExtension: languageForExtensionOption, globals, transforms, moduleTransforms, __shimTransforms__, archiveOnly, Compartment, }: LinkOptions): {
-    compartment: Compartment;
-    compartments: Record<string, Compartment>;
-    attenuatorsCompartment: Compartment;
-    pendingJobsPromise: Promise<void>;
-};
+export function link({ entry, compartments: compartmentDescriptors }: CompartmentMapDescriptor, options: LinkOptions): LinkResult;
 export function assemble(compartmentMap: CompartmentMapDescriptor, options: LinkOptions): Compartment;
-import type { LanguageForExtension } from './types.js';
-import type { ParserForLanguage } from './types.js';
-import type { ModuleTransforms } from './types.js';
-import type { ParseFn } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';
 import type { LinkOptions } from './types.js';
+import type { LinkResult } from './types.js';
 //# sourceMappingURL=link.d.ts.map

package/src/link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AAwJO,iDAPI,oBAAoB,8BACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,qBAEtB,iBAAiB,qBACjB,gBAAgB,GACd,OAAO,CA0BnB;AAyKM,sEAHI,wBAAwB,mNACxB,WAAW;;;;;EAoKrB;AAOM,yCAJI,wBAAwB,WACxB,WAAW,eAIqB;0CApfH,YAAY;uCAJN,YAAY;sCAGtB,YAAY;6BAHF,YAAY;8CAOd,YAAY;iCACzB,YAAY"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AAqPO,sEAJI,wBAAwB,WACxB,WAAW,GACT,UAAU,CA0LtB;AAOM,yCAJI,wBAAwB,WACxB,WAAW,eAIqB;8CA5ZjC,YAAY;iCAAZ,YAAY;gCAAZ,YAAY"}