@agoric/vow 0.1.1-dev-c5284e4.0

package/src/watch.js

@@ -0,0 +1,163 @@
+// @ts-check
+import { getVowPayload, basicE } from './vow-utils.js';
+import { PromiseWatcherI, watchPromiseShim } from './watch-promise.js';
+
+const { apply } = Reflect;
+
+/**
+ * @param {typeof watchPromiseShim} watchPromise
+ */
+const makeWatchNextStep =
+  watchPromise =>
+  /**
+   * If the specimen is a vow, obtain a fresh shortened promise from it,
+   * otherwise coerce the non-vow specimen to a promise.  Then, associate a
+   * (usually durable) watcher object with the promise.
+   *
+   * @param {any} specimen
+   * @param {import('./watch-promise.js').PromiseWatcher} promiseWatcher
+   */
+  (specimen, promiseWatcher) => {
+    let promise;
+    const payload = getVowPayload(specimen);
+    if (payload) {
+      promise = basicE(payload.vowV0).shorten();
+    } else {
+      promise = basicE.resolve(specimen);
+    }
+    watchPromise(promise, promiseWatcher);
+  };
+
+/**
+ * @param {import('./types.js').VowResolver | undefined} resolver
+ * @param {import('./types.js').Watcher<unknown, unknown, unknown> | undefined} watcher
+ * @param {keyof Required<import('./types.js').Watcher>} wcb
+ * @param {unknown} value
+ * @param {unknown} [watcherContext]
+ */
+const settle = (resolver, watcher, wcb, value, watcherContext) => {
+  try {
+    let chainedValue = value;
+    const w = watcher && watcher[wcb];
+    if (w) {
+      chainedValue = apply(w, watcher, [value, watcherContext]);
+    } else if (wcb === 'onRejected') {
+      throw value;
+    }
+    resolver && resolver.resolve(chainedValue);
+  } catch (e) {
+    if (resolver) {
+      resolver.reject(e);
+    } else {
+      // for host's unhandled rejection handler to catch
+      throw e;
+    }
+  }
+};
+
+/**
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {(reason: any) => boolean} isRetryableReason
+ * @param {ReturnType<typeof makeWatchNextStep>} watchNextStep
+ */
+const preparePromiseWatcher = (zone, isRetryableReason, watchNextStep) =>
+  zone.exoClass(
+    'PromiseWatcher',
+    PromiseWatcherI,
+    /**
+     * @template [T=any]
+     * @template [TResult1=T]
+     * @template [TResult2=never]
+     * @param {import('./types.js').VowResolver<TResult1 | TResult2>} resolver
+     * @param {import('./types.js').Watcher<T, TResult1, TResult2>} [watcher]
+     * @param {unknown} [watcherContext]
+     */
+    (resolver, watcher, watcherContext) => {
+      const state = {
+        vow: /** @type {unknown} */ (undefined),
+        resolver,
+        watcher,
+        watcherContext,
+      };
+      return /** @type {Partial<typeof state>} */ (state);
+    },
+    {
+      /** @type {Required<import('./watch-promise.js').PromiseWatcher>['onFulfilled']} */
+      onFulfilled(value) {
+        const { watcher, watcherContext, resolver } = this.state;
+        if (getVowPayload(value)) {
+          // We've been shortened, so reflect our state accordingly, and go again.
+          this.state.vow = value;
+          watchNextStep(value, this.self);
+          return;
+        }
+        this.state.watcher = undefined;
+        this.state.resolver = undefined;
+        settle(resolver, watcher, 'onFulfilled', value, watcherContext);
+      },
+      /** @type {Required<import('./watch-promise.js').PromiseWatcher>['onRejected']} */
+      onRejected(reason) {
+        const { vow, watcher, watcherContext, resolver } = this.state;
+        if (vow && isRetryableReason(reason)) {
+          watchNextStep(vow, this.self);
+          return;
+        }
+        this.state.resolver = undefined;
+        this.state.watcher = undefined;
+        settle(resolver, watcher, 'onRejected', reason, watcherContext);
+      },
+    },
+  );
+
+/**
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {() => import('./types.js').VowKit<any>} makeVowKit
+ * @param {typeof watchPromiseShim} [watchPromise]
+ * @param {(reason: any) => boolean} [isRetryableReason]
+ */
+export const prepareWatch = (
+  zone,
+  makeVowKit,
+  watchPromise = watchPromiseShim,
+  isRetryableReason = _reason => false,
+) => {
+  const watchNextStep = makeWatchNextStep(watchPromise);
+  const makePromiseWatcher = preparePromiseWatcher(
+    zone,
+    isRetryableReason,
+    watchNextStep,
+  );
+
+  /**
+   * @template [T=any]
+   * @template [TResult1=T]
+   * @template [TResult2=T]
+   * @param {import('./types.js').ERef<T | import('./types.js').Vow<T>>} specimenP
+   * @param {import('./types.js').Watcher<T, TResult1, TResult2>} [watcher]
+   * @param {unknown} [watcherContext]
+   */
+  const watch = (specimenP, watcher, watcherContext) => {
+    /** @type {import('./types.js').VowKit<TResult1 | TResult2>} */
+    const { resolver, vow } = makeVowKit();
+
+    // Create a promise watcher to track vows, retrying upon rejection as
+    // controlled by `isRetryableReason`.
+    const promiseWatcher = makePromiseWatcher(
+      resolver,
+      watcher,
+      watcherContext,
+    );
+
+    // Coerce the specimen to a promise, and start the watcher cycle.
+    watchPromise(basicE.resolve(specimenP), promiseWatcher);
+
+    return vow;
+  };
+  harden(watch);
+
+  return watch;
+};
+
+harden(prepareWatch);
+
+/** @typedef {ReturnType<typeof prepareWatch>} Watch */

