@endo/eventual-send 1.2.8 → 1.3.1

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@endo/eventual-send",
3
- "version": "1.2.8",
3
+ "version": "1.3.1",
4
4
  "description": "Extend a Promise class to implement the eventual-send API",
5
5
  "type": "module",
6
6
  "main": "src/no-shim.js",
@@ -39,7 +39,7 @@
39
39
  "@endo/env-options": "^1.1.8"
40
40
  },
41
41
  "devDependencies": {
42
- "@endo/lockdown": "^1.0.13",
42
+ "@endo/lockdown": "^1.0.15",
43
43
  "ava": "^6.1.3",
44
44
  "c8": "^7.14.0",
45
45
  "tsd": "^0.31.2",
@@ -77,5 +77,5 @@
77
77
  "typeCoverage": {
78
78
  "atLeast": 77.81
79
79
  },
80
- "gitHead": "5486ed1f238104716b6a8321b977fbc508ef80e1"
80
+ "gitHead": "9b6784831d37db948cdd61f6da1f3489e8f97906"
81
81
  }
package/src/E.d.ts CHANGED
@@ -51,8 +51,11 @@ export type EProxy = ReturnType<(HandledPromise: HandledPromiseConstructor) => (
51
51
  readonly when: <T, U = T>(x: T | PromiseLike<T>, onfulfilled?: ((value: T) => ERef<U>) | undefined, onrejected?: ((reason: any) => ERef<U>) | undefined) => Promise<U>;
52
52
  }>;
53
53
  /**
54
- * Creates a type that accepts both near and marshalled references that were
55
- * returned from `Remotable` or `Far`, and also promises for such references.
54
+ * Declare an object that is potentially a far reference of type Primary whose
55
+ * auxilliary data has type Local. This should be used only for consumers of
56
+ * Far objects in arguments and declarations; the only creators of Far objects
57
+ * are distributed object creator components like the `Far` or `Remotable`
58
+ * functions.
56
59
  */
57
60
  export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<Local & import("./types.js").RemotableBrand<Local, Primary>>;
58
61
  /**
@@ -60,8 +63,17 @@ export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<Local & import("./
60
63
  * properties that are *not* functions.
61
64
  */
62
65
  export type DataOnly<T> = Omit<T, FilteredKeys<T, import("./types.js").Callable>>;
66
+ /**
67
+ * Declare that `T` may or may not be a Promise. This should be used only for
68
+ * consumers of arguments and declarations; return values should specifically be
69
+ * `Promise<T>` or `T` itself.
70
+ */
63
71
  export type ERef<T> = PromiseLike<T> | T;
64
- export type ECallable<T extends import("./types.js").Callable> = (ReturnType<T> extends PromiseLike<infer U> ? T : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>);
72
+ /**
73
+ * The awaited return type of a function.
74
+ */
75
+ export type EReturn<T extends (...args: any[]) => any> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
76
+ export type ECallable<T extends import("./types.js").Callable> = (ReturnType<T> extends PromiseLike<infer U> ? T : (...args: Parameters<T>) => Promise<EReturn<T>>);
65
77
  export type EMethods<T> = { readonly [P in keyof T]: T[P] extends import("./types.js").Callable ? ECallable<T[P]> : never; };
66
78
  export type EGetters<T> = { readonly [P in keyof T]: T[P] extends PromiseLike<infer U> ? T[P] : Promise<Awaited<T[P]>>; };
67
79
  export type ESendOnlyCallable<T extends import("./types.js").Callable> = (...args: Parameters<T>) => Promise<void>;
@@ -94,8 +106,9 @@ export type EPromiseKit<R = unknown> = {
94
106
  settler: import("./types.js").Settler<R>;
95
107
  };
96
108
  /**
97
- * Type for an object that must only be invoked with E. It supports a given
98
- * interface but declares all the functions as asyncable.
109
+ * Declare a near object that must only be invoked with E, even locally. It
110
+ * supports the `T` interface but additionally permits `T`'s methods to return
111
+ * `PromiseLike`s even if `T` declares them as only synchronous.
99
112
  */
100
113
  export type EOnly<T> = (T extends import("./types.js").Callable ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>> : T extends Record<PropertyKey, import("./types.js").Callable> ? { [K in keyof T]: T[K] extends import("./types.js").Callable ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>> : T[K]; } : T);
