@endo/compartment-mapper 1.6.3 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/package.json +24 -14
  2. package/src/archive-lite.d.ts +7 -7
  3. package/src/archive-lite.d.ts.map +1 -1
  4. package/src/archive-lite.js +81 -30
  5. package/src/archive.d.ts.map +1 -1
  6. package/src/archive.js +7 -0
  7. package/src/bundle-lite.d.ts +3 -3
  8. package/src/bundle-lite.d.ts.map +1 -1
  9. package/src/bundle-lite.js +19 -24
  10. package/src/bundle.d.ts +3 -3
  11. package/src/bundle.d.ts.map +1 -1
  12. package/src/bundle.js +19 -24
  13. package/src/capture-lite.d.ts +2 -2
  14. package/src/capture-lite.d.ts.map +1 -1
  15. package/src/capture-lite.js +243 -25
  16. package/src/compartment-map.d.ts +9 -2
  17. package/src/compartment-map.d.ts.map +1 -1
  18. package/src/compartment-map.js +738 -254
  19. package/src/digest.d.ts +22 -2
  20. package/src/digest.d.ts.map +1 -1
  21. package/src/digest.js +180 -57
  22. package/src/generic-graph.d.ts +7 -25
  23. package/src/generic-graph.d.ts.map +1 -1
  24. package/src/generic-graph.js +83 -108
  25. package/src/guards.d.ts +18 -0
  26. package/src/guards.d.ts.map +1 -0
  27. package/src/guards.js +109 -0
  28. package/src/hooks.md +124 -0
  29. package/src/import-archive-lite.d.ts.map +1 -1
  30. package/src/import-archive-lite.js +15 -11
  31. package/src/import-archive.d.ts +5 -19
  32. package/src/import-archive.d.ts.map +1 -1
  33. package/src/import-archive.js +7 -27
  34. package/src/import-hook.d.ts +4 -3
  35. package/src/import-hook.d.ts.map +1 -1
  36. package/src/import-hook.js +140 -70
  37. package/src/import-lite.d.ts +6 -6
  38. package/src/import-lite.d.ts.map +1 -1
  39. package/src/import-lite.js +8 -5
  40. package/src/import.d.ts +3 -3
  41. package/src/import.d.ts.map +1 -1
  42. package/src/import.js +16 -6
  43. package/src/infer-exports.d.ts +4 -2
  44. package/src/infer-exports.d.ts.map +1 -1
  45. package/src/infer-exports.js +172 -23
  46. package/src/link.d.ts +4 -3
  47. package/src/link.d.ts.map +1 -1
  48. package/src/link.js +122 -52
  49. package/src/node-modules.d.ts +4 -3
  50. package/src/node-modules.d.ts.map +1 -1
  51. package/src/node-modules.js +513 -151
  52. package/src/parse-cjs-shared-export-wrapper.d.ts.map +1 -1
  53. package/src/parse-cjs-shared-export-wrapper.js +3 -1
  54. package/src/pattern-replacement.d.ts +6 -0
  55. package/src/pattern-replacement.d.ts.map +1 -0
  56. package/src/pattern-replacement.js +198 -0
  57. package/src/policy-format.d.ts +22 -5
  58. package/src/policy-format.d.ts.map +1 -1
  59. package/src/policy-format.js +342 -108
  60. package/src/policy.d.ts +13 -28
  61. package/src/policy.d.ts.map +1 -1
  62. package/src/policy.js +161 -106
  63. package/src/types/canonical-name.d.ts +97 -0
  64. package/src/types/canonical-name.d.ts.map +1 -0
  65. package/src/types/canonical-name.ts +151 -0
  66. package/src/types/compartment-map-schema.d.ts +121 -35
  67. package/src/types/compartment-map-schema.d.ts.map +1 -1
  68. package/src/types/compartment-map-schema.ts +211 -37
  69. package/src/types/external.d.ts +240 -76
  70. package/src/types/external.d.ts.map +1 -1
  71. package/src/types/external.ts +305 -74
  72. package/src/types/generic-graph.d.ts +8 -2
  73. package/src/types/generic-graph.d.ts.map +1 -1
  74. package/src/types/generic-graph.ts +7 -2
  75. package/src/types/internal.d.ts +31 -50
  76. package/src/types/internal.d.ts.map +1 -1
  77. package/src/types/internal.ts +60 -58
  78. package/src/types/node-modules.d.ts +112 -14
  79. package/src/types/node-modules.d.ts.map +1 -1
  80. package/src/types/node-modules.ts +152 -13
  81. package/src/types/pattern-replacement.d.ts +62 -0
  82. package/src/types/pattern-replacement.d.ts.map +1 -0
  83. package/src/types/pattern-replacement.ts +70 -0
  84. package/src/types/policy-schema.d.ts +26 -11
  85. package/src/types/policy-schema.d.ts.map +1 -1
  86. package/src/types/policy-schema.ts +29 -16
  87. package/src/types/policy.d.ts +6 -2
  88. package/src/types/policy.d.ts.map +1 -1
  89. package/src/types/policy.ts +7 -2
  90. package/src/types/powers.d.ts +11 -9
  91. package/src/types/powers.d.ts.map +1 -1
  92. package/src/types/powers.ts +11 -10
  93. package/src/types/typescript.d.ts +28 -0
  94. package/src/types/typescript.d.ts.map +1 -1
  95. package/src/types/typescript.ts +37 -1
