@endo/eventual-send - npm Package Compare versions

Comparing version 0.17.2 to 0.17.3

package.json

 {
   "name": "@endo/eventual-send",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "description": "Extend a Promise class to implement the eventual-send API",
@@ -32,8 +32,11 @@ "type": "module",
   "homepage": "https://github.com/endojs/endo#readme",
+  "dependencies": {
+    "@endo/env-options": "^0.1.1"
+  },
   "devDependencies": {
-    "@endo/lockdown": "^0.1.28",
-    "@endo/ses-ava": "^0.2.40",
-    "ava": "^5.2.0",
-    "c8": "^7.7.3",
-    "tsd": "^0.24.1"
+    "@endo/lockdown": "^0.1.29",
+    "@endo/ses-ava": "^0.2.41",
+    "ava": "^5.3.0",
+    "c8": "^7.14.0",
+    "tsd": "^0.28.1"
   },
@@ -65,3 +68,3 @@ "keywords": [
   },
-  "gitHead": "38c2c59d6ae8c53f84cd333e6c7828e2d37604e2"
+  "gitHead": "106da55b8bcea3067f70c29c357806f3f2e55c52"
 }

src/E.d.ts

@@ -0,6 +1,158 @@
+export default makeE;
+export type EProxy = ReturnType<(HandledPromise: {
+    new <R>(executor: import("./handled-promise.js").HandledExecutor<R>, unfulfilledHandler?: import("./handled-promise.js").Handler<Promise<unknown>> | undefined): Promise<R>;
+    prototype: Promise<unknown>;
+} & PromiseConstructor & import("./handled-promise.js").HandledPromiseStaticMethods) => (<T>(x: T) => ECallableOrMethods<RemoteFunctions<T>>) & {
+    /**
+     * E.get(x) returns a proxy on which you can get arbitrary properties.
+     * Each of these properties returns a promise for the property.  The promise
+     * value will be the property fetched from whatever 'x' designates (or
+     * resolves to) in a future turn, not this one.
+     *
+     * @template T
+     * @param {T} x target for property get
+     * @returns {EGetters<LocalRecord<T>>} property get proxy
+     * @readonly
+     */
+    readonly get: <T_1>(x: T_1) => EGetters<LocalRecord<T_1>>;
+    /**
+     * E.resolve(x) converts x to a handled promise. It is
+     * shorthand for HandledPromise.resolve(x)
+     *
+     * @template T
+     * @param {T} x value to convert to a handled promise
+     * @returns {Promise<Awaited<T>>} handled promise for x
+     * @readonly
+     */
+    readonly resolve: {
+        (): Promise<void>;
+        <T_2>(value: T_2): Promise<Awaited<T_2>>;
+        <T_3>(value: T_3 | PromiseLike<T_3>): Promise<Awaited<T_3>>;
+    };
+    /**
+     * E.sendOnly returns a proxy similar to E, but for which the results
+     * are ignored (undefined is returned).
+     *
+     * @template T
+     * @param {T} x target for method/function call
+     * @returns {ESendOnlyCallableOrMethods<RemoteFunctions<T>>} method/function call proxy
+     * @readonly
+     */
+    readonly sendOnly: <T_4>(x: T_4) => ESendOnlyCallableOrMethods<RemoteFunctions<T_4>>;
+    /**
+     * E.when(x, res, rej) is equivalent to
+     * HandledPromise.resolve(x).then(res, rej)
+     *
+     * @template T
+     * @template [U = T]
+     * @param {T|PromiseLike<T>} x value to convert to a handled promise
+     * @param {(value: T) => ERef<U>} [onfulfilled]
+     * @param {(reason: any) => ERef<U>} [onrejected]
+     * @returns {Promise<U>}
+     * @readonly
+     */
+    readonly when: <T_5, U = T_5>(x: T_5 | PromiseLike<T_5>, onfulfilled?: ((value: T_5) => ERef<U>) | undefined, onrejected?: ((reason: any) => ERef<U>) | undefined) => Promise<U>;
+}>;
 /**
- * @param {import('./index').HandledPromiseConstructor} HandledPromise
- * @returns {import('./index').EProxy}
+ * Creates a type that accepts both near and marshalled references that were
+ * returned from `Remotable` or `Far`, and also promises for such references.
  */
