@agoric/vow 0.1.1-dev-9986152.0 → 0.1.1-dev-aedfac6.0

package/README.md

@@ -26,12 +26,12 @@ Here they are: {
 }
 ```
 
-On Agoric, you can use `V` exported from `@agoric/vow/vat.js`, which
-converts a chain of promises and vows to a promise for its final
-fulfilment, by unwrapping any intermediate vows:
+You can use `heapVowE` exported from `@agoric/vow`, which converts a chain of
+promises and vows to a promise for its final fulfilment, by unwrapping any
+intermediate vows:
 
 ```js
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow';
 [...]
 const a = await E.when(w1);
 const b = await E(w2).something(...args);
@@ -40,12 +40,13 @@ const b = await E(w2).something(...args);
 
 ## Vow Producer
 
-On Agoric, use the following to create and resolve a vow:
+Use the following to create and resolve a vow:
 
 ```js
-// CAVEAT: `V` uses internal ephemeral promises, so while it is convenient,
+// CAVEAT: `heapVow*` uses internal ephemeral promises, so while it is convenient,
 // it cannot be used by upgradable vats.  See "Durability" below:
-import { V as E, makeVowKit } from '@agoric/vow/vat.js';
+import { heapVowE, heapVowTools } from '@agoric/vow';
+const { makeVowKit } = heapVowTools;
 [...]
 const { resolver, vow } = makeVowKit();
 // Send vow to a potentially different vat.
@@ -56,15 +57,15 @@ resolver.resolve('now you know the answer');
 
 ## Durability
 
-The `@agoric/vow/vat.js` module allows vows to integrate Agoric's vat upgrade
-mechanism.  To create vow tools that deal with durable objects:
+By default, the `@agoric/vow` module allows vows to integrate with Agoric's vat
+upgrade mechanism.  To create vow tools that deal with durable objects:
 
 ```js
 // NOTE: Cannot use `V` as it has non-durable internal state when unwrapping
 // vows.  Instead, use the default vow-exposing `E` with the `watch`
 // operator.
 import { E } from '@endo/far';
-import { prepareVowTools } from '@agoric/vow/vat.js';
+import { prepareVowTools } from '@agoric/vow';
 import { makeDurableZone } from '@agoric/zone';
 
 // Only do the following once at the start of a new vat incarnation:
@@ -94,20 +95,25 @@ final result:
 // that may not be side-effect free.
 let result = await specimenP;
 let vowInternals = getVowInternals(result);
+let disconnectionState = undefined;
 // Loop until the result is no longer a vow.
 while (vowInternals) {
   try {
-    const shortened = await E(internals.vowV0).shorten();
+    // WARNING: Do not use `shorten()` in your own code.  This is an example
+    // for didactic purposes only.
+    const shortened = await E(vowInternals.vowV0).shorten();
     const nextInternals = getVowInternals(shortened);
     // Atomically update the state.
     result = shortened;
     vowInternals = nextInternals;
   } catch (e) {
-    if (!isDisconnectionReason(e)) {
+    const nextDisconnectionState = isDisconnectionReason(e, disconnectionState);
+    if (!nextDisconnectionState) {
       // Not a disconnect, so abort.
       throw e;
     }
-    // It was a disconnect, so try again with the same state.
+    // It was a disconnect, so try again with the updated state.
+    disconnectionState = nextDisconnectionState;
   }
 }
 return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/vow",
-  "version": "0.1.1-dev-9986152.0+9986152",
+  "version": "0.1.1-dev-aedfac6.0+aedfac6",
   "description": "Remote (shortening and disconnection-tolerant) Promise-likes",
   "type": "module",
   "main": "src/index.js",
@@ -20,8 +20,8 @@
     "lint:types": "tsc"
   },
   "dependencies": {
-    "@agoric/base-zone": "0.1.1-dev-9986152.0+9986152",
-    "@agoric/internal": "0.3.3-dev-9986152.0+9986152",
+    "@agoric/base-zone": "0.1.1-dev-aedfac6.0+aedfac6",
+    "@agoric/internal": "0.3.3-dev-aedfac6.0+aedfac6",
     "@endo/env-options": "^1.1.5",
     "@endo/errors": "^1.2.4",
     "@endo/eventual-send": "^1.2.4",
@@ -56,5 +56,5 @@
   "typeCoverage": {
     "atLeast": 89.93
   },
-  "gitHead": "9986152969a5f7df2044710e99178dbfb51e5f37"
+  "gitHead": "aedfac6ea5fd276a4f64a327cad18d3633901547"
 }