@@ -15,10 +15,141 @@ import type {
15
15
  import type {
16
16
  CompartmentDescriptor,
17
17
  CompartmentMapDescriptor,
18
+ DigestedCompartmentMapDescriptor,
18
19
  Language,
19
20
  LanguageForExtension,
21
+ PackageCompartmentDescriptorName,
22
+ PackageCompartmentDescriptors,
20
23
  } from './compartment-map-schema.js';
24
+ import type { SomePolicy } from './policy-schema.js';
21
25
  import type { HashFn, ReadFn, ReadPowers } from './powers.js';
26
+ import type { CanonicalName } from './canonical-name.js';
27
+ import type { PackageDescriptor } from './node-modules.js';
28
+ import type {
29
+ ATTENUATORS_COMPARTMENT,
30
+ ENTRY_COMPARTMENT,
31
+ } from '../policy-format.js';
32
+ import type { LiteralUnion } from './typescript.js';
33
+
34
+ export type { CanonicalName };
35
+ export type { PackageDescriptor };
36
+
37
+ /**
38
+ * Hook executed for each canonical name mentioned in policy but not found in the
39
+ * compartment map
40
+ */
41
+ export type UnknownCanonicalNameHook = (params: {
42
+ canonicalName: CanonicalName;
43
+ path: string[];
44
+ message: string;
45
+ suggestion?: CanonicalName | undefined;
46
+ log: LogFn;
47
+ }) => void;
48
+
49
+ export type { PackageCompartmentDescriptorName };
50
+
51
+ /**
52
+ * Data about a package provided by a {@link PackageDataHook}
53
+ */
54
+ export type PackageData = {
55
+ name: string;
56
+ packageDescriptor: PackageDescriptor;
57
+ location: FileUrlString;
58
+ canonicalName: PackageCompartmentDescriptorName;
59
+ };
60
+
61
+ /**
62
+ * Hook executed with data about all packages found while crawling `node_modules`.
63
+ *
64
+ * Called once before `translateGraph`.
65
+ */
66
+ export type PackageDataHook = (params: {
67
+ packageData: Readonly<
68
+ Map<
69
+ LiteralUnion<
70
+ typeof ATTENUATORS_COMPARTMENT | typeof ENTRY_COMPARTMENT,
71
+ FileUrlString
72
+ >,
73
+ PackageData
74
+ >
75
+ >;
76
+ log: LogFn;
77
+ }) => void;
78
+
79
+ /**
80
+ * Hook executed for each canonical name (corresponding to a package) in the
81
+ * `CompartmentMapDescriptor` with a list of canonical names of its
82
+ * dependencies.
83
+ *
84
+ * Can return partial updates to modify the dependencies set.
85
+ *
86
+ * Suggested use cases:
87
+ * - Adding dependencies based on policy
88
+ * - Removing dependencies based on policy
89
+ * - Filtering dependencies based on multiple criteria
90
+ */
91
+ export type PackageDependenciesHook = (params: {
92
+ canonicalName: CanonicalName;
93
+ dependencies: Readonly<Set<CanonicalName>>;
94
+ log: LogFn;
95
+ }) => Partial<{ dependencies: Set<CanonicalName> }> | void;
96
+
97
+ /**
98
+ * The `moduleSource` property value for {@link ModuleSourceHook}
99
+ */
100
+ export type ModuleSourceHookModuleSource =
101
+ | ModuleSourceHookFileModuleSource
102
+ | ModuleSourceHookExitModuleSource;
103
+
104
+ /**
105
+ * The `moduleSource` property value for {@link ModuleSourceHook} for a module
106
+ * on disk
107
+ */
108
+ export type ModuleSourceHookFileModuleSource = {
109
+ location: FileUrlString;
110
+ language: Language;
111
+ bytes: Uint8Array;
112
+ imports?: string[] | undefined;
113
+ exports?: string[] | undefined;
114
+ reexports?: string[] | undefined;
115
+ sha512?: string | undefined;
116
+ };
117
+
118
+ /**
119
+ * The `moduleSource` property value for {@link ModuleSourceHook} for an exit
120
+ * module (virtual)
121
+ */
122
+ export type ModuleSourceHookExitModuleSource = {
123
+ exit: string;
124
+ };
125
+
126
+ /**
127
+ * Hook executed when processing a module source.
128
+ */
129
+ export type ModuleSourceHook = (params: {
130
+ moduleSource: ModuleSourceHookModuleSource;
131
+ canonicalName: CanonicalName;
132
+ log: LogFn;
133
+ }) => void;
134
+
135
+ /**
136
+ * Hook executed for each canonical name with its connections (linked compartments).
137
+ */
138
+ export type PackageConnectionsHook = (params: {
139
+ canonicalName: CanonicalName;
140
+ connections: Set<CanonicalName>;
141
+ log: LogFn;
142
+ }) => void;
143
+
144
+ /**
145
+ * Hook executed during preloading when a compartment designated to be preloaded
146
+ * is already loaded.
147
+ */
148
+ export type RedundantPreloadHook = (params: {
149
+ canonicalName: CanonicalName;
150
+ entry: string;
151
+ log: LogFn;
152
+ }) => void;
22
153
 
23
154
  /**
24
155
  * Set of options available in the context of code execution.
@@ -26,22 +157,22 @@ import type { HashFn, ReadFn, ReadPowers } from './powers.js';
26
157
  * May be used only as an intersection with other options types.
27
158
  */
28
159
  export type ExecuteOptions = Partial<{
29
- globals: object;
30
- transforms: Array<Transform>;
31
- __shimTransforms__: Array<Transform>;
32
- attenuations: Record<string, object>;
33
- Compartment: typeof Compartment;
34
- __native__: boolean;
160
+ globals: object | undefined;
161
+ transforms: Array<Transform> | undefined;
162
+ __shimTransforms__: Array<Transform> | undefined;
163
+ attenuations: Record<string, object> | undefined;
164
+ Compartment: typeof Compartment | undefined;
165
+ __native__: boolean | undefined;
35
166
  }> &
36
167
  ModulesOption &
37
168
  ExitModuleImportHookOption;
38
169
 
39
170
  export type ParseArchiveOptions = Partial<{
40
- expectedSha512: string;
41
- computeSha512: HashFn;
42
- computeSourceLocation: ComputeSourceLocationHook;
43
- computeSourceMapLocation: ComputeSourceMapLocationHook;
44
- __native__: boolean;
171
+ expectedSha512: string | undefined;
172
+ computeSha512: HashFn | undefined;
173
+ computeSourceLocation: ComputeSourceLocationHook | undefined;
174
+ computeSourceMapLocation: ComputeSourceMapLocationHook | undefined;
175
+ __native__: boolean | undefined;
45
176
  }> &
46
177
  ModulesOption &
47
178
  CompartmentOption &
@@ -57,7 +188,7 @@ export interface LogOptions {
57
188
  /**
58
189
  * A logger (for logging)
59
190
  */
60
- log?: LogFn;
191
+ log?: LogFn | undefined;
61
192
  }
62
193
 
63
194
  /**
@@ -65,11 +196,12 @@ export interface LogOptions {
65
196
  */
66
197
  export type MapNodeModulesOptions = MapNodeModulesOptionsOmitPolicy &
67
198
  PolicyOption &
199
+ MapNodeModulesHookOptions &
68
200
  LogOptions;
69
201
 
70
202
  type MapNodeModulesOptionsOmitPolicy = Partial<{
71
203
  /** @deprecated renamed `conditions` to be consistent with Node.js */
72
- tags: Set<string>;
204
+ tags: Set<string> | undefined;
73
205
  /**
74
206
  * Conditions for package `"imports"` and `"exports"`.
75
207
  *
@@ -81,7 +213,7 @@ type MapNodeModulesOptionsOmitPolicy = Partial<{
81
213
  * `devDependencies`, use the {@link MapNodeModulesOptions.dev dev} flag
82
214
  * instead.
83
215
  */
84
- conditions: Set<string>;
216
+ conditions: Set<string> | undefined;
85
217
  /**
86
218
  * If `true`, include packages from `devDependencies` in the resulting {@link CompartmentMapDescriptor}.
87
219
  *
@@ -89,61 +221,101 @@ type MapNodeModulesOptionsOmitPolicy = Partial<{
89
221
  * {@link MapNodeModulesOptions.conditions condition}, but this behavior may
90
222
  * be deprecated in a future version.
91
223
  */
92
- dev: boolean;
224
+ dev: boolean | undefined;
93
225
  /**
94
226
  * Indicates that the node_modules tree should fail to map if it does not
95
227
  * strictly reach every expected package.
96
228
  * By default, unreachable packages are simply omitted from the map,
97
229
  * which defers some errors to when modules load.
98
230
  */
99
- strict: boolean;
231
+ strict: boolean | undefined;
100
232
  /** Dependencies to make reachable from any package */
101
- commonDependencies: Record<string, string>;
233
+ commonDependencies: Record<string, string> | undefined;
102
234
  /** Maps extensions to languages for all packages, like `txt` to `text` */
103
- languageForExtension: LanguageForExtension;
235
+ languageForExtension: LanguageForExtension | undefined;
104
236
  /** Maps additional extensions to languages for all type=module packages */
105
- moduleLanguageForExtension: LanguageForExtension;
237
+ moduleLanguageForExtension: LanguageForExtension | undefined;
106
238
  /** Maps additional extensions to languages for all type=commonjs packages (default) */
107
- commonjsLanguageForExtension: LanguageForExtension;
239
+ commonjsLanguageForExtension: LanguageForExtension | undefined;
108
240
  /** Maps extensions to languages for packages not under node_modules */
109
- workspaceLanguageForExtension: LanguageForExtension;
241
+ workspaceLanguageForExtension: LanguageForExtension | undefined;
110
242
  /**
111
243
  * Maps additional extensions to languages for all type=module packages that
112
244
  * are not under node_modules
113
245
  */
114
- workspaceModuleLanguageForExtension: LanguageForExtension;
246
+ workspaceModuleLanguageForExtension: LanguageForExtension | undefined;
115
247
  /**
116
248
  * Maps additional extensions to languages for all type=commonjs packages
117
249
  * (default)
118
250
  */
119
- workspaceCommonjsLanguageForExtension: LanguageForExtension;
251
+ workspaceCommonjsLanguageForExtension: LanguageForExtension | undefined;
120
252
  /**
121
253
  * Accounts for languages not present as values in any of the extension to
122
254
  * language mappings.
123
255
  * For higher level functions like `importLocation`, these are inferred
124
256
  * from the `parserForLanguage` option.
125
257
  */
126
- languages: Array<Language>;
258
+ languages: Array<Language> | undefined;
127
259
  }>;
128
260
 
129
261
  /**
130
- * @deprecated Use `mapNodeModules()`.
262
+ * Hook options for `mapNodeModules()`
131
263
  */
264
+ export type MapNodeModulesHookOptions = {
265
+ unknownCanonicalNameHook?: UnknownCanonicalNameHook | undefined;
266
+ packageDependenciesHook?: PackageDependenciesHook | undefined;
267
+ packageDataHook?: PackageDataHook | undefined;
268
+ };
269
+
132
270
  export type CompartmentMapForNodeModulesOptions = Omit<
133
271
  MapNodeModulesOptions,
134
272
  'conditions' | 'tags'
135
273
  >;
136
274
 
275
+ /**
276
+ * Options for `captureFromMap()`
277
+ */
137
278
  export type CaptureLiteOptions = ImportingOptions &
138
279
  LinkingOptions &
139
280
  PolicyOption &
140
- LogOptions;
281
+ LogOptions &
282
+ PreloadOption &
283
+ CaptureFromMapHookOptions;
284
+
285
+ /**
286
+ * Hook options for `captureFromMap()`
287
+ */
288
+ export type CaptureFromMapHookOptions = {
289
+ packageConnectionsHook?: PackageConnectionsHook | undefined;
290
+ moduleSourceHook?: ModuleSourceHook | undefined;
291
+ };
292
+
293
+ /**
294
+ * Options bag containing a `preload` array.
295
+ */
296
+ export interface PreloadOption {
297
+ /**
298
+ * List of compartment names (the keys of
299
+ * {@link CompartmentMapDescriptor.compartments}) and entries (`ModuleConfiguration` names) to force-load _after_ the
300
+ * entry compartment and any attenuators.
301
+ *
302
+ * If an array of strings is provided, the entry is assumed to be `.`.
303
+ */
304
+ _preload?: Array<string | { compartment: string; entry: string }>;
305
+
306
+ /**
307
+ * Hook executed during preloading when a compartment designated to be preloaded
308
+ * has already been loaded (via entry Compartment).
309
+ */
310
+ _redundantPreloadHook?: RedundantPreloadHook | undefined;
311
+ }
141
312
 
142
313
  export type ArchiveLiteOptions = SyncOrAsyncArchiveOptions &
143
314
  ModuleTransformsOption &
144
315
  ImportingOptions &
145
316
  ExitModuleImportHookOption &
146
- LinkingOptions;
317
+ LinkingOptions &
318
+ LogOptions;
147
319
 
148
320
  export type SyncArchiveLiteOptions = SyncOrAsyncArchiveOptions &
149
321
  SyncModuleTransformsOption &
@@ -163,31 +335,51 @@ export type BundleOptions = ArchiveOptions & {
163
335
  * Specifying `cjs` makes `require` available for modules outside the bundle
164
336
  * (exits to the import graph).
165
337
  */
166
- format?: 'cjs';
338
+ format?: 'cjs' | undefined;
167
339
  /**
168
340
  * Evaluates individual module functors in-place so stack traces represent
169
341
  * original source locations better.
170
342
  * The resulting script cannot be used on a web page with a no-unsafe-eval
171
343
  * Content Security Policy.
172
344
  */
173
- useEvaluate?: boolean;
345
+ useEvaluate?: boolean | undefined;
174
346
  /**
175
347
  * A prefix for the sourceURL comment in each module format that supports
176
348
  * sourceURL comments.
177
349
  * Requires `useEvaluate` for effect.
178
350
  */
179
- sourceUrlPrefix?: string;
351
+ sourceUrlPrefix?: string | undefined;
180
352
  };
181
353
 
182
- export type SyncArchiveOptions = Omit<MapNodeModulesOptions, 'languages'> &
354
+ export type SyncArchiveOptions = Omit<
355
+ MapNodeModulesOptions,
356
+ | 'languages'
357
+ | 'unknownCanonicalNameHook'
358
+ | 'packageDependenciesHook'
359
+ | 'packageDataHook'
360
+ > &
183
361
  SyncArchiveLiteOptions;
184
362
 
363
+ export type SyncLoadLocationOptions = SyncArchiveOptions &
364
+ LogOptions &
365
+ PreloadOption &
366
+ LoadLocationHookOptions;
367
+
185
368
  /**
186
369
  * Options for `loadLocation()`
187
370
  */
188
371
  export type LoadLocationOptions = ArchiveOptions &
189
372
  SyncArchiveOptions &
190
- LogOptions;
373
+ LogOptions &
374
+ PreloadOption &
375
+ LoadLocationHookOptions;
376
+
377
+ /**
378
+ * Hook options for `loadLocation()`
379
+ */
380
+ export type LoadLocationHookOptions = MapNodeModulesHookOptions & {
381
+ moduleSourceHook?: ModuleSourceHook | undefined;
382
+ };
191
383
 
192
384
  /**
193
385
  * Options for `importLocation()` necessary (but not sufficient--see
@@ -195,14 +387,17 @@ export type LoadLocationOptions = ArchiveOptions &
195
387
  */
196
388
  export type SyncImportLocationOptions = SyncArchiveOptions &
197
389
  ExecuteOptions &
198
- LogOptions;
390
+ LogOptions &
391
+ PreloadOption;
199
392
 
200
393
  /**
201
394
  * Options for `importLocation()` without dynamic require support
202
395
  */
203
396
  export type ImportLocationOptions = ArchiveOptions &
204
397
  ExecuteOptions &
205
- LogOptions;
398
+ LoadLocationHookOptions &
399
+ LogOptions &
400
+ PreloadOption;
206
401
 
207
402
  // ////////////////////////////////////////////////////////////////////////////////
208
403
  // Single Options
@@ -211,7 +406,7 @@ export type ComputeSha512Option = {
211
406
  /**
212
407
  * For computing integrity hashes for module descriptors based on captured sources.
213
408
  */
214
- computeSha512?: HashFn;
409
+ computeSha512?: HashFn | undefined;
215
410
  };
216
411
 
217
412
  export type SearchSuffixesOption = {
@@ -223,15 +418,15 @@ export type SearchSuffixesOption = {
223
418
  * bundler, and does not attempt to vary the behavior of resolution depending
224
419
  * on the language of the importing module.
225
420
  */
226
- searchSuffixes?: string[];
421
+ searchSuffixes?: string[] | undefined;
227
422
  };
228
423
 
229
424
  export type SourceMapHookOption = {
230
- sourceMapHook?: SourceMapHook;
425
+ sourceMapHook?: SourceMapHook | undefined;
231
426
  };
232
427
 
233
428
  export type ModulesOption = {
234
- modules?: Record<string, any>;
429
+ modules?: Record<string, any> | undefined;
235
430
  };
236
431
 
237
432
  export type ExitModuleImportHookOption = {
@@ -239,7 +434,7 @@ export type ExitModuleImportHookOption = {
239
434
  * For obtaining module descriptors for modules that must be provided
240
435
  * by the eventual runtime execution environment, asynchronously.
241
436
  */
242
- importHook?: ExitModuleImportHook;
437
+ importHook?: ExitModuleImportHook | undefined;
243
438
  };
244
439
 
245
440
  export type ExitModuleImportNowHookOption = {
@@ -247,23 +442,23 @@ export type ExitModuleImportNowHookOption = {
247
442
  * For obtaining module descriptors for modules that must be provided
248
443
  * by the eventual runtime execution environment, synchronusly.
249
444
  */
250
- importNowHook?: ExitModuleImportNowHook;
445
+ importNowHook?: ExitModuleImportNowHook | undefined;
251
446
  };
252
447
 
253
448
  export type ParserForLanguageOption = {
254
- parserForLanguage?: ParserForLanguage;
449
+ parserForLanguage?: ParserForLanguage | undefined;
255
450
  };
256
451
 
257
452
  export type CompartmentOption = {
258
- Compartment?: typeof Compartment;
453
+ Compartment?: typeof Compartment | undefined;
259
454
  };
260
455
 
261
456
  export type ModuleTransformsOption = {
262
- moduleTransforms?: ModuleTransforms;
457
+ moduleTransforms?: ModuleTransforms | undefined;
263
458
  };
264
459
 
265
460
  export type SyncModuleTransformsOption = {
266
- syncModuleTransforms?: SyncModuleTransforms;
461
+ syncModuleTransforms?: SyncModuleTransforms | undefined;
267
462
  };
268
463
 
269
464
  export type ArchiveOnlyOption = {
@@ -291,22 +486,22 @@ export type ArchiveOnlyOption = {
291
486
  * This option does not generally surface to users, but is set by the scenario,
292
487
  * off for `importLocation`, on for `makeArchive` and `makeScript`.
293
488
  */
294
- archiveOnly?: boolean;
489
+ archiveOnly?: boolean | undefined;
295
490
  };
296
491
 
297
492
  export type PolicyOption = {
298
- policy?: any;
493
+ policy?: SomePolicy | undefined;
299
494
  };
300
495
 
301
496
  export type LanguageForExtensionOption = {
302
- languageForExtension?: LanguageForExtension;
497
+ languageForExtension?: LanguageForExtension | undefined;
303
498
  };
304
499
 
305
500
  // ////////////////////////////////////////////////////////////////////////////////
306
501
  // Common option groups:
307
502
 
308
503
  export type SyncOrAsyncArchiveOptions = Partial<{
309
- captureSourceLocation: CaptureSourceLocationHook;
504
+ captureSourceLocation: CaptureSourceLocationHook | undefined;
310
505
  }> &
311
506
  ParserForLanguageOption &
312
507
  CompartmentOption &
@@ -332,11 +527,14 @@ type LinkingOptions = ParserForLanguageOption &
332
527
  /**
333
528
  * Result of `digestCompartmentMap()`
334
529
  */
335
- export interface DigestResult {
530
+ export interface DigestResult<
531
+ OldCompartmentName extends string = FileUrlString,
532
+ NewCompartmentName extends string = PackageCompartmentDescriptorName,
533
+ > {
336
534
  /**
337
535
  * Normalized `CompartmentMapDescriptor`
338
536
  */
339
- compartmentMap: CompartmentMapDescriptor;
537
+ compartmentMap: DigestedCompartmentMapDescriptor;
340
538
 
341
539
  /**
342
540
  * Sources found in the `CompartmentMapDescriptor`
@@ -347,34 +545,37 @@ export interface DigestResult {
347
545
  * A record of renamed {@link CompartmentDescriptor CompartmentDescriptors}
348
546
  * from _new_ to _original_ name
349
547
  */
350
- newToOldCompartmentNames: Record<string, string>;
548
+ newToOldCompartmentNames: Record<NewCompartmentName, OldCompartmentName>;
351
549
 
352
550
  /**
353
551
  * A record of renamed {@link CompartmentDescriptor CompartmentDescriptors}
354
552
  * from _original_ to _new_ name
355
553
  */
356
- oldToNewCompartmentNames: Record<string, string>;
554
+ oldToNewCompartmentNames: Record<OldCompartmentName, NewCompartmentName>;
357
555
 
358
556
  /**
359
557
  * Alias for `newToOldCompartmentNames`
360
558
  * @deprecated Use {@link newToOldCompartmentNames} instead.
361
559
  */
362
- compartmentRenames: Record<string, string>;
560
+ compartmentRenames: Record<NewCompartmentName, OldCompartmentName>;
363
561
  }
364
562
 
365
563
  /**
366
564
  * The result of `captureFromMap`.
367
565
  */
368
566
  export type CaptureResult = Omit<DigestResult, 'compartmentMap' | 'sources'> & {
369
- captureCompartmentMap: DigestResult['compartmentMap'];
567
+ captureCompartmentMap: DigestedCompartmentMapDescriptor;
370
568
  captureSources: DigestResult['sources'];
371
569
  };
372
570
 
373
571
  /**
374
572
  * The result of `makeArchiveCompartmentMap`
375
573
  */
376
- export type ArchiveResult = Omit<DigestResult, 'compartmentMap' | 'sources'> & {
377
- archiveCompartmentMap: DigestResult['compartmentMap'];
574
+ export type ArchiveResult = Omit<
575
+ DigestResult<FileUrlString, string>,
576
+ 'compartmentMap' | 'sources'
577
+ > & {
578
+ archiveCompartmentMap: DigestedCompartmentMapDescriptor;
378
579
  archiveSources: DigestResult['sources'];
379
580
  };
380
581
 
@@ -385,18 +586,31 @@ export type ArchiveResult = Omit<DigestResult, 'compartmentMap' | 'sources'> & {
385
586
  export type Sources = Record<string, CompartmentSources>;
386
587
  export type CompartmentSources = Record<string, ModuleSource>;
387
588
 
388
- // TODO unionize:
389
- export type ModuleSource = Partial<{
589
+ export type ModuleSource =
590
+ | LocalModuleSource
591
+ | ExitModuleSource
592
+ | ErrorModuleSource;
593
+
594
+ export interface BaseModuleSource {
390
595
  /** module loading error deferred to later stage */
596
+
597
+ deferredError?: string;
598
+ }
599
+
600
+ export interface ErrorModuleSource extends BaseModuleSource {
391
601
  deferredError: string;
602
+ }
603
+
604
+ export interface LocalModuleSource extends BaseModuleSource {
392
605
  /**
393
606
  * package-relative location.
394
607
  * Not suitable for capture in an archive or bundle since it varies from host
395
608
  * to host and would frustrate integrity hash checks.
396
609
  */
397
610
  location: string;
398
- /** fully qualified location */
399
- sourceLocation: string;
611
+ parser: Language;
612
+ /** in lowercase base-16 (hexadecimal) */
613
+ sha512?: string;
400
614
  /**
401
615
  * directory name of the original source.
402
616
  * This is safe to capture in a compartment map because it is _unlikely_ to
@@ -412,15 +626,19 @@ export type ModuleSource = Partial<{
412
626
  * https://github.com/endojs/endo/issues/2671
413
627
  */
414
628
  sourceDirname: string;
629
+ /** fully qualified location */
630
+
631
+ sourceLocation: FileUrlString;
415
632
  bytes: Uint8Array;
416
- /** in lowercase base-16 (hexadecimal) */
417
- sha512: string;
418
- parser: Language;
419
- /** indicates that this is a reference that exits the mapped compartments */
420
- exit: string;
421
633
  /** module for the module */
422
634
  record: StaticModuleType;
423
- }>;
635
+ }
636
+
637
+ export interface ExitModuleSource extends BaseModuleSource {
638
+ /** indicates that this is a reference that exits the mapped compartments */
639
+
640
+ exit: string;
641
+ }
424
642
 
425
643
  export type SourceMapHook = (
426
644
  sourceMap: string,
@@ -450,14 +668,14 @@ type ModuleTransformArguments = [
450
668
  moduleLocation: string,
451
669
  packageLocation: string,
452
670
  params: {
453
- sourceMap?: string;
671
+ sourceMap?: string | undefined;
454
672
  },
455
673
  ];
456
674
 
457
675
  type ModuleTransformResult = {
458
676
  bytes: Uint8Array;
459
677
  parser: Language;
460
- sourceMap?: string;
678
+ sourceMap?: string | undefined;
461
679
  };
462
680
 
463
681
  export type ExitModuleImportHook = (
@@ -516,11 +734,11 @@ type ParseArguments = [
516
734
  moduleLocation: string,
517
735
  packageLocation: string,
518
736
  options?: Partial<{
519
- sourceMap: string;
520
- sourceMapHook: SourceMapHook;
521
- sourceMapUrl: string;
522
- readPowers: ReadFn | ReadPowers;
523
- compartmentDescriptor: CompartmentDescriptor;
737
+ sourceMap: string | undefined;
738
+ sourceMapHook: SourceMapHook | undefined;
739
+ sourceMapUrl: string | undefined;
740
+ readPowers: ReadFn | ReadPowers | undefined;
741
+ compartmentDescriptor: CompartmentDescriptor | undefined;
524
742
  }> &
525
743
  ArchiveOnlyOption,
526
744
  ];
@@ -532,7 +750,7 @@ export type ParseResult = {
532
750
  bytes: Uint8Array;
533
751
  parser: Language;
534
752
  record: FinalStaticModuleType;
535
- sourceMap?: string;
753
+ sourceMap?: string | undefined;
536
754
  };
537
755
 
538
756
  export type AsyncParseFn = (...args: ParseArguments) => Promise<ParseResult>;
@@ -556,3 +774,16 @@ export type LogFn = (...args: any[]) => void;
556
774
  * A string that represents a file URL.
557
775
  */
558
776
  export type FileUrlString = `file://${string}`;
777
+
778
+ /**
779
+ * A function that renames compartments; used by `digestCompartmentMap()`.
780
+ *
781
+ * The default implementation uses {@link PackageCompartmentDescriptorName} as the key type.
782
+ *
783
+ * @returns Mapping from old compartment names to new compartment names
784
+ * @template NewName Key type
785
+ */
786
+ export type CompartmentsRenameFn<
787
+ OldName extends string = FileUrlString,
788
+ NewName extends string = PackageCompartmentDescriptorName,
789
+ > = (compartments: PackageCompartmentDescriptors) => Record<OldName, NewName>;
@@ -3,14 +3,20 @@
3
3
  *
4
4
  * @module
5
5
  */
6
+ /**
7
+ * A node in a `GenericGraph`.
8
+ */
9
+ export type GenericGraphNode = string | {
10
+ toString: () => string;
11
+ };
6
12
  /**
7
13
  * Context used for shortest-path traversal algorithm
8
14
  *
9
15
  * @template T The type of nodes in the graph
10
16
  * @internal
11
17
  */
12
- export interface TraversalContext<T = string, U = number> {
13
- distances: Map<T, U>;
18
+ export interface TraversalContext<T extends GenericGraphNode = string> {
19
+ paths: Map<T, T[]>;
14
20
  predecessors: Map<T, T>;
15
21
  queue: Set<T>;
16
22
  }
@@ -1 +1 @@
1
- {"version":3,"file":"generic-graph.d.ts","sourceRoot":"","sources":["generic-graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,MAAM;IACtD,SAAS,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrB,YAAY,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CACf"}
1
+ {"version":3,"file":"generic-graph.d.ts","sourceRoot":"","sources":["generic-graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,GAAG,MAAM;IACnE,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACnB,YAAY,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CACf"}