101
114
  /**
package/src/E.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"E.d.ts","sourceRoot":"","sources":["E.js"],"names":[],"mappings":";qBA6Pc,UAAU,kBAnFb,yBAAyB,OAUjB,CAAC,KACH,CAAC,KACC,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAKjD;;;;;;;;;;OAUG;mBAJU,CAAC,KACH,CAAC,KACC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IASrC;;;;;;;;OAQG;;;;;;IAGH;;;;;;;;OAQG;wBAJU,CAAC,KACH,CAAC,KACC,0BAA0B,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAS3D;;;;;;;;;;;OAWG;oBAPU,CAAC,EACA,CAAC,SACJ,CAAC,GAAC,WAAW,CAAC,CAAC,CAAC,yBACR,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,sCACZ,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,kBACtB,OAAO,CAAC,CAAC,CAAC;EAcA;;;;;mBAMlB,OAAO,EACN,KAAK,wBACN,IAAI,CAAC,KAAK,GAAG,OAAO,YAAY,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;;;;;qBAOjE,CAAC,IACD,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,CAAC;iBAKvD,CAAC,IACD,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;sBAIc,CAAC,SAAjC,OAAQ,YAAY,EAAE,QAAS,IAC/B,CACR,UAAU,CAAC,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GACtC,CAAC,GACD,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAChE;qBAIS,CAAC,IACD,EACZ,QAAY,EAAE,CAAY,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GAC/D,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACf,KAAK,GACV;qBAIS,CAAC,IACD,EACZ,QAAY,EAAE,CAAY,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GACtD,CAAC,CAAC,CAAC,CAAC,GACJ,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3B;8BAIyC,CAAC,SAAjC,OAAQ,YAAY,EAAE,QAAS,IAC/B,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC;6BAIzC,CAAC,IACD,EACZ,QAAY,EAAE,CAAY,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GAC/D,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACvB,KAAK,GACV;uCAIS,CAAC,IACD,CACR,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GACnC,iBAAiB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GACpD,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAClC;+BAIS,CAAC,IACD,CACR,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GACnC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GACpC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAC1B;;;;;;;;;;;yBAaS,CAAC,EACD,CAAC,IACD,GAAG,CAAY,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC;;;;;yBAOxD,CAAC,IACD,CACR,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GACnC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,GACzC,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,CAAC,CAC5D;;;;4BAMS,CAAC,IACD,CACR,CAAC,SAAS,OAAO,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC3D,YAAY,CAAC,CAAC,CAAC,GACf,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACxE,YAAY,CAAC,CAAC,CAAC,GACf,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,GACV,CAAC,CACN;wBAIS,CAAC,IACD,CACR,CAAC,SAAS,OAAO,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC3D,CAAC,GACD,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACxE,CAAC,GACD,CAAC,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,GACV,CAAC,CACN;wBAIU,CAAC,cACF;IACR,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,OAAO,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1C;;;;;kBAOS,CAAC,IACD,CACR,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GACnC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC/D,CAAC,SAAS,MAAM,CAAC,WAAW,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC,GAC5D,GACG,CAAY,IAAP,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,YAAY,EAAE,QAAQ,GACtD,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACrE,CAAC,CAAC,CAAC,CAAC,GACT,GACD,CAAC,CACN;AAtPJ;;GAEG;AACH,uCAFW,yBAAyB,KAUjB,CAAC,KACH,CAAC,KACC,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAKjD;;;;;;;;;;OAUG;mBAJU,CAAC,KACH,CAAC,KACC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IASrC;;;;;;;;OAQG;;;;;;IAGH;;;;;;;;OAQG;wBAJU,CAAC,KACH,CAAC,KACC,0BAA0B,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAS3D;;;;;;;;;;;OAWG;oBAPU,CAAC,EACA,CAAC,SACJ,CAAC,GAAC,WAAW,CAAC,CAAC,CAAC,yBACR,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,sCACZ,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,kBACtB,OAAO,CAAC,CAAC,CAAC;EAU9B;+CAlP6C,YAAY"}
1
+ {"version":3,"file":"E.d.ts","sourceRoot":"","sources":["E.js"],"names":[],"mappings":"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"}
package/src/E.js CHANGED
@@ -2,7 +2,7 @@ import { trackTurns } from './track-turns.js';
2
2
  import { makeMessageBreakpointTester } from './message-breakpoints.js';
3
3
 
4
4
  const { details: X, quote: q, Fail, error: makeError } = assert;
5
- const { assign, create } = Object;
5
+ const { assign, freeze } = Object;
6
6
 
7
7
  /**
8
8
  * @import { HandledPromiseConstructor } from './types.js';
@@ -167,6 +167,23 @@ const makeEGetProxyHandler = (x, HandledPromise) =>
167
167
  get: (_target, prop) => HandledPromise.get(x, prop),
168
168
  });
169
169
 
170
+ /**
171
+ * `freeze` but not `harden` the proxy target so it remains trapping.
172
+ * Thus, it should not be shared outside this module.
173
+ *
174
+ * @see https://github.com/endojs/endo/blob/master/packages/ses/docs/preparing-for-stabilize.md
175
+ */
176
+ const funcTarget = freeze(() => {});
177
+
178
+ /**
179
+ /**
180
+ * `freeze` but not `harden` the proxy target so it remains trapping.
181
+ * Thus, it should not be shared outside this module.
182
+ *
183
+ * @see https://github.com/endojs/endo/blob/master/packages/ses/docs/preparing-for-stabilize.md
184
+ */
185
+ const objTarget = freeze({ __proto__: null });
186
+
170
187
  /**
171
188
  * @param {HandledPromiseConstructor} HandledPromise
172
189
  */
