feat(vowTools): asPromise helper for unwrapping vows

packages/vow/src/tools.js

@@ -6,7 +6,7 @@ import { prepareWatchUtils } from './watch-utils.js';
 import { makeAsVow } from './vow-utils.js';
 
 /** @import {Zone} from '@agoric/base-zone' */
-/** @import {IsRetryableReason} from './types.js' */
+/** @import {IsRetryableReason, AsPromiseFunction} from './types.js' */
 
 /**
  * @param {Zone} zone
@@ -35,7 +35,11 @@ export const prepareVowTools = (zone, powers = {}) => {
    */
   const allVows = vows => watchUtils.all(vows);
 
-  return harden({ when, watch, makeVowKit, allVows, asVow });
+  /** @type {AsPromiseFunction} */
+  const asPromise = (specimenP, ...watcherArgs) =>
+    watchUtils.asPromise(specimenP, ...watcherArgs);
+
+  return harden({ when, watch, makeVowKit, allVows, asVow, asPromise });
 };
 harden(prepareVowTools);
 

packages/vow/src/types.js

@@ -86,3 +86,17 @@ export {};
  * @property {(value: T, ...args: C) => Vow<TResult1> | PromiseVow<TResult1> | TResult1} [onFulfilled]
  * @property {(reason: any, ...args: C) => Vow<TResult2> | PromiseVow<TResult2> | TResult2} [onRejected]
  */
+
+/**
+ * Converts a vow or promise to a promise, ensuring proper handling of ephemeral promises.
+ *
+ * @template [T=any]
+ * @template [TResult1=T]
+ * @template [TResult2=never]
+ * @template {any[]} [C=any[]]
+ * @callback AsPromiseFunction
+ * @param {ERef<T | Vow<T>>} specimenP
+ * @param {Watcher<T, TResult1, TResult2, C>} [watcher]
+ * @param {C} [watcherArgs]
+ * @returns {Promise<TResult1 | TResult2>}
+ */

packages/vow/src/watch-utils.js

@@ -10,7 +10,7 @@ const { Fail, bare } = assert;
  * @import { Zone } from '@agoric/base-zone'
  * @import { Watch } from './watch.js'
  * @import { When } from './when.js'
- * @import {VowKit} from './types.js'
+ * @import {VowKit, AsPromiseFunction} from './types.js'
  * @import {IsRetryableReason} from './types.js'
  */
 
@@ -96,6 +96,7 @@ export const prepareWatchUtils = (
           }
           return kit.vow;
         },
+        /** @type {AsPromiseFunction} */
         asPromise(specimenP, ...watcherArgs) {
           // Watch the specimen in case it is an ephemeral promise.
           const vow = watch(specimenP, ...watcherArgs);

packages/vow/test/watch-utils.test.js

@@ -199,3 +199,55 @@ test('allVows does NOT support Vow pipelining', async t => {
     message: 'target has no method "getAddress", has []',
   });
 });
+
+test('asPromise converts a vow to a promise', async t => {
+  const zone = makeHeapZone();
+  const { watch, asPromise } = prepareVowTools(zone);
+
+  const testPromiseP = Promise.resolve('test value');
+  const vow = watch(testPromiseP);
+
+  const result = await asPromise(vow);
+  t.is(result, 'test value');
+});
+
+test('asPromise handles vow rejection', async t => {
+  const zone = makeHeapZone();
+  const { watch, asPromise } = prepareVowTools(zone);
+
+  const testPromiseP = Promise.reject(new Error('test error'));
+  const vow = watch(testPromiseP);
+
+  await t.throwsAsync(asPromise(vow), { message: 'test error' });
+});
+
+test('asPromise accepts and resolves promises', async t => {
+  const zone = makeHeapZone();
+  const { asPromise } = prepareVowTools(zone);
+
+  const p = Promise.resolve('a promise');
+  const result = await asPromise(p);
+  t.is(result, 'a promise');
+});
+
+test('asPromise handles watcher arguments', async t => {
+  const zone = makeHeapZone();
+  const { watch, asPromise } = prepareVowTools(zone);
+
+  const testPromiseP = Promise.resolve('watcher test');
+  const vow = watch(testPromiseP);
+
+  let watcherCalled = false;
+  const watcher = {
+    onFulfilled(value, ctx) {
+      watcherCalled = true;
+      t.is(value, 'watcher test');
+      t.deepEqual(ctx, ['ctx']);
+      return value;
+    },
+  };
+
+  const result = await asPromise(vow, watcher, ['ctx']);
+  t.is(result, 'watcher test');
+  t.true(watcherCalled);
+});