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

package/src/vow-e.js

@@ -0,0 +1,101 @@
+// @ts-check
+/* global globalThis */
+import { PromiseWatcherI } from '@agoric/base-zone';
+import makeE from './E.js';
+
+/**
+ * @import {PromiseWatcher} from '@agoric/base-zone'
+ */
+
+const { Fail, bare } = assert;
+
+/**
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {object} powers
+ * @param {import('./when.js').When} powers.when
+ * @param {import('./watch.js').Watch} powers.watch
+ * @param {import('./types.js').IsRetryableReason} powers.isRetryableReason
+ */
+export const makeVowE = (zone, { when, watch, isRetryableReason }) => {
+  /** @type {import('@agoric/base-zone').PromiseWatcher} */
+  const retryRejectionPromiseWatcher = zone.exo(
+    'rejectRetriesPromiseWatcher',
+    PromiseWatcherI,
+    {
+      onFulfilled(_result) {},
+      onRejected(reason, failedOp) {
+        if (isRetryableReason(reason)) {
+          Fail`Pending ${bare(failedOp)} could not retry; ${reason}`;
+        }
+      },
+    },
+  );
+
+  /**
+   * @param {unknown} specimenP
+   * @param {string} opDescription
+   * @param {import('./E.js').EOptions} [opts]
+   * @returns {Promise<any>}
+   */
+  const unwrap = (specimenP, opDescription, opts = {}) => {
+    const { watch: optWatch = false } = opts;
+
+    // Watch the specimen in case it is an ephemeral promise.
+    /** @type {Promise<any>} */
+    let promise;
+
+    if (optWatch) {
+      /** @type {import('./types.js').Vow<any>} */
+      let vow;
+      if (Array.isArray(optWatch)) {
+        // Arguments for the watch.
+        vow = watch(specimenP, ...optWatch);
+      } else if (
+        Object(optWatch) === optWatch &&
+        typeof optWatch === 'object'
+      ) {
+        // Just a watcher.
+        vow = watch(specimenP, optWatch);
+      } else {
+        vow = watch(specimenP);
+      }
+
+      // Make a prompt ephemeral promise for a (potentially durable) vow.
+      promise = HandledPromise.resolve(vow);
+    } else {
+      // Resolve to an non-prompt ephemeral promise.
+      promise = when(specimenP);
+    }
+
+    // Watch the ephemeral result promise to ensure that if its settlement is
+    // lost due to upgrade of this incarnation, we will at least cause an
+    // unhandled rejection in the new incarnation.
+    zone.watchPromise(
+      harden(promise),
+      retryRejectionPromiseWatcher,
+      opDescription,
+    );
+
+    return promise;
+  };
+
+  /**
+   * A convenient vow-shortening E, which returns platform result promises.  It
+   * can cause problems when used in a durable context, because the resulting
+   * promises are ephemeral and likely not promptly resolved.
+   *
+   * Instead of this `vowE`, when manipulating durable vows, use
+   * `vowTools.watch` prepared in a durable zone with the standard,
+   * non-unwrapping `import('@endo/far').E`.  This avoids the creation of
+   * promise/vow chains containing non-prompt ephemeral promises.
+   */
+  const vowE = makeE(globalThis.HandledPromise, {
+    unwrap,
+    additional: {
+      when,
+      watch,
+    },
+  });
+
+  return vowE;
+};

package/src/vow-utils.d.ts

