From dbcad4ab4b8b29441a4bbb46719d56af3a399c88 Mon Sep 17 00:00:00 2001 From: Eryn Lynn Date: Wed, 24 Oct 2018 02:54:32 -0400 Subject: [PATCH] Add docs --- README.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ac172b0..1ca15a6 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,12 @@ This Promise implementation attempts to satisfy those traits. ## API ### Static Functions -* `Promise.new((resolve, reject) -> nil) -> Promise` +* `Promise.new((resolve, reject, onCancel) -> nil) -> Promise` * Construct a new Promise that will be resolved or rejected with the given callbacks. + * You may register an optional cancellation hook by using the `onCancel` argument. + * This should be used to abort any ongoing operations leading up to the promise being settled. + * Call the `onCancel` function with a new function as its only argument to set a hook which will in turn be called when/if the promise is cancelled. + * When a promise is cancelled, calls to `resolve` or `reject` will be ignored, regardless of if you set a cancellation hook or not. * `Promise.resolve(value) -> Promise` * Creates an immediately resolved Promise with the given value. * `Promise.reject(value) -> Promise` @@ -37,6 +41,13 @@ This Promise implementation attempts to satisfy those traits. * Equivalent to the Promise/A+ `then` method. * `Promise:catch(failureHandler) -> Promise` * Shorthand for `Promise:andThen(nil, failureHandler)`. +* `Promise:finally(finallyHandler) -> Promise` + * Set a handler that will be called regardless of the promise's fate. The handler is called when the promise is resolved, rejected, *or* cancelled. + * Returns a new promise chained from this promise. +* `Promise:cancel() -> nil` + * Cancels this promise, preventing the promise from resolving or rejecting. Does not do anything if the promise is already settled. + * Cancellations will propagate upwards through chained promises. + * Promises will only be cancelled if all of their consumers are also cancelled. This is to say that if you call `andThen` twice on the same promise, and you cancel only one of the promises resulting from the `andThen` call, it will not cancel the parent promise until the other child promise is also cancelled. * `Promise:await() -> ok, value` * Yields the current thread until the given Promise completes. Returns `ok` as a bool, followed by the value that the promise returned.