@agoric/vow 0.1.1-dev-9f30228.0 → 0.1.1-dev-0b1501a.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/vow",
-  "version": "0.1.1-dev-9f30228.0+9f30228",
+  "version": "0.1.1-dev-0b1501a.0+0b1501a",
   "description": "Remote (shortening and disconnection-tolerant) Promise-likes",
   "type": "module",
   "main": "src/index.js",
@@ -19,8 +19,8 @@
     "lint:types": "tsc"
   },
   "dependencies": {
-    "@agoric/base-zone": "0.1.1-dev-9f30228.0+9f30228",
-    "@agoric/internal": "0.3.3-dev-9f30228.0+9f30228",
+    "@agoric/base-zone": "0.1.1-dev-0b1501a.0+0b1501a",
+    "@agoric/internal": "0.3.3-dev-0b1501a.0+0b1501a",
     "@endo/env-options": "^1.1.6",
     "@endo/errors": "^1.2.5",
     "@endo/eventual-send": "^1.2.5",
@@ -30,8 +30,8 @@
   },
   "devDependencies": {
     "@agoric/internal": "^0.3.2",
-    "@agoric/swingset-vat": "0.32.3-dev-9f30228.0+9f30228",
-    "@agoric/zone": "0.2.3-dev-9f30228.0+9f30228",
+    "@agoric/swingset-vat": "0.32.3-dev-0b1501a.0+0b1501a",
+    "@agoric/zone": "0.2.3-dev-0b1501a.0+0b1501a",
     "@endo/far": "^1.1.5",
     "@endo/init": "^1.1.4",
     "ava": "^5.3.0",
@@ -57,5 +57,5 @@
   "typeCoverage": {
     "atLeast": 89.96
   },
-  "gitHead": "9f302280633b9f760a169e47076f2c497b3a2bda"
+  "gitHead": "0b1501ace92d3f53ba37e1c83f508f61c14fcd7d"
 }

package/src/tools.d.ts

@@ -1,11 +1,22 @@
 export function prepareBasicVowTools(zone: Zone, powers?: {
     isRetryableReason?: IsRetryableReason | undefined;
-} | undefined): {
-    when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("./types.js").EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
-    watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: import("./types.js").Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
-    makeVowKit: <T>() => import("./types.js").VowKit<T>;
+} | undefined): VowTools;
+export type VowTools = {
+    /**
+     * Vow-tolerant implementation of Promise.all that takes an iterable of vows
+     * and other {@link Passable}s and returns a single {@link Vow}. It resolves
+     * with an array of values when all of the input's promises or vows are
+     * fulfilled and rejects when any of the input's promises or vows are rejected
+     * with the first rejection reason.
+     */
     all: (maybeVows: unknown[]) => Vow<any[]>;
-    allVows: (maybeVows: unknown[]) => Vow<any[]>;
+    /**
+     * Vow-tolerant
+     * implementation of Promise.allSettled that takes an iterable of vows and other
+     * {@link Passable}s and returns a single {@link Vow}. It resolves when all of
+     * the input's promises or vows are settled with an array of settled outcome
+     * objects.
+     */
     allSettled: (maybeVows: unknown[]) => Vow<({
         status: "fulfilled";
         value: any;
@@ -13,14 +24,36 @@ export function prepareBasicVowTools(zone: Zone, powers?: {
         status: "rejected";
         reason: any;
     })[]>;
-    asVow: <T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> | Awaited<T> | import("./types.js").PromiseVow<T>) => Vow<Awaited<T>>;
+    allVows: (maybeVows: unknown[]) => Vow<any[]>;
+    /**
+     * Convert a vow or promise to a promise, ensuring proper handling of ephemeral promises.
+     */
     asPromise: AsPromiseFunction;
+    /**
+     * Helper function that
+     * coerces the result of a function to a Vow. Helpful for scenarios like a
+     * synchronously thrown error.
+     */
+    asVow: <T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> | Awaited<T> | PromiseVow<T>) => Vow<Awaited<T>>;
+    makeVowKit: <T>() => VowKit<T>;
     retriable: <F extends (...args: any[]) => Promise<any>>(fnZone: Zone, name: string, fn: F) => F extends (...args: infer Args) => Promise<infer R> ? (...args: Args) => Vow<R> : never;
+    watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
+    /**
+     * Shorten `specimenP` until we achieve a final result.
+     *
+     * Does not survive upgrade (even if specimenP is a durable Vow).
+     *
+     * Use only if the Vow will resolve _promptly_ {@see {@link  @agoric/swingset-vat/docs/async.md}}.
+     */
+    when: <T, TResult1 = EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
 };
-export type VowTools = ReturnType<typeof prepareBasicVowTools>;
 import type { Zone } from '@agoric/base-zone';
 import type { IsRetryableReason } from './types.js';
-import type { EVow } from './types.js';
 import type { Vow } from './types.js';
 import type { AsPromiseFunction } from './types.js';
+import type { PromiseVow } from './types.js';
+import type { VowKit } from './types.js';
+import type { EVow } from './types.js';
+import type { Watcher } from './types.js';
+import type { EUnwrap } from './types.js';
 //# sourceMappingURL=tools.d.ts.map