@@ -178,12 +195,20 @@ const makeE = HandledPromise => {
178
195
  * method calls returns a promise. The method will be invoked on whatever
179
196
  * 'x' designates (or resolves to) in a future turn, not this one.
180
197
  *
198
+ * An example call would be
199
+ *
200
+ * E(zoe).install(bundle)
201
+ * .then(installationHandle => { ... })
202
+ * .catch(err => { ... });
203
+ *
204
+ * See https://endojs.github.io/endo/functions/_endo_far.E.html for details.
205
+ *
181
206
  * @template T
182
207
  * @param {T} x target for method/function call
183
208
  * @returns {ECallableOrMethods<RemoteFunctions<T>>} method/function call proxy
184
209
  */
185
210
  // @ts-expect-error XXX typedef
186
- x => harden(new Proxy(() => {}, makeEProxyHandler(x, HandledPromise))),
211
+ x => new Proxy(funcTarget, makeEProxyHandler(x, HandledPromise)),
187
212
  {
188
213
  /**
189
214
  * E.get(x) returns a proxy on which you can get arbitrary properties.
@@ -196,11 +221,8 @@ const makeE = HandledPromise => {
196
221
  * @returns {EGetters<LocalRecord<T>>} property get proxy
197
222
  * @readonly
198
223
  */
199
- get: x =>
200
- // @ts-expect-error XXX typedef
201
- harden(
202
- new Proxy(create(null), makeEGetProxyHandler(x, HandledPromise)),
203
- ),
224
+ // @ts-expect-error XXX typedef
225
+ get: x => new Proxy(objTarget, makeEGetProxyHandler(x, HandledPromise)),
204
226
 
205
227
  /**
206
228
  * E.resolve(x) converts x to a handled promise. It is
@@ -224,9 +246,7 @@ const makeE = HandledPromise => {
224
246
  */
225
247
  sendOnly: x =>
226
248
  // @ts-expect-error XXX typedef
227
- harden(
228
- new Proxy(() => {}, makeESendOnlyProxyHandler(x, HandledPromise)),
229
- ),
249
+ new Proxy(funcTarget, makeESendOnlyProxyHandler(x, HandledPromise)),
230
250
 
231
251
  /**
232
252
  * E.when(x, res, rej) is equivalent to
@@ -254,8 +274,11 @@ export default makeE;
254
274
  /** @typedef {ReturnType<makeE>} EProxy */
255
275
 
256
276
  /**
257
- * Creates a type that accepts both near and marshalled references that were
258
- * returned from `Remotable` or `Far`, and also promises for such references.
277
+ * Declare an object that is potentially a far reference of type Primary whose
278
+ * auxilliary data has type Local. This should be used only for consumers of
279
+ * Far objects in arguments and declarations; the only creators of Far objects
280
+ * are distributed object creator components like the `Far` or `Remotable`
281
+ * functions.
259
282
  *
260
283
  * @template Primary The type of the primary reference.
261
284
  * @template [Local=DataOnly<Primary>] The local properties of the object.
@@ -274,6 +297,16 @@ export default makeE;
274
297
  * @see {@link https://github.com/microsoft/TypeScript/issues/31394}
275
298
  * @template T
276
299
  * @typedef {PromiseLike<T> | T} ERef
300
+ * Declare that `T` may or may not be a Promise. This should be used only for
301
+ * consumers of arguments and declarations; return values should specifically be
302
+ * `Promise<T>` or `T` itself.
303
+ */
304
+
305
+ /**
306
+ * The awaited return type of a function.
307
+ *
308
+ * @template {(...args: any[]) => any} T
309
+ * @typedef {T extends (...args: any[]) => infer R ? Awaited<R> : never} EReturn
277
310
  */
278
311
 
279
312
  /**
@@ -281,7 +314,7 @@ export default makeE;
281
314
  * @typedef {(
282
315
  * ReturnType<T> extends PromiseLike<infer U> // if function returns a promise
283
316
  * ? T // return the function
284
- * : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>> // make it return a promise
317
+ * : (...args: Parameters<T>) => Promise<EReturn<T>> // make it return a promise
285
318
  * )} ECallable
286
319
  */
287
320
 
@@ -399,8 +432,9 @@ export default makeE;
399
432
  */
400
433
 
401
434
  /**
402
- * Type for an object that must only be invoked with E. It supports a given
403
- * interface but declares all the functions as asyncable.
435
+ * Declare a near object that must only be invoked with E, even locally. It
436
+ * supports the `T` interface but additionally permits `T`'s methods to return
437
+ * `PromiseLike`s even if `T` declares them as only synchronous.
404
438
  *
405
439
  * @template T
406
440
  * @typedef {(
package/src/exports.d.ts CHANGED
@@ -12,6 +12,7 @@ export type {
12
12
  ERef,
13
13
  EProxy,
14
14
  EOnly,
15
+ EReturn,
15
16
  RemoteFunctions,
16
17
  LocalRecord,
17
18
  FilteredKeys,
@@ -1,7 +1,7 @@
1
1
  /* eslint-disable @endo/no-polymorphic-call, import/no-extraneous-dependencies, no-restricted-globals */
2
2
  import { expectType } from 'tsd';
3
3
  import { E } from '../test/_get-hp.js';
4
- import type { ERef, FarRef } from './exports.js';
4
+ import type { ERef, EReturn, FarRef } from './exports.js';
5
5
 
6
6
  // Check the legacy ERef type
7
7
  const foo = async (a: ERef<{ bar(): string; baz: number }>) => {
@@ -21,6 +21,19 @@ const foo = async (a: ERef<{ bar(): string; baz: number }>) => {
21
21
  a.bar();
22
22
  };
23
23
 
24
+ // EReturn
25
+ {
26
+ const makeFoo = async () => 'foo' as const;
27
+ expectType<Promise<'foo'>>(makeFoo());
28
+ type Foo = EReturn<typeof makeFoo>;
29
+ expectType<Foo>('foo');
30
+
31
+ const fooP = Promise.resolve('foo' as const);
32
+ expectType<Promise<'foo'>>(fooP);
33
+ // @ts-expect-error takes only functions
34
+ EReturn<typeof fooP>;
35
+ }
36
+
24
37
  // FarRef<T>
25
38
  const foo2 = async (a: FarRef<{ bar(): string; baz: number }>) => {
26
39
  const { baz } = await a;
@@ -1 +1 @@
1
- {"version":3,"file":"handled-promise.d.ts","sourceRoot":"","sources":["handled-promise.js"],"names":[],"mappings":"AAyDO;SAyIe,CAAC,YAAY,eAAe,CAAC,CAAC,CAAC,uBAAuB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAAa,OAAO,CAAC,OAAO,CAAC;qDAwY9I;oBAGY,CAAC,IACD;IACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC1G,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClF;0CAIc,CAAC,SAAN,EAAI,IACJ;IACR,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC;QAChB,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;KAC7C,CAAC;CACH;4BAIU,CAAC,cACF,CACR,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,EACnC,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,EACzC,mBAAmB,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,KAAK,MAAM,KACvG,IAAI;oBAIE,CAAC,cACF;IACR,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,mBAAmB,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;CACzG;0CAIS;IACR,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/E,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CACvD;wCAGU,UAAU,CAAC,OAAO,kBAAkB,CAAC"}
1
+ {"version":3,"file":"handled-promise.d.ts","sourceRoot":"","sources":["handled-promise.js"],"names":[],"mappings":"AAyDO;SAyIe,CAAC,YAAY,eAAe,CAAC,CAAC,CAAC,uBAAuB,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAAa,OAAO,CAAC,OAAO,CAAC;qDA2Y9I;oBAGY,CAAC,IACD;IACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7E,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC1G,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClF;0CAIc,CAAC,SAAN,EAAI,IACJ;IACR,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC;QAChB,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;KAC7C,CAAC;CACH;4BAIU,CAAC,cACF,CACR,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,EACnC,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,EACzC,mBAAmB,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,KAAK,MAAM,KACvG,IAAI;oBAIE,CAAC,cACF;IACR,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,mBAAmB,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,6BAA6B,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;CACzG;0CAIS;IACR,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/F,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/E,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CACvD;wCAGU,UAAU,CAAC,OAAO,kBAAkB,CAAC"}
@@ -309,6 +309,9 @@ export const makeHandledPromise = () => {
309
309
  if (proxyOpts) {
310
310
  const {
311
311
  handler: proxyHandler,
312
+ // The proxy target can be frozen but should not be hardened
313
+ // so it remains trapping.
314
+ // See https://github.com/endojs/endo/blob/master/packages/ses/docs/preparing-for-stabilize.md
312
315
  target: proxyTarget,
313
316
  revokerCallback,
314
317
  } = proxyOpts;
package/src/no-shim.d.ts CHANGED
@@ -1,3 +1,13 @@
1
+ /**
2
+ * E(x) returns a proxy on which you can call arbitrary methods. Each of these method calls returns a promise.
3
+ * The method will be invoked on whatever 'x' designates (or resolves to) in a future turn, not this one.
4
+ *
5
+ * E.get(x) returns a proxy on which you can get arbitrary properties. Each of these properties returns a
6
+ * promise for the property. The promise value will be the property fetched from whatever 'x' designates (or
7
+ * resolves to) in a future turn, not this one.
8
+ *
9
+ * E.when(x, res, rej) is equivalent to HandledPromise.resolve(x).then(res, rej)
10
+ */
1
11
  export const E: (<T>(x: T) => ECallableOrMethods<RemoteFunctions<T>>) & {
2
12
  readonly get: <T>(x: T) => EGetters<LocalRecord<T>>;
3
13
  readonly resolve: {
@@ -1 +1 @@
1
- {"version":3,"file":"no-shim.d.ts","sourceRoot":"","sources":["no-shim.js"],"names":[],"mappings":"AAOA;;;;;;;;;EAA2B;;;qCAHuG,QAAQ;wCAAR,QAAQ;iCAAR,QAAQ;8BAAR,QAAQ;gDAAR,QAAQ;0BAAR,QAAQ;AAD1I,qEAAqE;AACrE,6IAA6I;AAE7I;;;oFAA0B;qCAHkB,sBAAsB;6BAAtB,sBAAsB"}
1
+ {"version":3,"file":"no-shim.d.ts","sourceRoot":"","sources":["no-shim.js"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH;;;;;;;;;EAA2B;;;qCAduG,QAAQ;wCAAR,QAAQ;iCAAR,QAAQ;8BAAR,QAAQ;gDAAR,QAAQ;0BAAR,QAAQ;AAD1I,qEAAqE;AACrE,6IAA6I;AAE7I;;;oFAA0B;qCAHkB,sBAAsB;6BAAtB,sBAAsB"}
package/src/no-shim.js CHANGED
@@ -5,6 +5,17 @@ import makeE from './E.js';
5
5
  /** @import {ECallableOrMethods, EGetters, ERef, ERemoteFunctions, ESendOnlyCallableOrMethods, LocalRecord, RemoteFunctions} from './E.js' */
6
6
 
7
7
  const hp = HandledPromise;
8
+
9
+ /**
10
+ * E(x) returns a proxy on which you can call arbitrary methods. Each of these method calls returns a promise.
11
+ * The method will be invoked on whatever 'x' designates (or resolves to) in a future turn, not this one.
12
+ *
13
+ * E.get(x) returns a proxy on which you can get arbitrary properties. Each of these properties returns a
14
+ * promise for the property. The promise value will be the property fetched from whatever 'x' designates (or
15
+ * resolves to) in a future turn, not this one.
16
+ *
17
+ * E.when(x, res, rej) is equivalent to HandledPromise.resolve(x).then(res, rej)
18
+ */
8
19
  export const E = makeE(hp);
9
20
  export { hp as HandledPromise };
10
21