@@ -0,0 +1,20 @@
+export { basicE };
+/**
+ * The least possibly restrictive guard for a `watch` watcher's `onFulfilled` or
+ * `onRejected` reaction
+ */
+export const ReactionGuard: import("@endo/patterns").MethodGuard;
+export const VowShape: import("@endo/patterns").Matcher;
+export function OrVow$(shape: any): import("@endo/patterns").Matcher;
+export function EVow$(shape: any): import("@endo/patterns").Matcher;
+export function isVow(specimen: unknown): specimen is Vow;
+export function getVowPayload<T>(specimen: any): VowPayload<T> | undefined;
+export function toPassableCap(k: PassableCap | Vow): PassableCap;
+export function makeAsVow(makeVowKit: MakeVowKit): <T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> | Awaited<T> | PromiseVow<T>) => Vow<Awaited<T>>;
+import { E as basicE } from '@endo/eventual-send';
+import type { Vow } from './types.js';
+import type { VowPayload } from './types.js';
+import type { PassableCap } from '@endo/pass-style';
+import type { MakeVowKit } from './vow.js';
+import type { PromiseVow } from './types.js';
+//# sourceMappingURL=vow-utils.d.ts.map

package/src/vow-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vow-utils.d.ts","sourceRoot":"","sources":["vow-utils.js"],"names":[],"mappings":";AAaA;;;GAGG;AACH,iEAAgF;AAEhF,wDAKE;AAEK,qEAA6C;AAC7C,oEAAkE;AAMlE,gCAHI,OAAO,GACL,QAAQ,IAAI,GAAG,CAGyB;AAc9C,8BAJM,CAAC,YACH,GAAG,GACD,WAAW,CAAC,CAAC,GAAG,SAAS,CASrC;AAoBM,iCAHI,WAAW,GAAG,GAAG,GACf,WAAW,CAUvB;AAIM,sCADK,UAAU,IAKD,CAAC,sBACT,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,KAC9D,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAiB7B;4BA7G2B,qBAAqB;yBAMH,YAAY;gCAAZ,YAAY;iCAD5B,kBAAkB;gCAEnB,UAAU;gCADO,YAAY"}

package/src/vow-utils.js

@@ -0,0 +1,112 @@
+// @ts-check
+import { E as basicE } from '@endo/eventual-send';
+import { isPassable } from '@endo/pass-style';
+import { M, matches } from '@endo/patterns';
+
+/**
+ * @import {PassableCap} from '@endo/pass-style';
+ * @import {VowPayload, Vow, PromiseVow} from './types.js';
+ * @import {MakeVowKit} from './vow.js';
+ */
+
+export { basicE };
+
+/**
+ * The least possibly restrictive guard for a `watch` watcher's `onFulfilled` or
+ * `onRejected` reaction
+ */
+export const ReactionGuard = M.call(M.any()).optional(M.any()).returns(M.any());
+
+export const VowShape = M.tagged(
+  'Vow',
+  M.splitRecord({
+    vowV0: M.remotable('VowV0'),
+  }),
+);
+
+export const OrVow$ = shape => M.or(shape, VowShape);
+export const EVow$ = shape => M.or(OrVow$(shape), M.promise(/* shape */));
+
+/**
+ * @param {unknown} specimen
+ * @returns {specimen is Vow}
+ */
+export const isVow = specimen =>
+  isPassable(specimen) && matches(specimen, VowShape);
+harden(isVow);
+
+/**
+ * A vow is a passable tagged as 'Vow'.  Its payload is a record with
+ * API-versioned remotables.  payload.vowV0 is the API for the `watch` and
+ * `when` operators to use for retriable shortening of the vow chain.
+ *
+ * If the specimen is a Vow, return its payload, otherwise undefined.
+ *
+ * @template T
+ * @param {any} specimen any value to verify as a vow
+ * @returns {VowPayload<T> | undefined} undefined if specimen is not a vow, otherwise the vow's payload.
+ */
+export const getVowPayload = specimen => {
+  if (!isVow(specimen)) {
+    return undefined;
+  }
+
+  const vow = /** @type {Vow<T>} */ (/** @type {unknown} */ (specimen));
+  return vow.payload;
+};
+harden(getVowPayload);
+
+/**
+ * For when you have a Vow or a `PassableCap` (`RemotableObject` or
+ * passable `Promise`) and you need `PassableCap`,
+ * typically to serve as a key in a `Map`, `WeakMap`, `Store`, or `WeakStore`.
+ *
+ * Relies on, and encapsulates, the current "V0" representation of a vow
+ * as containing a unique remotable shortener.
+ *
+ * Note: if `k` is not a `Vow`, `toPassableCap` does no enforcement that `k`
+ * is already a `PassableCap`. Rather, it just acts as an identity function
+ * returning `k` without further checking. The types only describe the
+ * intended use. (If warranted, we may later add such enforcement, so please
+ * do not rely on either the presence or absence of such enforcement.)
+ *
+ * @param {PassableCap | Vow} k
+ * @returns {PassableCap}
+ */
+export const toPassableCap = k => {
+  const payload = getVowPayload(k);
+  if (payload === undefined) {
+    return /** @type {PassableCap} */ (k);
+  }
+  const { vowV0 } = payload;
+  // vowMap.set(vowV0, h);
+  return vowV0;
+};
+harden(toPassableCap);
+
+/** @param {MakeVowKit} makeVowKit */
+export const makeAsVow = makeVowKit => {
+  /**
+   * Helper function that coerces the result of a function to a Vow. Helpful
+   * for scenarios like a synchronously thrown error.
+   * @template {any} T
+   * @param {(...args: any[]) => Vow<Awaited<T>> | Awaited<T> | PromiseVow<T>} fn
+   * @returns {Vow<Awaited<T>>}
+   */
+  const asVow = fn => {
+    let result;
+    try {
+      result = fn();
+    } catch (e) {
+      result = Promise.reject(e);
+    }
+    if (isVow(result)) {
+      return result;
+    }
+    const kit = makeVowKit();
+    kit.resolver.resolve(result);
+    return kit.vow;
+  };
+  return harden(asVow);
+};
+harden(makeAsVow);

