@agoric/vow 0.1.1-calypso-dev-84eb287.0

package/src/E.js

@@ -0,0 +1,484 @@
+// @ts-check
+/**
+ * @file provides a `makeE` that can be parameterized with an `unwrap` function
+ * and corresponding `import('./types').EUnwrap<T>`.  These will be used to
+ * extract the final settlement from a chain of PromiseLikes and PromiseSteps or
+ * similar non-thenable pseudo-promises.
+ *
+ * `@agoric/vow/vat.js` uses this mechanism to export a `V` function with
+ * similar behaviour as the default `E`, augmented with automatic unwrapping of
+ * recipient Vows as if they were PromiseLikes.
+ */
+
+/*
+ * TODO: Once this implementation has been polished and well-tested, it is
+ * designed to be a drop-in replacement for the version in
+ * `@endo/eventual-send/src/E.js` which contained no concept of "unwrap",
+ */
+import { trackTurns } from './track-turns.js';
+import { makeMessageBreakpointTester } from './message-breakpoints.js';
+
+const { details: X, quote: q, Fail } = assert;
+const { assign, create } = Object;
+
+const onSend = makeMessageBreakpointTester('ENDO_SEND_BREAKPOINTS');
+
+/**
+ * @import { HandledPromiseConstructor, RemotableBrand } from '@endo/eventual-send'
+ * @import { EUnwrap, EUnwrapOptions } from './types.js'
+ */
+/** @typedef {(...args: unknown[]) => any} Callable */
+
+/** @type {ProxyHandler<any>} */
+const baseFreezableProxyHandler = {
+  set(_target, _prop, _value) {
+    return false;
+  },
+  isExtensible(_target) {
+    return false;
+  },
+  setPrototypeOf(_target, _value) {
+    return false;
+  },
+  deleteProperty(_target, _prop) {
+    return false;
+  },
+};
+
+// E Proxy handlers pretend that any property exists on the target and returns
+// a function for their value. While this function is "bound" by context, it is
+// meant to be called as a method. For that reason, the returned function
+// includes a check that the `this` argument corresponds to the initial
+// receiver when the function was retrieved.
+// E Proxy handlers also forward direct calls to the target in case the remote
+// is a function instead of an object. No such receiver checks are necessary in
+// that case.
+
+/**
+ * A Proxy handler for E(x).
+ *
+ * @param {any} recipient Any value passed to E(x)
+ * @param {HandledPromiseConstructor} HandledPromise
+ * @param {Unwrapper} unwrap
+ * @param {EOptions} [opts]
+ * @returns {ProxyHandler<any>} the Proxy handler
+ */
+const makeEProxyHandler = (recipient, HandledPromise, unwrap, opts) =>
+  harden({
+    ...baseFreezableProxyHandler,
+    get: (_target, propertyKey, receiver) => {
+      return harden(
+        {
+          /**
+           * This function purposely checks the `this` value (see above)
+           * In order to be `this` sensitive it is defined using concise method
+           * syntax rather than as an arrow function. To ensure the function
+           * is not constructable, it also avoids the `function` syntax.
+           * @param  {...any[]} args
+           */
+          [propertyKey](...args) {
+            if (this !== receiver) {
+              // Reject the async function call
+              return HandledPromise.reject(
+                assert.error(
+                  X`Unexpected receiver for "${q(propertyKey)}" method of E(${q(
+                    recipient,
+                  )})`,
+                ),
+              );
+            }
+
+            if (onSend && onSend.shouldBreakpoint(recipient, propertyKey)) {
+              // eslint-disable-next-line no-debugger
+              debugger; // LOOK UP THE STACK
+              // Stopped at a breakpoint on eventual-send of a method-call message,
+              // so that you can walk back on the stack to see how we came to
+              // make this eventual-send
+            }
+            return unwrap(
+              HandledPromise.applyMethod(
+                unwrap(recipient, 'method recipient'),
+                propertyKey,
+                args,
+              ),
+              'method result',
+              opts,
+            );
+          },
+          // @ts-expect-error https://github.com/microsoft/TypeScript/issues/50319
+        }[propertyKey],
+      );
+    },
+    apply: (_target, _thisArg, argArray = []) => {
+      if (onSend && onSend.shouldBreakpoint(recipient, undefined)) {
+        // eslint-disable-next-line no-debugger
+        debugger; // LOOK UP THE STACK
+        // Stopped at a breakpoint on eventual-send of a function-call message,
+        // so that you can walk back on the stack to see how we came to
+        // make this eventual-send
+      }
+      return unwrap(
+        HandledPromise.applyFunction(
+          unwrap(recipient, 'function recipient'),
+          argArray,
+        ),
+        'function result',
+      );
+    },
+    has: (_target, _p) => {
+      // We just pretend everything exists.
+      return true;
+    },
+  });
+
+/**
+ * A Proxy handler for E.sendOnly(x)
+ * It is a variant on the E(x) Proxy handler.
+ *
+ * @param {any} recipient Any value passed to E.sendOnly(x)
+ * @param {HandledPromiseConstructor} HandledPromise
+ * @param {Unwrapper} unwrap
+ * @param {EOptions} [opts]
+ * @returns {ProxyHandler<any>} the Proxy handler
+ */
+const makeESendOnlyProxyHandler = (recipient, HandledPromise, unwrap, opts) =>
+  harden({
+    ...baseFreezableProxyHandler,
+    get: (_target, propertyKey, receiver) => {
+      return harden(
+        {
+          /**
+           * This function purposely checks the `this` value (see above)
+           * In order to be `this` sensitive it is defined using concise method
+           * syntax rather than as an arrow function. To ensure the function
+           * is not constructable, it also avoids the `function` syntax.
+           * @param  {...any[]} args
+           */
+          [propertyKey](...args) {
+            // Throw since the function returns nothing
+            this === receiver ||
+              Fail`Unexpected receiver for "${q(
+                propertyKey,
+              )}" method of E.sendOnly(${q(recipient)})`;
+            if (onSend && onSend.shouldBreakpoint(recipient, propertyKey)) {
+              // eslint-disable-next-line no-debugger
+              debugger; // LOOK UP THE STACK
+              // Stopped at a breakpoint on eventual-send of a method-call message,
+              // so that you can walk back on the stack to see how we came to
+              // make this eventual-send
+            }
+            HandledPromise.applyMethodSendOnly(
+              unwrap(recipient, 'send-only method recipient', opts),
+              propertyKey,
+              args,
+            );
+            return unwrap(undefined, 'send-only method return', opts);
+          },
+          // @ts-expect-error https://github.com/microsoft/TypeScript/issues/50319
+        }[propertyKey],
+      );
+    },
+    apply: (_target, _thisArg, argsArray = []) => {
+      if (onSend && onSend.shouldBreakpoint(recipient, undefined)) {
+        // eslint-disable-next-line no-debugger
+        debugger; // LOOK UP THE STACK
+        // Stopped at a breakpoint on eventual-send of a function-call message,
+        // so that you can walk back on the stack to see how we came to
+        // make this eventual-send
+      }
+      HandledPromise.applyFunctionSendOnly(
+        unwrap(recipient, 'send-only function recipient'),
+        argsArray,
+      );
+      return undefined;
+    },
+    has: (_target, _p) => {
+      // We just pretend that everything exists.
+      return true;
+    },
+  });
+
+/**
+ * A Proxy handler for E.get(x)
+ * It is a variant on the E(x) Proxy handler.
+ *
+ * @param {any} x Any value passed to E.get(x)
+ * @param {HandledPromiseConstructor} HandledPromise
+ * @param {Unwrapper} unwrap
+ * @param {EOptions} [opts]
+ * @returns {ProxyHandler<any>} the Proxy handler
+ */
+const makeEGetProxyHandler = (x, HandledPromise, unwrap, opts) =>
+  harden({
+    ...baseFreezableProxyHandler,
+    has: (_target, _prop) => true,
+    get: (_target, prop) =>
+      unwrap(
+        HandledPromise.get(unwrap(x, 'get target'), prop),
+        'get result',
+        opts,
+      ),
+  });
+
+/** @param {any} x */
+const resolve = x => HandledPromise.resolve(x);
+
+/**
+ * @template [A={}]
+ * @param {HandledPromiseConstructor} HandledPromise
+ * @param {object} [powers]
+ * @param {Unwrapper} [powers.unwrap]
+ * @param {A} [powers.additional]
+ */
+const makeE = (HandledPromise, powers = {}) => {
+  const {
+    additional = /** @type {A} */ ({}),
+    unwrap = /** @type {NonNullable<typeof powers.unwrap>} */ (resolve),
+  } = powers;
+
+  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
+       * @param {EOptions} [opts]
+       * @returns {ECallableOrMethods<RemoteFunctions<T>>} method/function call proxy
+       */
+      (x, opts) =>
+        harden(
+          new Proxy(
+            () => {},
+            makeEProxyHandler(x, HandledPromise, unwrap, opts),
+          ),
+        ),
+      {
+        /**
+         * 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
+         * @param {EOptions} [opts]
+         * @returns {EGetters<LocalRecord<T>>} property get proxy
+         * @readonly
+         */
+        get: (x, opts) =>
+          harden(
+            new Proxy(
+              create(null),
+              makeEGetProxyHandler(x, HandledPromise, unwrap, opts),
+            ),
+          ),
+
+        /**
+         * 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
+         * @param {EOptions} [opts]
+         * @returns {Promise<Awaited<T>>} handled promise for x
+         * @readonly
+         */
+        resolve: (x, opts) => resolve(unwrap(x, 'resolve', opts)),
+
+        /**
+         * 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
+         * @param {EOptions} [opts]
+         * @returns {ESendOnlyCallableOrMethods<RemoteFunctions<T>>} method/function call proxy
+         * @readonly
+         */
+        sendOnly: (x, opts) =>
+          harden(
+            new Proxy(
+              () => {},
+              makeESendOnlyProxyHandler(x, HandledPromise, unwrap, opts),
+            ),
+          ),
+
+        /**
+         * E.when(x, res, rej) is equivalent to
+         * unwrap(x).then(onfulfilled, onrejected)
+         *
+         * @template T
+         * @template [TResult1=EUnwrap<T>]
+         * @template [TResult2=never]
+         * @param {ERef<T>} x value to convert to a handled promise
+         * @param {(value: EUnwrap<T>) => ERef<TResult1>} [onfulfilled]
+         * @param {(reason: any) => ERef<TResult2>} [onrejected]
+         * @param {EOptions} [opts]
+         * @returns {Promise<TResult1 | TResult2>}
+         * @readonly
+         */
+        when: (x, onfulfilled, onrejected, opts) => {
+          const unwrapped = resolve(unwrap(x, 'E.when', opts));
+          if (onfulfilled == null && onrejected == null) {
+            return unwrapped;
+          }
+          return unwrapped.then(
+            ...trackTurns(/** @type {const} */ ([onfulfilled, onrejected])),
+          );
+        },
+      },
+      additional,
+    ),
+  );
+};
+
+export default makeE;
+
+/** @typedef {ReturnType<makeE>} EProxy */
+
+/**
+ * `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, Callable>>} DataOnly
+ */
+
+/**
+ * @see {@link https://github.com/microsoft/TypeScript/issues/31394}
+ * @template T
+ * @typedef {PromiseLike<T> | T} ERef
+ */
+
+/**
+ * @template {Callable} T
+ * @typedef {ReturnType<T> extends EUnwrap<ReturnType<T>>
+ *     ? (...args: Parameters<T>) => Promise<ReturnType<T>>
+ *     : ReturnType<T> extends Promise<EUnwrap<ReturnType<T>>>
+ *       ? T
+ *       : (...args: Parameters<T>) => Promise<EUnwrap<ReturnType<T>>>} ECallable
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ *   readonly [P in keyof T]: T[P] extends Callable
+ *     ? ECallable<T[P]>
+ *     : never;
+ * }} EMethods
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ *   readonly [P in keyof T]: T[P] extends PromiseLike<any>
+ *     ? T[P]
+ *     : Promise<Awaited<T[P]>>;
+ * }} EGetters
+ */
+
+/**
+ * @template {Callable} T
+ * @typedef {(...args: Parameters<T>) => Promise<void>} ESendOnlyCallable
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ *   readonly [P in keyof T]: T[P] extends Callable
+ *     ? ESendOnlyCallable<T[P]>
+ *     : never;
+ * }} ESendOnlyMethods
+ */
+
+/**
+ * @template T
+ * @typedef {(
+ *   T extends Callable
+ *     ? ESendOnlyCallable<T> & ESendOnlyMethods<Required<T>>
+ *     : ESendOnlyMethods<Required<T>>
+ * )} ESendOnlyCallableOrMethods
+ */
+
+/**
+ * @template T
+ * @typedef {(
+ *   T extends 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 Callable
+ *     ? (...args: Parameters<T>) => ReturnType<T>   // a root callable, no methods
+ *     : FilteredKeys<T, Callable> extends never
+ *     ? any
+ *     : Pick<T, FilteredKeys<T, Callable>>          // any callable methods
+ * )} PickCallable
+ */
+
+/**
+ * `RemoteFunctions<T>` means to return the functions and properties that are remotely callable.
+ *
+ * @template T
+ * @typedef {(
+ *   EUnwrap<T> extends RemotableBrand<any, infer R>  // if a given T will settle to some remote interface R
+ *     ? PickCallable<R>                         // then return the callable properties of R
+ *     : PickCallable<EUnwrap<T>>                 // otherwise return the callable properties of the settled T
+ * )} RemoteFunctions
+ */
+
+/**
+ * @template T
+ * @typedef {(
+ *   T extends RemotableBrand<infer L, any>
+ *     ? L
+ *     : EUnwrap<T>
+ * )} LocalRecord
+ */
+
+/**
+ * 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 Callable
+ *     ? (...args: Parameters<T>) => ERef<Awaited<EOnly<ReturnType<T>>>>
+ *     : T extends Record<PropertyKey, Callable>
+ *     ? {
+ *         [K in keyof T]: T[K] extends Callable
+ *           ? (...args: Parameters<T[K]>) => ERef<Awaited<EOnly<ReturnType<T[K]>>>>
+ *           : T[K];
+ *       }
+ *     : T
+ * )} EOnly
+ */
+
+/** @typedef {<T>(x: T, retryContext?: string, opts?: EOptions) => Promise<EUnwrap<T>>} Unwrapper */
+
+/** @typedef {EUnwrapOptions} EOptions */

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./tools.js";
+export * from "./types.js";
+export * from "@agoric/internal/src/types.js";
+export { default as makeE } from "./E.js";
+export { ReactionGuard, VowShape, EVow$, OrVow$, toPassableCap } from "./vow-utils.js";
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}