package/src/when.d.ts

@@ -0,0 +1,3 @@
+export function makeWhen(isRetryableReason?: ((reason: any) => boolean) | undefined): <T = any, TResult1 = import("./E.js").Unwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("./E.js").Unwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+export type When = ReturnType<typeof makeWhen>;
+//# sourceMappingURL=when.d.ts.map

package/src/when.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["when.js"],"names":[],"mappings":"AAMO,uDAFa,GAAG,KAAK,OAAO,6NAWb,GAAG,oFAoCxB;mBAIa,WAAW,eAAe,CAAC"}

package/src/when.js

@@ -0,0 +1,56 @@
+// @ts-check
+import { getVowPayload, basicE } from './vow-utils.js';
+
+/**
+ * @param {(reason: any) => boolean} [isRetryableReason]
+ */
+export const makeWhen = (isRetryableReason = () => false) => {
+  /**
+   * Shorten `specimenP` until we achieve a final result.
+   *
+   * @template [T=any]
+   * @template [TResult1=import('./E.js').Unwrap<T>]
+   * @template [TResult2=never]
+   * @param {T} specimenP value to unwrap
+   * @param {(value: import('./E.js').Unwrap<T>) => TResult1 | PromiseLike<TResult1>} [onFulfilled]
+   * @param {(reason: any) => TResult2 | PromiseLike<TResult2>} [onRejected]
+   * @returns {Promise<TResult1 | TResult2>}
+   */
+  const when = async (specimenP, onFulfilled, onRejected) => {
+    // Ensure we don't run until a subsequent turn.
+    await null;
+    Promise.prototype.then;
+
+    // Ensure we have a presence that won't be disconnected later.
+    let result = await specimenP;
+    let payload = getVowPayload(result);
+    while (payload) {
+      result = await basicE(payload.vowV0)
+        .shorten()
+        .catch(e => {
+          if (isRetryableReason(e)) {
+            // Shorten the same specimen to try again.
+            return result;
+          }
+          throw e;
+        });
+      // Advance to the next vow.
+      payload = getVowPayload(result);
+    }
+
+    const unwrapped = /** @type {import('./E.js').Unwrap<T>} */ (result);
+
+    // We've extracted the final result.
+    if (onFulfilled == null && onRejected == null) {
+      return /** @type {TResult1} */ (unwrapped);
+    }
+    return basicE.resolve(unwrapped).then(onFulfilled, onRejected);
+  };
+  harden(when);
+
+  return when;
+};
+
+harden(makeWhen);
+
+/** @typedef {ReturnType<typeof makeWhen>} When */