package/src/vow.d.ts

@@ -0,0 +1,7 @@
+export function prepareVowKit(zone: Zone): <T>() => VowKit<T>;
+export type VowEphemera = Partial<PromiseKit<any>> & Pick<PromiseKit<any>, "promise">;
+export type MakeVowKit = ReturnType<typeof prepareVowKit>;
+import type { Zone } from '@agoric/base-zone';
+import type { VowKit } from './types.js';
+import type { PromiseKit } from '@endo/promise-kit';
+//# sourceMappingURL=vow.d.ts.map

package/src/vow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vow.d.ts","sourceRoot":"","sources":["vow.js"],"names":[],"mappings":"AA0BO,oCAFI,IAAI,IAkLA,CAAC,OACD,OAAO,CAAC,CAAC,CASvB;0BAjMY,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC,GACpC,IAAQ,CAAC,WAAW,GAAG,CAAC,EAAE,SAAS,CAAC;yBAiMvB,UAAU,CAAC,OAAO,aAAa,CAAC;0BA3MvB,mBAAmB;4BAEJ,YAAY;gCAHrB,mBAAmB"}

package/src/vow.js

@@ -0,0 +1,216 @@
+// @ts-check
+import { makePromiseKit } from '@endo/promise-kit';
+import { M } from '@endo/patterns';
+import { makeTagged } from '@endo/pass-style';
+import { PromiseWatcherI } from '@agoric/base-zone';
+
+const { details: X } = assert;
+
+/**
+ * @import {PromiseKit} from '@endo/promise-kit';
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {MapStore} from '@agoric/store';
+ * @import {VowResolver, VowKit} from './types.js';
+ */
+
+const sink = () => {};
+harden(sink);
+
+/**
+ * @typedef {Partial<PromiseKit<any>> &
+ *   Pick<PromiseKit<any>, 'promise'>} VowEphemera
+ */
+
+/**
+ * @param {Zone} zone
+ */
+export const prepareVowKit = zone => {
+  /** @type {WeakMap<VowResolver, VowEphemera>} */
+  const resolverToEphemera = new WeakMap();
+
+  /** @type {WeakMap<VowResolver, any>} */
+  const resolverToNonStoredValue = new WeakMap();
+
+  /**
+   * Get the current incarnation's promise kit associated with a vowV0.
+   *
+   * @param {VowResolver} resolver
+   */
+  const provideCurrentKit = resolver => {
+    let pk = resolverToEphemera.get(resolver);
+    if (pk) {
+      return pk;
+    }
+
+    pk = makePromiseKit();
+    pk.promise.catch(sink); // silence unhandled rejection
+    resolverToEphemera.set(resolver, pk);
+    return pk;
+  };
+
+  /**
+   * @param {VowResolver} resolver
+   */
+  const getPromiseKitForResolution = resolver => {
+    const kit = provideCurrentKit(resolver);
+    if (kit.resolve) {
+      // Resolution is a one-time event, so forget the resolve/reject functions.
+      resolverToEphemera.set(resolver, harden({ promise: kit.promise }));
+    }
+    return kit;
+  };
+
+  const makeVowInternalsKit = zone.exoClassKit(
+    'VowInternalsKit',
+    {
+      vowV0: M.interface('VowV0', {
+        shorten: M.call().returns(M.promise()),
+      }),
+      resolver: M.interface('VowResolver', {
+        resolve: M.call().optional(M.raw()).returns(),
+        reject: M.call().optional(M.raw()).returns(),
+      }),
+      watchNextStep: PromiseWatcherI,
+    },
+    () => ({
+      value: /** @type {any} */ (undefined),
+      // The stepStatus is null if the promise step hasn't settled yet.
+      stepStatus: /** @type {null | 'pending' | 'fulfilled' | 'rejected'} */ (
+        null
+      ),
+      isStoredValue: /** @type {boolean} */ (false),
+      /**
+       * Map for future properties that aren't in the schema.
+       * UNTIL https://github.com/Agoric/agoric-sdk/issues/7407
+       * @type {MapStore<any, any> | undefined}
+       */
+      extra: undefined,
+    }),
+    {
+      vowV0: {
+        /**
+         * @returns {Promise<any>}
+         */
+        async shorten() {
+          const { stepStatus, isStoredValue, value } = this.state;
+          const { resolver } = this.facets;
+
+          switch (stepStatus) {
+            case 'fulfilled': {
+              if (isStoredValue) {
+                // Always return a stored fulfilled value.
+                return value;
+              } else if (resolverToNonStoredValue.has(resolver)) {
+                // Non-stored value is available.
+                return resolverToNonStoredValue.get(resolver);
+              }
+              // We can't recover the non-stored value, so throw the
+              // explanation.
+              throw value;
+            }
+            case 'rejected': {
+              if (!isStoredValue && resolverToNonStoredValue.has(resolver)) {
+                // Non-stored reason is available.
+                throw resolverToNonStoredValue.get(resolver);
+              }
+              // Always throw a stored rejection reason.
+              throw value;
+            }
+            case null:
+            case 'pending':
+              return provideCurrentKit(this.facets.resolver).promise;
+            default:
+              throw new TypeError(`unexpected stepStatus ${stepStatus}`);
+          }
+        },
+      },
+      resolver: {
+        /**
+         * @param {any} [value]
+         */
+        resolve(value) {
+          const { resolver } = this.facets;
+          const { stepStatus } = this.state;
+          const { resolve } = getPromiseKitForResolution(resolver);
+          if (resolve) {
+            resolve(value);
+          }
+          if (stepStatus === null) {
+            this.state.stepStatus = 'pending';
+            zone.watchPromise(
+              HandledPromise.resolve(value),
+              this.facets.watchNextStep,
+            );
+          }
+        },
+        /**
+         * @param {any} [reason]
+         */
+        reject(reason) {
+          const { resolver, watchNextStep } = this.facets;
+          const { stepStatus } = this.state;
+          const { reject } = getPromiseKitForResolution(resolver);
+          if (reject) {
+            reject(reason);
+          }
+          if (stepStatus === null) {
+            watchNextStep.onRejected(reason);
+          }
+        },
+      },
+      watchNextStep: {
+        onFulfilled(value) {
+          const { resolver } = this.facets;
+          const { resolve } = getPromiseKitForResolution(resolver);
+          harden(value);
+          if (resolve) {
+            resolve(value);
+          }
+          this.state.stepStatus = 'fulfilled';
+          this.state.isStoredValue = zone.isStorable(value);
+          if (this.state.isStoredValue) {
+            this.state.value = value;
+          } else {
+            resolverToNonStoredValue.set(resolver, value);
+            this.state.value = assert.error(
+              X`Vow fulfillment value was not stored: ${value}`,
+            );
+          }
+        },
+        onRejected(reason) {
+          const { resolver } = this.facets;
+          const { reject } = getPromiseKitForResolution(resolver);
+          harden(reason);
+          if (reject) {
+            reject(reason);
+          }
+          this.state.stepStatus = 'rejected';
+          this.state.isStoredValue = zone.isStorable(reason);
+          if (this.state.isStoredValue) {
+            this.state.value = reason;
+          } else {
+            resolverToNonStoredValue.set(resolver, reason);
+            this.state.value = assert.error(
+              X`Vow rejection reason was not stored: ${reason}`,
+            );
+          }
+        },
+      },
+    },
+  );
+
+  /**
+   * @template T
+   * @returns {VowKit<T>}
+   */
+  const makeVowKit = () => {
+    const { resolver, vowV0 } = makeVowInternalsKit();
+    const vow = makeTagged('Vow', harden({ vowV0 }));
+    return harden({ resolver, vow });
+  };
+
+  return makeVowKit;
+};
+/** @typedef {ReturnType<typeof prepareVowKit>} MakeVowKit */
+
+harden(prepareVowKit);

