Skip to content

Commit

Permalink
docs: vowTools
Browse files Browse the repository at this point in the history
  • Loading branch information
0xpatrickdev committed Sep 16, 2024
1 parent 41a4ddd commit 8c50684
Showing 1 changed file with 62 additions and 1 deletion.
63 changes: 62 additions & 1 deletion packages/vow/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Here they are: {
```

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
promises and vows to a promise for its final fulfillment, by unwrapping any
intermediate vows:

```js
Expand Down Expand Up @@ -77,6 +77,67 @@ const { watch, makeVowKit } = prepareVowTools(vowZone);
// Vows and resolvers you create can be saved in durable stores.
```

## VowTools

VowTools are a set of utility functions for working with Vows in Agoric smart contracts and vats. These tools help manage asynchronous operations in a way that's resilient to vat upgrades, ensuring your smart contract can handle long-running processes reliably.

### Usage

VowTools are typically prepared in the start function of a smart contract or vat and passed in as a power to exos.


```javascript
import { prepareVowTools } from '@agoric/vow/vat.js';
import { makeDurableZone } from '@agoric/zone/durable.js';

export const start = async (zcf, privateArgs, baggage) => {
const zone = makeDurableZone(baggage);
const vowTools = prepareVowTools(zone.subZone('vows'));

// Use vowTools here...
}
```

### Available Tools

#### `when(vowOrPromise)`
Waits for a Vow or Promise to resolve and returns its value. It can't handle disconnections due to vat upgrades.

#### `watch(promiseOrVow, [watcher], [context])`
Watch a Vow and optionally provide a `watcher` with `onFulfilled`/`onRejected` handlers and a `context` value for the handlers. When handlers are not provided the fulfillment or rejection will simply pass through.

Also converts a Promise into a Vow which can survive vat upgrades.

#### `all(arrayOfVowsOrPassables, [watcher], [context])`
Vow-tolerant implementation of Promise.all that takes an iterable of vows and other Passables and returns a single 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.

#### `allSettled(arrayOfVowsOrPassables, [watcher], [context])`
Vow-tolerant implementation of Promise.allSettled that takes an iterable of vows and other Passables and returns a single Vow. It resolves when all of the input's promises or vows are settled with an array of settled outcome objects.

#### `asVow(fn)`
Takes a function that might return synchronously, throw an Error, or return a Promise or Vow and returns a Vow.

#### `asPromise(vow)`
Converts a Vow back into a Promise.

### Example

```javascript
const { when, watch, all, allSettled } = vowTools;

// Using watch to create a Vow
const myVow = watch(someAsyncOperation());

// Using when to resolve a Vow
const result = await when(myVow);

// Using all
const results = await when(all([vow, vowForVow, promise]));

// Using allSettled
const outcomes = await when(allSettled([vow, vowForVow, promise]));
```

## Internals

The current "version 0" vow internals expose a `shorten()` method, returning a
Expand Down

0 comments on commit 8c50684

Please sign in to comment.