From 3d5a3f3e44e328e102d7db197c0b06b18a5c63fe Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Mon, 1 Jul 2024 11:51:40 -0700
Subject: [PATCH] feat(types): EVow

---
 packages/vow/src/tools.js       |  6 +++---
 packages/vow/src/types.js       |  6 ++++++
 packages/vow/src/watch-utils.js | 13 ++++++-------
 packages/vow/src/watch.js       |  4 ++--
 4 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/packages/vow/src/tools.js b/packages/vow/src/tools.js
index a318415ee12..c93cab4b5a3 100644
--- a/packages/vow/src/tools.js
+++ b/packages/vow/src/tools.js
@@ -7,7 +7,7 @@ import { makeAsVow } from './vow-utils.js';
 
 /**
  * @import {Zone} from '@agoric/base-zone';
- * @import {IsRetryableReason, AsPromiseFunction} from './types.js';
+ * @import {IsRetryableReason, AsPromiseFunction, Vow, EVow} from './types.js';
  */
 
 /**
@@ -33,9 +33,9 @@ export const prepareVowTools = (zone, powers = {}) => {
   /**
    * Vow-tolerant implementation of Promise.all.
    *
-   * @param {unknown[]} vows
+   * @param {EVow<unknown>[]} maybeVows
    */
-  const allVows = vows => watchUtils.all(vows);
+  const allVows = maybeVows => watchUtils.all(maybeVows);
 
   /** @type {AsPromiseFunction} */
   const asPromise = (specimenP, ...watcherArgs) =>
diff --git a/packages/vow/src/types.js b/packages/vow/src/types.js
index f81bf55f9a3..15b894b244e 100644
--- a/packages/vow/src/types.js
+++ b/packages/vow/src/types.js
@@ -29,6 +29,12 @@ export {};
  * @typedef {T | PromiseLike<T>} ERef
  */
 
+/**
+ * Eventually a value T or Vow for it.
+ * @template T
+ * @typedef {ERef<T | Vow<T>>} EVow
+ */
+
 /**
  * Follow the chain of vow shortening to the end, returning the final value.
  * This is used within E, so we must narrow the type to its remote form.
diff --git a/packages/vow/src/watch-utils.js b/packages/vow/src/watch-utils.js
index c314883a301..9af06f3ab6a 100644
--- a/packages/vow/src/watch-utils.js
+++ b/packages/vow/src/watch-utils.js
@@ -6,12 +6,11 @@ import { PromiseWatcherI } from '@agoric/base-zone';
 const { Fail, bare, details: X } = assert;
 
 /**
- * @import {MapStore} from '@agoric/store/src/types.js'
- * @import { Zone } from '@agoric/base-zone'
- * @import { Watch } from './watch.js'
- * @import { When } from './when.js'
- * @import {VowKit, AsPromiseFunction} from './types.js'
- * @import {IsRetryableReason} from './types.js'
+ * @import {MapStore} from '@agoric/store/src/types.js';
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {Watch} from './watch.js';
+ * @import {When} from './when.js';
+ * @import {VowKit, AsPromiseFunction, IsRetryableReason, Vow, EVow} from './types.js';
  */
 
 const VowShape = M.tagged(
@@ -81,7 +80,7 @@ export const prepareWatchUtils = (
     {
       utils: {
         /**
-         * @param {unknown[]} vows
+         * @param {EVow<unknown>[]} vows
          */
         all(vows) {
           const { nextId: id, idToVowState } = this.state;
diff --git a/packages/vow/src/watch.js b/packages/vow/src/watch.js
index 9391dfeefb7..fb5a793500b 100644
--- a/packages/vow/src/watch.js
+++ b/packages/vow/src/watch.js
@@ -6,7 +6,7 @@ const { apply } = Reflect;
 
 /**
  * @import { PromiseWatcher, Zone } from '@agoric/base-zone';
- * @import { ERef, IsRetryableReason, Vow, VowKit, VowResolver, Watcher } from './types.js';
+ * @import { ERef, EVow, IsRetryableReason, Vow, VowKit, VowResolver, Watcher } from './types.js';
  */
 
 /**
@@ -170,7 +170,7 @@ export const prepareWatch = (
    * @template [TResult1=T]
    * @template [TResult2=never]
    * @template {any[]} [C=any[]] watcher args
-   * @param {ERef<T | Vow<T>>} specimenP
+   * @param {EVow<T>} specimenP
    * @param {Watcher<T, TResult1, TResult2, C>} [watcher]
    * @param {C} watcherArgs
    */