package/src/index.d.ts

@@ -1,6 +1,7 @@
-export * from "./tools.js";
+export * from "../vat.js";
 export * from "./types.js";
 export * from "@agoric/internal/src/types.js";
 export { default as makeE } from "./E.js";
+export type VowTools = import("./tools.js").VowTools;
 export { VowShape, toPassableCap } from "./vow-utils.js";
 //# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";;;;uBASa,OAAO,YAAY,EAAE,QAAQ"}

package/src/index.js

@@ -1,8 +1,15 @@
 // @ts-check
-export * from './tools.js';
+
+// We default to the vat-compatible version of this package, which is easy to
+// reconfigure if not running under SwingSet.
+export * from '../vat.js';
 export { default as makeE } from './E.js';
 export { VowShape, toPassableCap } from './vow-utils.js';
 
+/**
+ * @typedef {import('./tools.js').VowTools} VowTools
+ */
+
 // eslint-disable-next-line import/export
 export * from './types.js';
 

package/src/tools.d.ts

@@ -1,4 +1,4 @@
-export function prepareVowTools(zone: Zone, powers?: {
+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>;
@@ -9,7 +9,7 @@ export function prepareVowTools(zone: Zone, powers?: {
     asPromise: AsPromiseFunction;
     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;
 };
-export type VowTools = ReturnType<typeof prepareVowTools>;
+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';

package/src/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAoBO,sCAJI,IAAI;;;;;;yBAwCF,KAAK,OAAO,CAAC,EAAE;oCAqB6V,GAAG;;gBArC1U,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;EA6BrG;uBAGa,UAAU,CAAC,OAAO,eAAe,CAAC;0BApEzB,mBAAmB;uCAC8B,YAAY;0BAAZ,YAAY;yBAAZ,YAAY;uCAAZ,YAAY"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAoBO,2CAJI,IAAI;;;;;;yBAwCF,KAAK,OAAO,CAAC,EAAE;oCAqB8U,GAAG;;gBArC3T,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;EA6BrG;uBAGa,UAAU,CAAC,OAAO,oBAAoB,CAAC;0BApE9B,mBAAmB;uCAC8B,YAAY;0BAAZ,YAAY;yBAAZ,YAAY;uCAAZ,YAAY"}

package/src/tools.js

@@ -18,7 +18,7 @@ import { makeWhen } from './when.js';
  * @param {object} [powers]
  * @param {IsRetryableReason} [powers.isRetryableReason]
  */
-export const prepareVowTools = (zone, powers = {}) => {
+export const prepareBasicVowTools = (zone, powers = {}) => {
   const { isRetryableReason = /** @type {IsRetryableReason} */ (() => false) } =
     powers;
   const makeVowKit = prepareVowKit(zone);
@@ -72,6 +72,6 @@ export const prepareVowTools = (zone, powers = {}) => {
     retriable,
   });
 };
-harden(prepareVowTools);
+harden(prepareBasicVowTools);
 
-/** @typedef {ReturnType<typeof prepareVowTools>} VowTools */
+/** @typedef {ReturnType<typeof prepareBasicVowTools>} VowTools */

package/vat.js

@@ -7,7 +7,9 @@
 // @ts-check
 import { isUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
 import { makeHeapZone } from '@agoric/base-zone/heap.js';
-import { makeE, prepareVowTools as rawPrepareVowTools } from './src/index.js';
+
+import { prepareBasicVowTools } from './src/tools.js';
+import makeE from './src/E.js';
 
 /** @type {import('./src/types.js').IsRetryableReason} */
 const isRetryableReason = (reason, priorRetryValue) => {
@@ -28,13 +30,17 @@ export const defaultPowers = harden({
 /**
  * Produce SwingSet-compatible vowTools, with an arbitrary Zone type
  *
- * @type {typeof rawPrepareVowTools}
+ * @type {typeof prepareBasicVowTools}
  */
 export const prepareSwingsetVowTools = (zone, powers = {}) =>
-  rawPrepareVowTools(zone, { ...defaultPowers, ...powers });
+  prepareBasicVowTools(zone, { ...defaultPowers, ...powers });
+harden(prepareSwingsetVowTools);
 
-/** @deprecated */
-export const prepareVowTools = prepareSwingsetVowTools;
+/**
+ * Reexport as prepareVowTools, since that's the thing that people find easiest
+ * to reach.
+ */
+export { prepareSwingsetVowTools as prepareVowTools };
 
 /**
  * `vowTools` that are not durable, but are useful in non-durable clients that