package/src/index.js

@@ -0,0 +1,16 @@
+// @ts-check
+export * from './tools.js';
+export { default as makeE } from './E.js';
+export {
+  ReactionGuard,
+  VowShape,
+  EVow$,
+  OrVow$,
+  toPassableCap,
+} from './vow-utils.js';
+
+// eslint-disable-next-line import/export
+export * from './types.js';
+
+// XXX re-exporting the Remote type for back-compat
+export * from '@agoric/internal/src/types.js';

package/src/message-breakpoints.d.ts

@@ -0,0 +1,44 @@
+export function makeMessageBreakpointTester(optionName: string): MessageBreakpointTester | undefined;
+/**
+ * A star `'*'` matches any recipient. Otherwise, the string is
+ * matched against the value of a recipient's `@@toStringTag`
+ * after stripping out any leading `'Alleged: '` or `'DebugName: '`
+ * prefix. For objects defined with `Far` this is the first argument,
+ * known as the `farName`. For exos, this is the tag.
+ */
+export type MatchStringTag = string | "*";
+/**
+ * A star `'*'` matches any method name. Otherwise, the string is
+ * matched against the method name. Currently, this is only an exact match.
+ * However, beware that we may introduce a string syntax for
+ * symbol method names.
+ */
+export type MatchMethodName = string | "*";
+/**
+ * A star `'*'` will always breakpoint. Otherwise, the string
+ * must be a non-negative integer. Once that is zero, always breakpoint.
+ * Otherwise decrement by one each time it matches until it reaches zero.
+ * In other words, the countdown represents the number of
+ * breakpoint occurrences to skip before actually breakpointing.
+ */
+export type MatchCountdown = number | "*";
+/**
+ * This is the external JSON representation, in which
+ * - the outer property name is the class-like tag or '*',
+ * - the inner property name is the method name or '*',
+ * - the value is a non-negative integer countdown or '*'.
+ */
+export type MessageBreakpoints = Record<MatchStringTag, Record<MatchMethodName, MatchCountdown>>;
+/**
+ * This is the internal JSON representation, in which
+ * - the outer property name is the method name or '*',
+ * - the inner property name is the class-like tag or '*',
+ * - the value is a non-negative integer countdown or '*'.
+ */
+export type BreakpointTable = Record<MatchMethodName, Record<MatchStringTag, MatchCountdown>>;
+export type MessageBreakpointTester = {
+    getBreakpoints: () => MessageBreakpoints;
+    setBreakpoints: (newBreakpoints?: MessageBreakpoints) => void;
+    shouldBreakpoint: (recipient: object, methodName: string | symbol | undefined) => boolean;
+};
+//# sourceMappingURL=message-breakpoints.d.ts.map

package/src/message-breakpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-breakpoints.d.ts","sourceRoot":"","sources":["message-breakpoints.js"],"names":[],"mappings":"AA0FO,wDAHI,MAAM,GACJ,uBAAuB,GAAG,SAAS,CA0F/C;;;;;;;;6BA1KY,MAAM,GAAG,GAAG;;;;;;;8BAQZ,MAAM,GAAG,GAAG;;;;;;;;6BAOZ,MAAM,GAAG,GAAG;;;;;;;iCAcZ,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC;;;;;;;8BAS/D,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;;oBAK9D,MAAM,kBAAkB;oBACxB,CAAC,cAAc,CAAC,EAAE,kBAAkB,KAAK,IAAI;sBAC7C,CACb,SAAa,EAAE,MAAM,EACrB,UAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,KACpC,OAAO"}