chore: Update Promise Kit README #2317
Conversation
| @@ -1,3 +1,71 @@ | |||
| # Promise Kit | |||
|
|
|||
| A helper for making promises | |||
| The promise-kit package provides a simple abstraction for creating a promise and its corresponding resolve and reject functions, allowing for easier promise management. It exports, `makePromiseKit` which is a utility function used to create a Promise and its associated resolver and rejector functions. This is particularly useful in asynchronous programming, where you might need to create a promise and resolve or reject it at a later point in time. | |||
|
|
|||
There was a problem hiding this comment.
@mhofman Would you contribute a word about why you would use this instead of Promise.withResolvers this year?
It may be worth stating up front that this is a “ponyfill” for Promise.withResolvers that makes certain accommodations to ensure that the resulting promises can pipeline messages through @endo/eventual-send.
There was a problem hiding this comment.
@kriskowal I can append this text at the end of above if that is desirable:
“ponyfill” for Promise.withResolvers that makes certain accommodations to ensure that the resulting promises can pipeline messages through @endo/eventual-send.
There was a problem hiding this comment.
It's actually more than this. It also fixes resolver leaks in common implementations. Once withResolvers get introduced later this year, we should consider making this a full shim (this package is already a shim for race which is similarly leaky)
There was a problem hiding this comment.
Oh yeah it also creates HandledPromises, however I admit I still get confused about the layering there, @michaelfig might be more helpful.
There was a problem hiding this comment.
Thinking about this, a repaired HandledPromise.withResolvers would do what makePromiseKit does since it defers to the this to decide what the constructor is.
There was a problem hiding this comment.
HandledPromise is an augmentation of Promise that supports eventual operations. It does not rely on any other packages, but the @endo/eventual-send package provides a shim for it in addition to the makeE eventual send operator maker. I'm not yet certain where makeE actually belongs; I'd like to have just one version of it that (like the version in @agoric/vow/src/E.js) can support a higher-than-eventual-send layer's implementation of pseudo-promises.
makePromiseKit uses HandledPromise if available; otherwise just Promise.
There was a problem hiding this comment.
So, should I add the following or is there a more accurate statement that needs to be added? Or leave it as is?
This is a “ponyfill” for Promise.withResolvers that makes certain accommodations to ensure that the resulting promises can pipeline messages through @endo/eventual-send.
There was a problem hiding this comment.
I think this verbiage is fine and we can refine in follow-up. Please merge at your leisure.
ghost
force-pushed
the
ms-update-promise-kit-readme
branch
from
92b8ac7
to
23e6b4b
Compare
Update Promise Kit README
fixes #2318