more-proms 1.1.1 → 1.2.0

package/README.md

@@ -55,21 +55,31 @@ promRes()
 
 `CancelAblePromise` is a subclass of `SettledPromise` that adds cancellation support. It has a `cancel` method for the consumer that can be used to cancel the promise. A canceled promise will never resolve nor will it reject.
 
-Nested cancellation are also supported. More specific: where nested promises created by `then` or `catch` methods are cancelled when the parent promise is cancelled.
+The promise provider can provide a callback will only ever be called once, and wont be called after resolvement or rejection. This callback can be used to e.g. cancel an ongoing animation, or network request.
+
+Note how in this example the clearance of the timeout will have no effect, as a canceled promise wont resolve nor reject even if resolve is called after the timeout finishes. But the two example use cases from above could actually do something useful in the cancel callback.
+
 
 ```ts
 import { CancelAblePromise } from "more-proms"
 
+let timeout
 const p = new CancelAblePromise<string>((resolve, reject) => {
-  setTimeout(() => {
+  timeout = setTimeout(() => {
     resolve("Hello, world!")
   }, 1000)
+}, () => {
+  console.log("cancelled")
+  clearTimeout(timeout)
 })
 
+
+// later
+
 p.cancel()
 ```
 
-A nested example: Note how `p1` is cancelled before `p2` resolve, hence only the `p1` will resolve, the `p2` will never resolve.
+Nested cancellation are also supported. More specific: where nested promises created by `then` or `catch` methods are cancelled when the parent promise is cancelled. A nested example follows below. Note how `p1` is cancelled before `p2` resolve, hence only the `p1` will resolve, the `p2` will never resolve.
 
 ```ts
 const p1 = new CancelAblePromise<string>((resolve, reject) => {
@@ -105,17 +115,46 @@ import { latestLatent } from "more-proms"
 const showPopup = latestLatent(async () => {
   element.css({display: "block"})
   await element.animate({opacity: 1})
-  await waitForCloseInput()
+  await closeButton.waitForClick()
   await element.animate({opacity: 0})
 })
 
-showPopup().then(() => {
-  element.css({display: "none"})
+
+// later
+
+showButton.on("click", () => {
+  showPopup().then(() => {
+    element.css({display: "none"})
+  })
 })
+
 ```
 
 This way you can be sure that the popup doesnt get `display: none`, when the user opens it again before it has been fully closed (the animation finishes).
 
+You may have noticed that the location in your code where you want to `showPopup()` may have a different concern than ensuring that the popupElement is properly hidden. So, to keep the concerns where they belong, you can chain then calls directly on the showPopup provider (where it is declared).
+
+```ts
+import { latestLatent } from "more-proms"
+
+const showPopup = latestLatent(async () => {
+  element.css({display: "block"})
+  await element.animate({opacity: 1})
+  await closeButton.waitForClick()
+  await element.animate({opacity: 0})
+}).then(() => {
+  element.css({display: "none"})
+})
+
+
+// later
+
+showButton.on("click", () => {
+  showPopup()
+})
+```
+
+
 
 ## Contribute