-export default function makeE(HandledPromise: import('./index').HandledPromiseConstructor): import('./index').EProxy;
+export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<Local & import('./types').RemotableBrand<Local, Primary>>;
+/**
+ * `DataOnly<T>` means to return a record type `T2` consisting only of
+ * properties that are *not* functions.
+ */
+export type DataOnly<T> = Omit<T, FilteredKeys<T, import('./types').Callable>>;
+export type ERef<T> = PromiseLike<T> | T;
+export type ECallable<T extends import("./types").Callable> = ReturnType<T> extends PromiseLike<infer U> ? T : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+export type EMethods<T> = { readonly [P in keyof T]: T[P] extends import("./types").Callable ? ECallable<T[P]> : never; };
+export type EGetters<T> = { readonly [P in keyof T]: T[P] extends PromiseLike<infer U> ? T[P] : Promise<Awaited<T[P]>>; };
+export type ESendOnlyCallable<T extends import("./types").Callable> = (...args: Parameters<T>) => Promise<void>;
+export type ESendOnlyMethods<T> = { readonly [P in keyof T]: T[P] extends import("./types").Callable ? ESendOnlyCallable<T[P]> : never; };
+export type ESendOnlyCallableOrMethods<T> = (T extends import('./types').Callable ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>> : ESendOnlyMethods<Required<T>>);
+export type ECallableOrMethods<T> = (T extends import('./types').Callable ? ECallable<T> & EMethods<Required<T>> : EMethods<Required<T>>);
+/**
+ * Return a union of property names/symbols/numbers P for which the record element T[P]'s type extends U.
+ *
+ * Given const x = { a: 123, b: 'hello', c: 42, 49: () => {}, 53: 67 },
+ *
+ * FilteredKeys<typeof x, number> is the type 'a' | 'c' | 53.
+ * FilteredKeys<typeof x, string> is the type 'b'.
+ * FilteredKeys<typeof x, 42 | 67> is the type 'c' | 53.
+ * FilteredKeys<typeof x, boolean> is the type never.
+ */
+export type FilteredKeys<T, U> = { [P in keyof T]: T[P] extends U ? P : never; }[keyof T];
+/**
+ * `PickCallable<T>` means to return a single root callable or a record type
+ * consisting only of properties that are functions.
+ */
+export type PickCallable<T> = T extends import("./types").Callable ? (...args: Parameters<T>) => ReturnType<T> : Pick<T, FilteredKeys<T, import("./types").Callable>>;
+/**
+ * `RemoteFunctions<T>` means to return the functions and properties that are remotely callable.
+ */
+export type RemoteFunctions<T> = T extends import("./types").RemotableBrand<infer L, infer R> ? PickCallable<R> : Awaited<T> extends import("./types").RemotableBrand<infer L_1, infer R_1> ? PickCallable<R_1> : T extends PromiseLike<infer U> ? Awaited<T> : T;
+export type LocalRecord<T> = T extends import("./types").RemotableBrand<infer L, infer R> ? L : Awaited<T> extends import("./types").RemotableBrand<infer L_1, infer R_1> ? L_1 : T extends PromiseLike<infer U> ? Awaited<T> : T;
+export type EPromiseKit<R = unknown> = {
+    promise: Promise<R>;
+    settler: import('./types').Settler<R>;
+};
+/**
+ * Type for an object that must only be invoked with E.  It supports a given
+ * interface but declares all the functions as asyncable.
+ */
+export type EOnly<T> = T extends import("./types").Callable ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>> : T extends Record<PropertyKey, import("./types").Callable> ? { [K in keyof T]: T[K] extends import("./types").Callable ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>> : T[K]; } : T;
+/**
+ * @param {import('./types').HandledPromiseConstructor} HandledPromise
+ */
+declare function makeE(HandledPromise: import('./types').HandledPromiseConstructor): (<T>(x: T) => ECallableOrMethods<RemoteFunctions<T>>) & {
+    /**
+     * E.get(x) returns a proxy on which you can get arbitrary properties.
+     * Each of these properties returns a promise for the property.  The promise
+     * value will be the property fetched from whatever 'x' designates (or
+     * resolves to) in a future turn, not this one.
+     *
+     * @template T
+     * @param {T} x target for property get
+     * @returns {EGetters<LocalRecord<T>>} property get proxy
+     * @readonly
+     */
+    readonly get: <T_1>(x: T_1) => EGetters<LocalRecord<T_1>>;
+    /**
+     * E.resolve(x) converts x to a handled promise. It is
+     * shorthand for HandledPromise.resolve(x)
+     *
+     * @template T
+     * @param {T} x value to convert to a handled promise
+     * @returns {Promise<Awaited<T>>} handled promise for x
+     * @readonly
+     */
+    readonly resolve: {
+        (): Promise<void>;
+        <T_2>(value: T_2): Promise<Awaited<T_2>>;
+        <T_3>(value: T_3 | PromiseLike<T_3>): Promise<Awaited<T_3>>;
+    };
+    /**
+     * E.sendOnly returns a proxy similar to E, but for which the results
+     * are ignored (undefined is returned).
+     *
+     * @template T
+     * @param {T} x target for method/function call
+     * @returns {ESendOnlyCallableOrMethods<RemoteFunctions<T>>} method/function call proxy
+     * @readonly
+     */
+    readonly sendOnly: <T_4>(x: T_4) => ESendOnlyCallableOrMethods<RemoteFunctions<T_4>>;
+    /**
+     * E.when(x, res, rej) is equivalent to
+     * HandledPromise.resolve(x).then(res, rej)
+     *
+     * @template T
+     * @template [U = T]
+     * @param {T|PromiseLike<T>} x value to convert to a handled promise
+     * @param {(value: T) => ERef<U>} [onfulfilled]
+     * @param {(reason: any) => ERef<U>} [onrejected]
+     * @returns {Promise<U>}
+     * @readonly
+     */
+    readonly when: <T_5, U = T_5>(x: T_5 | PromiseLike<T_5>, onfulfilled?: ((value: T_5) => ERef<U>) | undefined, onrejected?: ((reason: any) => ERef<U>) | undefined) => Promise<U>;
+};
 //# sourceMappingURL=E.d.ts.map

src/E.js

 import { trackTurns } from './track-turns.js';
 
 const { details: X, quote: q, Fail } = assert;
+const { assign, create } = Object;
 
@@ -34,9 +35,9 @@ /** @type {ProxyHandler<any>} */
  * @param {*} x Any value passed to E(x)
- * @param {import('./index').HandledPromiseConstructor} HandledPromise
+ * @param {import('./types').HandledPromiseConstructor} HandledPromise
  * @returns {ProxyHandler} the Proxy handler
  */
-function EProxyHandler(x, HandledPromise) {
-  return harden({
+const makeEProxyHandler = (x, HandledPromise) =>
+  harden({
     ...baseFreezableProxyHandler,
-    get(_target, p, receiver) {
+    get: (_target, p, receiver) => {
       return harden(
@@ -64,6 +65,6 @@ {
     },
-    apply(_target, _thisArg, argArray = []) {
+    apply: (_target, _thisArg, argArray = []) => {
       return HandledPromise.applyFunction(x, argArray);
     },
-    has(_target, _p) {
+    has: (_target, _p) => {
       // We just pretend everything exists.
@@ -73,3 +74,2 @@ return true;
   });
-}
 
@@ -81,9 +81,9 @@ /**
  * @param {*} x Any value passed to E.sendOnly(x)
- * @param {import('./index').HandledPromiseConstructor} HandledPromise
+ * @param {import('./types').HandledPromiseConstructor} HandledPromise
  * @returns {ProxyHandler} the Proxy handler
  */
-function EsendOnlyProxyHandler(x, HandledPromise) {
-  return harden({
+const makeESendOnlyProxyHandler = (x, HandledPromise) =>
+  harden({
     ...baseFreezableProxyHandler,
-    get(_target, p, receiver) {
+    get: (_target, p, receiver) => {
       return harden(
@@ -108,7 +108,7 @@ {
     },
-    apply(_target, _thisArg, argsArray = []) {
+    apply: (_target, _thisArg, argsArray = []) => {
       HandledPromise.applyFunctionSendOnly(x, argsArray);
       return undefined;
     },
-    has(_target, _p) {
+    has: (_target, _p) => {
       // We just pretend that everything exists.
@@ -118,38 +118,262 @@ return true;
   });
-}
 
 /**
- * @param {import('./index').HandledPromiseConstructor} HandledPromise
- * @returns {import('./index').EProxy}
+ * A Proxy handler for E.get(x)
+ * It is a variant on the E(x) Proxy handler.
+ *
+ * @param {*} x Any value passed to E.get(x)
+ * @param {import('./types').HandledPromiseConstructor} HandledPromise
+ * @returns {ProxyHandler} the Proxy handler
  */
-export default function makeE(HandledPromise) {
-  function E(x) {
-    const handler = EProxyHandler(x, HandledPromise);
-    return harden(new Proxy(() => {}, handler));
-  }
+const makeEGetProxyHandler = (x, HandledPromise) =>
+  harden({
+    ...baseFreezableProxyHandler,
+    has: (_target, _prop) => true,
+    get: (_target, prop) => HandledPromise.get(x, prop),
+  });
 
-  const makeEGetterProxy = x =>
-    new Proxy(Object.create(null), {
-      ...baseFreezableProxyHandler,
-      has(_target, _prop) {
-        return true;
+/**
+ * @param {import('./types').HandledPromiseConstructor} HandledPromise
+ */
+const makeE = HandledPromise => {
+  return harden(
+    assign(
+      /**
+       * E(x) returns a proxy on which you can call arbitrary methods. Each of these
+       * method calls returns a promise. The method will be invoked on whatever
+       * 'x' designates (or resolves to) in a future turn, not this one.
+       *
+       * @template T
+       * @param {T} x target for method/function call
+       * @returns {ECallableOrMethods<RemoteFunctions<T>>} method/function call proxy
+       */
+      x => harden(new Proxy(() => {}, makeEProxyHandler(x, HandledPromise))),
+      {
+        /**
+         * E.get(x) returns a proxy on which you can get arbitrary properties.
+         * Each of these properties returns a promise for the property.  The promise
+         * value will be the property fetched from whatever 'x' designates (or
+         * resolves to) in a future turn, not this one.
+         *
+         * @template T
+         * @param {T} x target for property get
+         * @returns {EGetters<LocalRecord<T>>} property get proxy
+         * @readonly
+         */
+        get: x =>
+          harden(
+            new Proxy(create(null), makeEGetProxyHandler(x, HandledPromise)),
+          ),
+
+        /**
+         * E.resolve(x) converts x to a handled promise. It is
+         * shorthand for HandledPromise.resolve(x)
+         *
+         * @template T
+         * @param {T} x value to convert to a handled promise
+         * @returns {Promise<Awaited<T>>} handled promise for x
+         * @readonly
+         */
+        resolve: HandledPromise.resolve,
+
+        /**
+         * E.sendOnly returns a proxy similar to E, but for which the results
+         * are ignored (undefined is returned).
+         *
+         * @template T
+         * @param {T} x target for method/function call
+         * @returns {ESendOnlyCallableOrMethods<RemoteFunctions<T>>} method/function call proxy
+         * @readonly
+         */
+        sendOnly: x =>
+          harden(
+            new Proxy(() => {}, makeESendOnlyProxyHandler(x, HandledPromise)),
+          ),
+
+        /**
+         * E.when(x, res, rej) is equivalent to
+         * HandledPromise.resolve(x).then(res, rej)
+         *
+         * @template T
+         * @template [U = T]
+         * @param {T|PromiseLike<T>} x value to convert to a handled promise
+         * @param {(value: T) => ERef<U>} [onfulfilled]
+         * @param {(reason: any) => ERef<U>} [onrejected]
+         * @returns {Promise<U>}
+         * @readonly
+         */
+        when: (x, onfulfilled, onrejected) =>
+          HandledPromise.resolve(x).then(
+            ...trackTurns([onfulfilled, onrejected]),
+          ),
       },
-      get(_target, prop) {
-        return HandledPromise.get(x, prop);
-      },
-    });
+    ),
+  );
+};
 
-  E.get = makeEGetterProxy;
-  E.resolve = HandledPromise.resolve;
-  E.sendOnly = x => {
-    const handler = EsendOnlyProxyHandler(x, HandledPromise);
-    return harden(new Proxy(() => {}, handler));
-  };
+export default makeE;
 
-  E.when = (x, onfulfilled, onrejected) => {
-    const [onsuccess, onfailure] = trackTurns([onfulfilled, onrejected]);
-    return HandledPromise.resolve(x).then(onsuccess, onfailure);
-  };
+/** @typedef {ReturnType<makeE>} EProxy */
 
-  return harden(E);
-}
+/**
+ * Creates a type that accepts both near and marshalled references that were
+ * returned from `Remotable` or `Far`, and also promises for such references.
+ *
+ * @template Primary The type of the primary reference.
+ * @template [Local=DataOnly<Primary>] The local properties of the object.
+ * @typedef {ERef<Local & import('./types').RemotableBrand<Local, Primary>>} FarRef
+ */
+
+/**
+ * `DataOnly<T>` means to return a record type `T2` consisting only of
+ * properties that are *not* functions.
+ *
+ * @template T The type to be filtered.
+ * @typedef {Omit<T, FilteredKeys<T, import('./types').Callable>>} DataOnly
+ */
+
+/**
+ * @see {@link https://github.com/microsoft/TypeScript/issues/31394}
+ * @template T
+ * @typedef {PromiseLike<T> | T} ERef
+ */
+
+/**
+ * @template {import('./types').Callable} T
+ * @typedef {(
+ *   ReturnType<T> extends PromiseLike<infer U>                       // if function returns a promise
+ *     ? T                                                            // return the function
+ *     : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>  // make it return a promise
+ * )} ECallable
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ *   readonly [P in keyof T]: T[P] extends import('./types').Callable
+ *     ? ECallable<T[P]>
+ *     : never;
+ * }} EMethods
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ *   readonly [P in keyof T]: T[P] extends PromiseLike<infer U>
+ *     ? T[P]
+ *     : Promise<Awaited<T[P]>>;
+ * }} EGetters
+ */
+
+/**
+ * @template {import('./types').Callable} T
+ * @typedef {(...args: Parameters<T>) => Promise<void>} ESendOnlyCallable
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ *   readonly [P in keyof T]: T[P] extends import('./types').Callable
+ *     ? ESendOnlyCallable<T[P]>
+ *     : never;
+ * }} ESendOnlyMethods
+ */
+
+/**
+ * @template T
+ * @typedef {(
+ *   T extends import('./types').Callable
+ *     ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
+ *     : ESendOnlyMethods<Required<T>>
+ * )} ESendOnlyCallableOrMethods
+ */
+
+/**
+ * @template T
+ * @typedef {(
+ *   T extends import('./types').Callable
+ *     ? ECallable<T> & EMethods<Required<T>>
+ *     : EMethods<Required<T>>
+ * )} ECallableOrMethods
+ */
+
+/**
+ * Return a union of property names/symbols/numbers P for which the record element T[P]'s type extends U.
+ *
+ * Given const x = { a: 123, b: 'hello', c: 42, 49: () => {}, 53: 67 },
+ *
+ * FilteredKeys<typeof x, number> is the type 'a' | 'c' | 53.
+ * FilteredKeys<typeof x, string> is the type 'b'.
+ * FilteredKeys<typeof x, 42 | 67> is the type 'c' | 53.
+ * FilteredKeys<typeof x, boolean> is the type never.
+ *
+ * @template T
+ * @template U
+ * @typedef {{ [P in keyof T]: T[P] extends U ? P : never; }[keyof T]} FilteredKeys
+ */
+
+/**
+ * `PickCallable<T>` means to return a single root callable or a record type
+ * consisting only of properties that are functions.
+ *
+ * @template T
+ * @typedef {(
+ *   T extends import('./types').Callable
+ *     ? (...args: Parameters<T>) => ReturnType<T>                     // a root callable, no methods
+ *     : Pick<T, FilteredKeys<T, import('./types').Callable>>          // any callable methods
+ * )} PickCallable
+ */
+
+/**
+ * `RemoteFunctions<T>` means to return the functions and properties that are remotely callable.
+ *
+ * @template T
+ * @typedef {(
+ *   T extends import('./types').RemotableBrand<infer L, infer R>     // if a given T is some remote interface R
+ *     ? PickCallable<R>                                              // then return the callable properties of R
+ *     : Awaited<T> extends import('./types').RemotableBrand<infer L, infer R> // otherwise, if the final resolution of T is some remote interface R
+ *     ? PickCallable<R>                                              // then return the callable properties of R
+ *     : T extends PromiseLike<infer U>                               // otherwise, if T is a promise
+ *     ? Awaited<T>                                                   // then return resolved value T
+ *     : T                                                            // otherwise, return T
+ * )} RemoteFunctions
+ */
+
+/**
+ * @template T
+ * @typedef {(
+ *   T extends import('./types').RemotableBrand<infer L, infer R>
+ *     ? L
+ *     : Awaited<T> extends import('./types').RemotableBrand<infer L, infer R>
+ *     ? L
+ *     : T extends PromiseLike<infer U>
+ *     ? Awaited<T>
+ *     : T
+ * )} LocalRecord
+ */
+
+/**
+ * @template [R = unknown]
+ * @typedef {{
+ *   promise: Promise<R>;
+ *   settler: import('./types').Settler<R>;
+ * }} EPromiseKit
+ */
+
+/**
+ * Type for an object that must only be invoked with E.  It supports a given
+ * interface but declares all the functions as asyncable.
+ *
+ * @template T
+ * @typedef {(
+ *   T extends import('./types').Callable
+ *     ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>>
+ *     : T extends Record<PropertyKey, import('./types').Callable>
+ *     ? {
+ *         [K in keyof T]: T[K] extends import('./types').Callable
+ *           ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>>
+ *           : T[K];
+ *       }
+ *     : T
+ * )} EOnly
+ */

src/handled-promise.d.ts

@@ -1,4 +0,38 @@
-export function makeHandledPromise(): HandledPromiseConstructor;
-export type EHandler<T> = import('.').EHandler<T>;
-export type HandledPromiseConstructor = import('.').HandledPromiseConstructor;
+export function makeHandledPromise(): {
+    new <R>(executor: HandledExecutor<R>, unfulfilledHandler?: Handler<Promise<unknown>>): Promise<R>;
+    prototype: Promise<unknown>;
+} & PromiseConstructor & HandledPromiseStaticMethods;
+export type Handler<T> = {
+    get?(p: T, name: PropertyKey, returnedP?: Promise<unknown>): unknown;
+    getSendOnly?(p: T, name: PropertyKey): void;
+    applyFunction?(p: T, args: unknown[], returnedP?: Promise<unknown>): unknown;
+    applyFunctionSendOnly?(p: T, args: unknown[]): void;
+    applyMethod?(p: T, name: PropertyKey | undefined, args: unknown[], returnedP?: Promise<unknown>): unknown;
+    applyMethodSendOnly?(p: T, name: PropertyKey | undefined, args: unknown[]): void;
+};
+export type ResolveWithPresenceOptionsBag<T extends {}> = {
+    proxy?: {
+        handler: ProxyHandler<T>;
+        target: unknown;
+        revokerCallback?(revoker: () => void): void;
+    } | undefined;
+};
+export type HandledExecutor<R = unknown> = (resolveHandled: (value?: R) => void, rejectHandled: (reason?: unknown) => void, resolveWithPresence: (presenceHandler: Handler<{}>, options?: ResolveWithPresenceOptionsBag<{}>) => object) => void;
+export type Settler<R = unknown> = {
+    resolve(value?: R): void;
+    reject(reason: unknown): void;
+    resolveWithPresence(presenceHandler?: Handler<{}>, options?: ResolveWithPresenceOptionsBag<{}>): object;
+};
+export type HandledPromiseStaticMethods = {
+    applyFunction(target: unknown, args: unknown[]): Promise<unknown>;
+    applyFunctionSendOnly(target: unknown, args: unknown[]): void;
+    applyMethod(target: unknown, prop: PropertyKey | undefined, args: unknown[]): Promise<unknown>;
+    applyMethodSendOnly(target: unknown, prop: PropertyKey, args: unknown[]): void;
+    get(target: unknown, prop: PropertyKey): Promise<unknown>;
+    getSendOnly(target: unknown, prop: PropertyKey): void;
+};
+export type HandledPromiseConstructor = ReturnType<() => {
+    new <R>(executor: HandledExecutor<R>, unfulfilledHandler?: Handler<Promise<unknown>> | undefined): Promise<R>;
+    prototype: Promise<unknown>;
+} & PromiseConstructor & HandledPromiseStaticMethods>;
 //# sourceMappingURL=handled-promise.d.ts.map

src/handled-promise.js

 /// <reference types="ses" />
+
 import { trackTurns } from './track-turns.js';
@@ -13,9 +14,2 @@ import {
 
-/**
- * @template T
- * @typedef {import('.').EHandler<T>} EHandler
- */
-
-/** @typedef {import('.').HandledPromiseConstructor} HandledPromiseConstructor */
-
 const {
@@ -64,3 +58,2 @@ create,
  *
- * @returns {HandledPromiseConstructor} Handled promise
  */
@@ -124,3 +117,3 @@ export const makeHandledPromise = () => {
    *
-   * @type {Required<EHandler<any>>}
+   * @type {Required<Handler<any>>}
    */
@@ -132,3 +125,3 @@ let forwardingHandler;
    * @param {string} handlerName
-   * @param {EHandler<any>} handler
+   * @param {Handler<any>} handler
    * @param {string} operation
@@ -195,3 +188,3 @@ * @param {any} o
 
-    assert.fail(
+    throw assert.fail(
       X`${q(handlerName)} is defined but has no methods needed for ${q(
@@ -204,2 +197,3 @@ operation,
 
+  /** @typedef {{new <R>(executor: HandledExecutor<R>, unfulfilledHandler?: Handler<Promise<unknown>>): Promise<R>, prototype: Promise<unknown>} & PromiseConstructor & HandledPromiseStaticMethods} HandledPromiseConstructor */
   /** @type {HandledPromiseConstructor} */
@@ -212,4 +206,4 @@ let HandledPromise;
    * @template R
-   * @param {import('.').HandledExecutor<R>} executor
-   * @param {EHandler<Promise<R>>} [pendingHandler]
+   * @param {HandledExecutor<R>} executor
+   * @param {Handler<Promise<R>>} [pendingHandler]
    * @returns {Promise<R>}
@@ -408,3 +402,3 @@ */
 
-  /** @type {import('.').HandledPromiseStaticMethods & Pick<PromiseConstructor, 'resolve'>} */
+  /** @type {HandledPromiseStaticMethods & Pick<PromiseConstructor, 'resolve'>} */
   const staticMethods = {
@@ -592,3 +586,58 @@ get(target, prop) {
   }
+
   return HandledPromise;
 };
+
+/**
+ * @template T
+ * @typedef {{
+ *   get?(p: T, name: PropertyKey, returnedP?: Promise<unknown>): unknown;
+ *   getSendOnly?(p: T, name: PropertyKey): void;
+ *   applyFunction?(p: T, args: unknown[], returnedP?: Promise<unknown>): unknown;
+ *   applyFunctionSendOnly?(p: T, args: unknown[]): void;
+ *   applyMethod?(p: T, name: PropertyKey | undefined, args: unknown[], returnedP?: Promise<unknown>): unknown;
+ *   applyMethodSendOnly?(p: T, name: PropertyKey | undefined, args: unknown[]): void;
+ * }} Handler
+ */
+
+/**
+ * @template {{}} T
+ * @typedef {{
+ *   proxy?: {
+ *     handler: ProxyHandler<T>;
+ *     target: unknown;
+ *     revokerCallback?(revoker: () => void): void;
+ *   };
+ * }} ResolveWithPresenceOptionsBag
+ */
+
+/**
+ * @template [R = unknown]
+ * @typedef {(
+ *   resolveHandled: (value?: R) => void,
+ *   rejectHandled: (reason?: unknown) => void,
+ *   resolveWithPresence: (presenceHandler: Handler<{}>, options?: ResolveWithPresenceOptionsBag<{}>) => object,
+ * ) => void} HandledExecutor
+ */
+
+/**
+ * @template [R = unknown]
+ * @typedef {{
+ *   resolve(value?: R): void;
+ *   reject(reason: unknown): void;
+ *   resolveWithPresence(presenceHandler?: Handler<{}>, options?: ResolveWithPresenceOptionsBag<{}>): object;
+ * }} Settler
+ */
+
+/**
+ * @typedef {{
+ *   applyFunction(target: unknown, args: unknown[]): Promise<unknown>;
+ *   applyFunctionSendOnly(target: unknown, args: unknown[]): void;
+ *   applyMethod(target: unknown, prop: PropertyKey | undefined, args: unknown[]): Promise<unknown>;
+ *   applyMethodSendOnly(target: unknown, prop: PropertyKey, args: unknown[]): void;
+ *   get(target: unknown, prop: PropertyKey): Promise<unknown>;
+ *   getSendOnly(target: unknown, prop: PropertyKey): void;
+ * }} HandledPromiseStaticMethods
+ */
+
+/** @typedef {ReturnType<makeHandledPromise>} HandledPromiseConstructor */

src/index.d.ts

@@ -1,186 +0,28 @@
-// Type definitions for eventual-send
+import type { HandledPromiseConstructor, EProxy } from './types.d';
 
-/**
- * @file Type definitions for @agoric/eventual-send
- *
- * Some useful background knowledge:
- *
- * `Omit<T, U>` means to return a record type `T2` which has none of the properties whose keys are part of `U`.
- * `Omit<{a: 1, b: 2, c: 3}, 'b'>` is the type `{a: 1, c: 3}`.
- *
- * `Pick<T, U>` means to return a record type `T2` which has only the properties whose keys are part of `U`.
- * `Pick<{a: 1, b: 2, c: 3}, 'b'>` is the type `{b: 2}`.
- *
- * `PromiseLike<T>` is a thenable which resolves to `T`.
- *
- * `Promise<PromiseLike<T>>` doesn't handle recursion and is distinct from `T`.
- *
- * `Unpromise<PromiseLike<T>>` strips off just one layer and is just `T`.  `Unpromise<PromiseLike<PromiseLIke<T>>` is `PromiseLike<T>`.
- *
- * `Awaited<PromiseLike<T>>` recurses, and is just `T`.
- * `Awaited<PromiseLike<PromiseLike<T>>>` is just `T` as well.
- *
- * @see {@link https://www.typescriptlang.org/docs/handbook/2/generics.html#handbook-content}
- * @see {@link https://www.typescriptlang.org/docs/handbook/2/conditional-types.html}
- */
+// Package Types /////////////////////////////////////////////////////
+//
+//   Types exported to consumers.
+//
 
-export type Callable = (...args: any[]) => any;
+export type {
+  RemotableBrand,
+  DataOnly,
+  FarRef,
+  ERef,
+  EProxy,
+  EOnly,
+  RemoteFunctions,
+  LocalRecord,
+  FilteredKeys,
+  PickCallable,
+  EPromiseKit as RemoteKit,
+  ResolveWithPresenceOptionsBag,
+  HandledExecutor,
+  Settler,
+  HandledPromiseStaticMethods,
+  HandledPromiseConstructor,
+  Handler as EHandler,
+} from './types.d';
 
-// Same as https://github.com/microsoft/TypeScript/issues/31394
-export type ERef<T> = PromiseLike<T> | T;
-
-export declare const EmptyObj: {};
-
-// Type for an object that must only be invoked with E.  It supports a given
-// interface but declares all the functions as asyncable.
-export type EOnly<T> = T extends (...args: infer P) => infer R
-  ? (...args: P) => ERef<Awaited<R>> | EOnly<Awaited<R>>
-  : T extends Record<PropertyKey, Callable>
-  ? ERef<{
-      [K in keyof T]: EOnly<T[K]>;
-    }>
-  : ERef<T>;
-
-/**
- * Return a union of property names/symbols/numbers P for which the record element T[P]'s type extends U.
- *
- * Given const x = { a: 123, b: 'hello', c: 42, 49: () => {}, 53: 67 },
- *
- * FilteredKeys<typeof x, number> is the type 'a' | 'c' | 53.
- * FilteredKeys<typeof x, string> is the type 'b'.
- * FilteredKeys<typeof x, 42 | 67> is the type 'c' | 53.
- * FilteredKeys<typeof x, boolean> is the type never.
- */
-export type FilteredKeys<T, U> = {
-  [P in keyof T]: T[P] extends U ? P : never;
-}[keyof T];
-
-/**
- * `DataOnly<T>` means to return a record type `T2` consisting only of properties that are *not* functions.
- */
-export type DataOnly<T> = Omit<T, FilteredKeys<T, Callable>>;
-
-// Nominal type to carry the local and remote interfaces of a Remotable.
-export declare class RemotableBrand<L, R> {
-  // The local properties of the object.
-  private localProperties: L;
-
-  // The type of all the remotely-callable functions.
-  private remoteCallable: R;
-}
-
-/**
- * Creates a type that accepts both near and marshalled references that were
- * returned from `Remotable` or `Far`, and also promises for such references.
- */
-export type FarRef<Primary, Local = DataOnly<Primary>> = ERef<
-  Local & RemotableBrand<Local, Primary>
->;
-
-/**
- * `PickCallable<T>` means to return a single root callable or a record type
- * consisting only of properties that are functions.
- */
-export type PickCallable<T> = T extends Callable
-  ? (...args: Parameters<T>) => ReturnType<T> // a root callable, no methods
-  : Pick<T, FilteredKeys<T, Callable>>; // any callable methods
-
-/**
- * `RemoteFunctions<T>` means to return the functions and properties that are remotely callable.
- */
-export type RemoteFunctions<T> = T extends RemotableBrand<infer L, infer R> // if a given T is some remote interface R
-  ? PickCallable<R> // then use the function properties of R
-  : Awaited<T> extends RemotableBrand<infer L, infer R> // otherwise, if the final resolution of T is some remote interface R
-  ? PickCallable<R> // then use the function properties of R
-  : T extends PromiseLike<infer U>
-  ? Awaited<T> // otherwise, use the final resolution of that T
-  : T;
-
-export type LocalRecord<T> = T extends RemotableBrand<infer L, infer R>
-  ? L
-  : Awaited<T> extends RemotableBrand<infer L, infer R>
-  ? L
-  : T extends PromiseLike<infer U>
-  ? Awaited<T>
-  : T;
-export interface EHandler<T> {
-  get?: (p: T, name: PropertyKey, returnedP?: Promise<unknown>) => unknown;
-  getSendOnly?: (p: T, name: PropertyKey) => void;
-  applyFunction?: (
-    p: T,
-    args: unknown[],
-    returnedP?: Promise<unknown>,
-  ) => unknown;
-  applyFunctionSendOnly?: (p: T, args: unknown[]) => void;
-  applyMethod?: (
-    p: T,
-    name: PropertyKey | undefined,
-    args: unknown[],
-    returnedP?: Promise<unknown>,
-  ) => unknown;
-  applyMethodSendOnly?: (
-    p: T,
-    name: PropertyKey | undefined,
-    args: unknown[],
-  ) => void;
-}
-
-export type ResolveWithPresenceOptionsBag<T extends object> = {
-  proxy?: {
-    handler: ProxyHandler<T>;
-    target: unknown;
-    revokerCallback?: (revoker: () => void) => void;
-  };
-};
-
-export type HandledExecutor<R = unknown> = (
-  resolveHandled: (value?: R) => void,
-  rejectHandled: (reason?: unknown) => void,
-  resolveWithPresence: (
-    presenceHandler: EHandler<{}>,
-    options?: ResolveWithPresenceOptionsBag<{}>,
-  ) => object,
-) => void;
-
-declare interface Settler<R = unknown> {
-  resolve: (value?: R) => void;
-  reject: (reason?: unknown) => void;
-  resolveWithPresence: (
-    presenceHandler?: EHandler<{}>,
-    options?: ResolveWithPresenceOptionsBag<{}>,
-  ) => object;
-}
-
-declare interface RemoteKit<R = unknown> {
-  promise: Promise<R>;
-  settler: Settler<R>;
-}
-
-declare interface HandledPromiseStaticMethods {
-  applyFunction(target: unknown, args: unknown[]): Promise<unknown>;
-  applyFunctionSendOnly(target: unknown, args: unknown[]): void;
-  applyMethod(
-    target: unknown,
-    prop: PropertyKey | undefined,
-    args: unknown[],
-  ): Promise<unknown>;
-  applyMethodSendOnly(
-    target: unknown,
-    prop: PropertyKey,
-    args: unknown[],
-  ): void;
-  get(target: unknown, prop: PropertyKey): Promise<unknown>;
-  getSendOnly(target: unknown, prop: PropertyKey): void;
-}
-
-export interface HandledPromiseConstructor
-  extends PromiseConstructor,
-    HandledPromiseStaticMethods {
-  new <R>(
-    executor: HandledExecutor<R>,
-    unfulfilledHandler?: EHandler<Promise<unknown>>,
-  ): Promise<R>;
-  prototype: Promise<unknown>;
-}
-
 declare namespace global {
@@ -193,94 +35,2 @@ // eslint-disable-next-line vars-on-top,no-var
 
-/**
- * "E" short for "Eventual", what we call something that has to return a promise.
- */
-type ECallable<T extends Callable> = ReturnType<T> extends PromiseLike<infer U>
-  ? T // function already returns a promise
-  : (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>; // make it return a promise
-
-/* Types for E proxy calls. */
-
-/**
- * Transform each function in T to return a promise
- */
-type EMethods<T> = {
-  readonly [P in keyof T]: T[P] extends Callable ? ECallable<T[P]> : never;
-};
-
-type ECallableOrMethods<T> = T extends Callable
-  ? ECallable<T> & EMethods<Required<T>>
-  : EMethods<Required<T>>;
-
-type EGetters<T> = {
-  readonly [P in keyof T]: T[P] extends PromiseLike<infer U>
-    ? T[P]
-    : Promise<Awaited<T[P]>>;
-};
-
-/* Same types for send-only. */
-type ESendOnlyCallable<T extends Callable> = (
-  ...args: Parameters<T>
-) => Promise<void>;
-
-type ESendOnlyMethods<T> = {
-  readonly [P in keyof T]: T[P] extends Callable
-    ? ESendOnlyCallable<T[P]>
-    : never;
-};
-
-type ESendOnlyCallableOrMethods<T> = T extends Callable
-  ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
-  : ESendOnlyMethods<Required<T>>;
-
-interface ESendOnly {
-  <T>(x: T): ESendOnlyCallableOrMethods<RemoteFunctions<T>>;
-}
-
-// Generic on the proxy target {T}
-interface EProxy {
-  /**
-   * E(x) returns a proxy on which you can call arbitrary methods. Each of
-   * these method calls returns a promise. The method will be invoked on
-   * whatever 'x' designates (or resolves to) in a future turn, not this
-   * one.
-   *
-   * @param x target for method/function call
-   * @returns method/function call proxy
-   */
-  <T>(x: T): ECallableOrMethods<RemoteFunctions<T>>;
-
-  /**
-   * E.get(x) returns a proxy on which you can get arbitrary properties.
-   * Each of these properties returns a promise for the property.  The promise
-   * value will be the property fetched from whatever 'x' designates (or
-   * resolves to) in a future turn, not this one.
-   *
-   * @param x target for property get
-   * @returns property get proxy
-   */
-  readonly get: <T>(x: T) => EGetters<LocalRecord<T>>;
-
-  /**
-   * E.resolve(x) converts x to a handled promise. It is
-   * shorthand for HandledPromise.resolve(x)
-   */
-  readonly resolve: <T>(x: T) => Promise<Awaited<T>>;
-
-  /**
-   * E.when(x, res, rej) is equivalent to
-   * HandledPromise.resolve(x).then(res, rej)
-   */
-  readonly when: <T, U = Awaited<T>>(
-    x: T,
-    onfulfilled?: (value: Awaited<T>) => ERef<U>,
-    onrejected?: (reason: any) => ERef<U>,
-  ) => Promise<U>;
-
-  /**
-   * E.sendOnly returns a proxy similar to E, but for which the results
-   * are ignored (undefined is returned).
-   */
-  readonly sendOnly: ESendOnly;
-}
-
 export const E: EProxy;

src/index.test-d.ts

 /* eslint-disable @endo/no-polymorphic-call, import/no-extraneous-dependencies, no-restricted-globals */
 import { expectType } from 'tsd';
 import { E } from '../test/get-hp.js';
-import { DataOnly, ERef } from './index.js';
+import { ERef, FarRef } from './index.d';
 
-type FarRef<
-  Primary,
-  Local = DataOnly<Primary>,
-> = import('@endo/eventual-send').FarRef<Primary, Local>;
-
 // Check the legacy ERef type
@@ -12,0 +7,0 @@ const foo = async (a: ERef<{ bar(): string; baz: number }>) => {

src/no-shim.d.ts

@@ -1,4 +0,13 @@
-export const E: import("./index.js").EProxy;
+export const E: (<T>(x: T) => import("./E.js").ECallableOrMethods<import("./E.js").RemoteFunctions<T>>) & {
+    readonly get: <T_1>(x: T_1) => import("./E.js").EGetters<import("./E.js").LocalRecord<T_1>>;
+    readonly resolve: {
+        (): Promise<void>;
+        <T_2>(value: T_2): Promise<Awaited<T_2>>;
+        <T_3>(value: T_3 | PromiseLike<T_3>): Promise<Awaited<T_3>>;
+    };
+    readonly sendOnly: <T_4>(x: T_4) => import("./E.js").ESendOnlyCallableOrMethods<import("./E.js").RemoteFunctions<T_4>>;
+    readonly when: <T_5, U = T_5>(x: T_5 | PromiseLike<T_5>, onfulfilled?: ((value: T_5) => import("./E.js").ERef<U>) | undefined, onrejected?: ((reason: any) => import("./E.js").ERef<U>) | undefined) => Promise<U>;
+};
 export { hp as HandledPromise };
 declare const hp: any;
 //# sourceMappingURL=no-shim.d.ts.map

src/postponed.d.ts

@@ -1,3 +0,2 @@
-export function makePostponedHandler(HandledPromise: import('.').HandledPromiseConstructor): [Required<EHandler<any>>, () => void];
-export type EHandler<T> = import('.').EHandler<T>;
+export function makePostponedHandler(HandledPromise: import('./types').HandledPromiseConstructor): [Required<import('./types').Handler<any>>, () => void];
 //# sourceMappingURL=postponed.d.ts.map

src/postponed.js

 /// <reference types="ses" />
 
 /**
- * @template T
- * @typedef {import('.').EHandler<T>} EHandler
- */
-
-/**
  * Create a simple postponedHandler that just postpones until donePostponing is
  * called.
  *
- * @param {import('.').HandledPromiseConstructor} HandledPromise
- * @returns {[Required<EHandler<any>>, () => void]} A pair consisting of the
- * postponedHandler and donePostponing callback.
+ * @param {import('./types').HandledPromiseConstructor} HandledPromise
+ * @returns {[Required<import('./types').Handler<any>>, () => void]} postponedHandler and donePostponing callback.
  */
 export const makePostponedHandler = HandledPromise => {
+  /** @type {() => void} */
   let donePostponing;
+
   const interlockP = new Promise(resolve => {
@@ -36,3 +32,3 @@ donePostponing = () => resolve(undefined);
 
-  /** @type {Required<EHandler<any>>} */
+  /** @type {Required<import('./types').Handler<any>>} */
   const postponedHandler = {
@@ -47,4 +43,6 @@ get: makePostponedOperation('get'),
 
+  // @ts-expect-error 2454
   assert(donePostponing);
+
   return [postponedHandler, donePostponing];
 };

src/track-turns.js

 /* global globalThis */
-// @ts-nocheck
+import { makeEnvironmentCaptor } from '@endo/env-options';
 
-const { freeze } = Object;
+const { getEnvironmentOption } = makeEnvironmentCaptor(globalThis);
 
@@ -20,20 +20,14 @@ // NOTE: We can't import these because they're not in scope before lockdown.
 
-// TODO Use environment-options.js currently in ses/src after factoring it out
-// to a new package.
-const env = (globalThis.process || {}).env || {};
+const DEBUG = getEnvironmentOption('DEBUG', '');
 
 // Turn on if you seem to be losing error logging at the top of the event loop
-const VERBOSE = (env.DEBUG || '').split(':').includes('track-turns');
+const VERBOSE = DEBUG.split(':').includes('track-turns');
 
-const validOptionValues = freeze([undefined, 'enabled', 'disabled']);
-
-// Track-turns is enabled by default and can be disabled by an environment
+// Track-turns is disabled by default and can be enabled by an environment
 // option.
-const envOptionValue = env.TRACK_TURNS;
-if (!validOptionValues.includes(envOptionValue)) {
-  throw new TypeError(
-    `unrecognized TRACK_TURNS ${JSON.stringify(envOptionValue)}`,
-  );
+const TRACK_TURNS = getEnvironmentOption('TRACK_TURNS', 'disabled');
+if (TRACK_TURNS !== 'enabled' && TRACK_TURNS !== 'disabled') {
+  throw TypeError(`unrecognized TRACK_TURNS ${JSON.stringify(TRACK_TURNS)}`);
 }
-const ENABLED = (envOptionValue || 'disabled') === 'enabled';
+const ENABLED = (TRACK_TURNS || 'disabled') === 'enabled';
 
@@ -86,9 +80,2 @@ // We hoist the following functions out of trackTurns() to discourage the
 /**
- * @typedef {((...args: any[]) => any) | undefined} TurnStarterFn
- * An optional function that is not this-sensitive, expected to be called at
- * bottom of stack to start a new turn.
- */
-
-/**
- * @template {TurnStarterFn[]} T
  * Given a list of `TurnStarterFn`s, returns a list of `TurnStarterFn`s whose
@@ -104,2 +91,3 @@ * `this`-free call behaviors are not observably different to those that
  *
+ * @template {TurnStarterFn[]} T
  * @param {T} funcs
@@ -115,3 +103,3 @@ * @returns {T}
   hiddenCurrentEvent += 1;
-  const sendingError = new Error(
+  const sendingError = Error(
     `Event: ${hiddenCurrentTurn}.${hiddenCurrentEvent}`,
@@ -123,3 +111,12 @@ );
 
-  return funcs.map(func => func && wrapFunction(func, sendingError, X));
+  return /** @type {T} */ (
+    funcs.map(func => func && wrapFunction(func, sendingError, X))
+  );
 };
+
+/**
+ * An optional function that is not this-sensitive, expected to be called at
+ * bottom of stack to start a new turn.
+ *
+ * @typedef {((...args: any[]) => any) | undefined} TurnStarterFn
+ */

No alert changes

Improved metrics

Total package byte prevSize

77502

increased by22.04%

Number of package files

29

increased by3.57%

Lines of code

1497

increased by19.19%

Worsened metrics

Dependency count

1

increased byInfinity%

Dependency changes

• + Added@endo/env-options@^0.1.1

• + Added@endo/env-options@0.1.4(transitive)