package/src/watch-utils.d.ts

@@ -0,0 +1,20 @@
+export function prepareWatchUtils(zone: Zone, { watch, when, makeVowKit, isRetryableReason }: {
+    watch: Watch;
+    when: When;
+    makeVowKit: () => VowKit<any>;
+    isRetryableReason: IsRetryableReason;
+}): () => import("@endo/exo").Guarded<{
+    /**
+     * @param {EVow<unknown>[]} vows
+     */
+    all(vows: EVow<unknown>[]): import("./types.js").Vow<any[]>;
+    /** @type {AsPromiseFunction} */
+    asPromise(specimenP: any, watcher: import("./types.js").Watcher<any, any, never, any[]> | undefined, watcherArgs: any[] | undefined): Promise<any | never>;
+}>;
+import type { Zone } from '@agoric/base-zone';
+import type { Watch } from './watch.js';
+import type { When } from './when.js';
+import type { VowKit } from './types.js';
+import type { IsRetryableReason } from './types.js';
+import type { EVow } from './types.js';
+//# sourceMappingURL=watch-utils.d.ts.map

package/src/watch-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-utils.d.ts","sourceRoot":"","sources":["watch-utils.js"],"names":[],"mappings":"AA4CO,wCAPI,IAAI,kDAEZ;IAAsB,KAAK,EAAnB,KAAK;IACQ,IAAI,EAAjB,IAAI;IACsB,UAAU,EAApC,MAAM,OAAO,GAAG,CAAC;IACS,iBAAiB,EAA3C,iBAAiB;CAC3B;IAsCO;;OAEG;cADQ,KAAK,OAAO,CAAC,EAAE;IAuC1B,gCAAgC;;GAgGvC;0BAhNsB,mBAAmB;2BAClB,YAAY;0BACb,WAAW;4BACmC,YAAY;uCAAZ,YAAY;0BAAZ,YAAY"}