package/src/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAqBO,2CAJI,IAAI;;;;;;qBA4CF,OAAO,EAAE;yBAAT,OAAO,EAAE;4BAgBT,OAAO,EAAE;;;;;;;oCAFc,GACpC;;gBAnCkD,CAAC,SAApC,CAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAE,UACpC,IAAI,QACJ,MAAM,MACN,CAAC,KACC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK;EAmDrG;uBAGa,UAAU,CAAC,OAAO,oBAAoB,CAAC;0BA3F9B,mBAAmB;uCAE8B,YAAY;0BAAZ,YAAY;yBAAZ,YAAY;uCAAZ,YAAY"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAmDO,2CALI,IAAI;;gBAGF,QAAQ,CA+EpB;;;;;;;;;SAjHa,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC;;;;;;;;gBAKpC,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,GAAG,CAAA;KAAC,GAC7E;QAAG,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAC,CAAC,EAAE,CAAC;aAK1B,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,EAAE,CAAC;;;;eACpC,iBAAiB;;;;;;WACjB,CAAC,CAAiB,SAAP,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GACtE,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;gBAGnC,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC;eAClB,CAAC,CAA0C,SAAhC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK;WAC1K,CAAC,CAAO,GAAH,GAAG,EAAE,QAAY,GAAD,CAAC,EAAE,QAAgB,GAAL,KAAK,EAAE,CAAuB,SAAb,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,GAAG,SAAS,EAAE,GAAG,WAAW,EAAE,CAAC,KAAK,IAAI,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;;;;;;;;UACzS,CAAC,CAAC,EAAE,QAAqB,GAAV,QAAQ,CAAC,CAAC,EAAE,QAAgB,GAAL,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,KAAK,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;;0BA3BpP,mBAAmB;uCAE8D,YAAY;yBAAZ,YAAY;uCAAZ,YAAY;gCAAZ,YAAY;4BAAZ,YAAY;0BAAZ,YAAY;6BAAZ,YAAY;6BAAZ,YAAY"}

package/src/tools.js

@@ -8,7 +8,36 @@ import { makeWhen } from './when.js';
 /**
  * @import {Zone} from '@agoric/base-zone';
  * @import {Passable} from '@endo/pass-style';
- * @import {IsRetryableReason, AsPromiseFunction, EVow, Vow, ERef} from './types.js';
+ * @import {EUnwrap, IsRetryableReason, AsPromiseFunction, Vow, VowKit, EVow, PromiseVow, Watcher} from './types.js';
+ */
+
+/**
+ * @typedef VowTools
+ * @property {(maybeVows: unknown[]) => Vow<any[]>} all Vow-tolerant implementation of Promise.all that takes an iterable of vows
+ * and other {@link Passable}s and returns a single {@link Vow}. It resolves
+ * with an array of values when all of the input's promises or vows are
+ * fulfilled and rejects when any of the input's promises or vows are rejected
+ * with the first rejection reason.
+ * @property {(maybeVows: unknown[]) => Vow<({status: 'fulfilled', value: any} |
+ * {status: 'rejected', reason: any})[]>} allSettled Vow-tolerant
+ * implementation of Promise.allSettled that takes an iterable of vows and other
+ * {@link Passable}s and returns a single {@link Vow}. It resolves when all of
+ * the input's promises or vows are settled with an array of settled outcome
+ * objects.
+ * @property {(maybeVows: unknown[]) => Vow<any[]>} allVows
+ * @property {AsPromiseFunction} asPromise Convert a vow or promise to a promise, ensuring proper handling of ephemeral promises.
+ * @property {<T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> |
+ * Awaited<T> | PromiseVow<T>) => Vow<Awaited<T>>} asVow Helper function that
+ * coerces the result of a function to a Vow. Helpful for scenarios like a
+ * synchronously thrown error.
+ * @property {<T>() => VowKit<T>} makeVowKit
+ * @property {<F extends (...args: any[]) => Promise<any>>(fnZone: Zone, name: string, fn: F) => F extends (...args: infer Args) => Promise<infer R> ? (...args: Args) => Vow<R> : never} retriable
+ * @property {<T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>} watch
+ * @property {<T, TResult1 = EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>} when Shorten `specimenP` until we achieve a final result.
+ *
+ * Does not survive upgrade (even if specimenP is a durable Vow).
+ *
+ * Use only if the Vow will resolve _promptly_ {@see {@link @agoric/swingset-vat/docs/async.md}}.
  */
 
 /**
@@ -18,6 +47,7 @@ import { makeWhen } from './when.js';
  * @param {Zone} zone
  * @param {object} [powers]
  * @param {IsRetryableReason} [powers.isRetryableReason]
+ * @returns {VowTools}
  */
 export const prepareBasicVowTools = (zone, powers = {}) => {
   const { isRetryableReason = /** @type {IsRetryableReason} */ (() => false) } =
@@ -34,8 +64,10 @@ export const prepareBasicVowTools = (zone, powers = {}) => {
   const watchUtils = makeWatchUtils();
   const asVow = makeAsVow(makeVowKit);
 
+  // FIXME in https://github.com/Agoric/agoric-sdk/pull/9785
   /**
-   * TODO FIXME make this real
+   * @alpha Not yet implemented
+   *
    * Create a function that retries the given function if the underlying
    * functions rejects due to upgrade disconnection.
    *
@@ -96,5 +128,3 @@ export const prepareBasicVowTools = (zone, powers = {}) => {
   });
 };
 harden(prepareBasicVowTools);
-
-/** @typedef {ReturnType<typeof prepareBasicVowTools>} VowTools */