Merge pull request #953 from thefrontside/v4-with-resolvers-test

Add docs and test for with resolvers

test/with-resolvers.test.ts

@@ -0,0 +1,32 @@
+import { run, withResolvers } from "../mod.ts";
+import { describe, expect, it } from "./suite.ts";
+
+describe("withResolvers()", () => {
+  it("resolves", async () => {
+    let { operation, resolve } = withResolvers<string>();
+    resolve("hello");
+    await expect(run(() => operation)).resolves.toEqual("hello");
+  });
+  it("resolves only once", async () => {
+    let { operation, resolve, reject } = withResolvers<string>();
+    resolve("hello");
+    reject(new Error("boom!"));
+    resolve("goodbye");
+    await expect(run(() => operation)).resolves.toEqual("hello");
+  });
+  it("rejects", async () => {
+    let { operation, reject } = withResolvers<string>();
+    reject(new Error("boom!"));
+    await expect(run(() => operation)).rejects.toMatchObject({
+      message: "boom!",
+    });
+  });
+  it("rejects only once", async () => {
+    let { operation, reject } = withResolvers<string>();
+    reject(new Error("boom!"));
+    reject(new Error("bam!"));
+    await expect(run(() => operation)).rejects.toMatchObject({
+      message: "boom!",
+    });
+  });
+});

www/docs/async-rosetta-stone.mdx

@@ -201,6 +201,39 @@ function* main() {
 };
 ```
 
+## `Promise.withResolvers()` \<=> `withResolvers()`
+
+Both `Promise` and `Operation` can be constructed ahead of time without needing to begin the process that will resolve it. To do this with
+a `Promise`, use the `Promise.withResolvers()` function:
+
+```ts
+async function main() {
+  let { promise, resolve } = Promise.withResolvers();
+
+  setTimeout(resolve, 1000);
+
+  await promise;
+
+  console.log("done!")
+}
+```
+
+In effection:
+
+```ts
+import { withResolvers } from "effection";
+
+function* main() {
+  let { operation, resolve } = withResolvers();
+
+  setTimeout(resolve, 1000);
+
+  yield* operation;
+
+  console.log("done!");
+};
+```
+
 ## `for await` \<=> `for yield* each`
 
 Loop over an AsyncIterable with `for await`: