Add operation chains

Author: cowboyd

chain/README.md

@@ -0,0 +1,83 @@
+# Chain
+
+There are some use-cases for Promise for which there is not a 1:1 analogue in
+Effection. One of these is the "promise chaining" behavior of the `Promise`
+constructor itself using `then()`, `catch()`, and `finally()`.
+
+The chain package accomplishes this in a very similar way:
+
+```ts
+import { Chain } from "@effectionx/chain";
+
+await main(function* () {
+  let chain = new Chain<number>((resolve) => {
+    resolve(10);
+  });
+
+  let result = yield* chain.then(function* (value) {
+    return value * 2;
+  });
+
+  console.log(result); //=> 20;
+});
+```
+
+Another is to share a promise in multiple places. For example this async data
+call is used and re-used:
+
+```ts
+class Foo {
+  data: Promise<number>;
+
+  constructor() {
+    this.data = (async () => 5)();
+  }
+
+  async getData() {
+    return await this.data;
+  }
+}
+
+const foo = new Foo();
+console.log(await foo.getData());
+```
+
+This can be accomplished with Chain like so:
+
+```ts
+class Foo {
+  data: Promise<number>;
+
+  constructor() {
+    let operation = (function* () {
+      return 5;
+    })();
+    this.data = Chain.from(operation);
+  }
+
+  *getData() {
+    return yield* this.data;
+  }
+}
+
+const foo = new Foo();
+console.log(yield * foo.getData());
+```
+
+---
+
+```ts
+import { Chain } from "@effectionx/chain";
+
+await main(function* () {
+  let chain = new Chain<number>((resolve) => {
+    resolve(10);
+  });
+
+  let result = yield* chain.then(function* (value) {
+    return value * 2;
+  });
+
+  console.log(result); //=> 20;
+});
+```

chain/chain.test.ts

@@ -0,0 +1,55 @@
+import { describe, it } from "@effectionx/bdd";
+import { expect } from "@std/expect";
+import type { Operation } from "effection";
+
+import { Chain } from "./mod.ts";
+
+describe("chain", () => {
+  it("can continunue", function* () {
+    let result = yield* new Chain<string>((resolve) => {
+      resolve("Hello");
+    }).then(function* (message) {
+      return `${message} World!`;
+    });
+    expect(result).toEqual("Hello World!");
+  });
+  it("can catch", function* () {
+    let result = yield* new Chain<string>((_, reject) => {
+      reject(new Error("boom!"));
+    }).catch(function* (e) {
+      return (e as Error).message;
+    });
+
+    expect(result).toEqual("boom!");
+  });
+
+  it("can have a finally", function* () {
+    let didExecuteFinally = false;
+    expect.assertions(1);
+    try {
+      yield* new Chain<string>((_, reject) => {
+        reject(new Error("boom!"));
+      }).finally(function* () {
+        didExecuteFinally = true;
+      });
+      throw new Error(`expected chain to reject`);
+    } catch (_) {
+      expect(didExecuteFinally).toEqual(true);
+    }
+  });
+
+  it("can chain off of an existing operation", function* () {
+    function* twice(num: number): Operation<number> {
+      return num * 2;
+    }
+
+    let chain = Chain.from(twice(5)).then(function* (num) {
+      return num * 2;
+    });
+
+    expect(yield* chain).toEqual(20);
+
+    // make sure it works twice
+    expect(yield* chain).toEqual(20);
+  });
+});

chain/deno.json

@@ -0,0 +1,11 @@
+{
+  "name": "@effectionx/chain",
+  "version": "0.1.0",
+  "exports": "./mod.ts",
+  "license": "MIT",
+  "imports": {
+    "effection": "npm:effection@^3",
+    "@std/expect": "jsr:@std/expect@^1",
+    "@effectionx/bdd": "jsr:@effectionx/bdd@^0.3.0"
+  }
+}

chain/mod.ts

@@ -0,0 +1,122 @@
+import type { Operation, WithResolvers } from "effection";
+import { call, withResolvers } from "effection";
+
+/**
+ * Resolve a Chain
+ */
+export type Resolve<T> = WithResolvers<T>["resolve"];
+
+/**
+ * Reject a chain
+ */
+export type Reject = WithResolvers<unknown>["reject"];
+
+/**
+ * Represent the eventual completion of an [Operation] in a fashion
+ * that mirrors the * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise}
+ * implementation
+ */
+export class Chain<T> implements From<T> {
+  private resolvers = withResolvers<T>();
+
+  /**
+   * Create a chain from any operation.
+   */
+  static from = from;
+
+  constructor(compute: (resolve: Resolve<T>, reject: Reject) => void) {
+    let { resolve, reject } = this.resolvers;
+    compute(resolve, reject);
+  }
+
+  then<B>(fn: (value: T) => Operation<B>): From<B> {
+    let { operation } = this.resolvers;
+    return from(operation).then(fn);
+  }
+
+  catch<B>(fn: (error: unknown | Error) => Operation<B>): From<T | B> {
+    let { operation } = this.resolvers;
+    return from(operation).catch(fn);
+  }
+
+  finally(fn: () => Operation<void>): From<T> {
+    let { operation } = this.resolvers;
+    return from(operation).finally(fn);
+  }
+
+  [Symbol.iterator](): ReturnType<From<T>[typeof Symbol.iterator]> {
+    return this.resolvers.operation[Symbol.iterator]();
+  }
+}
+
+export interface From<A> extends Operation<A> {
+  /**
+   * Create a new chain that will resolve to the current chain's value after
+   * applying `fn`;
+   *
+   * @param `fn` - is applied to the source operation's result to create the chained operation's result
+   *
+   * @returns a new {Chain} representing this application
+   */
+  then<B>(fn: (value: A) => Operation<B>): From<B>;
+
+  /**
+   * Create a new chain that will resolve to the original chain's
+   * value, or the result of `fn` in the event that the current chain
+   * rejects. applying `fn`;
+   *
+   * @param `fn` - applied when the current chain rejects and becomes the result of chain
+   *
+   * @returns a new {Chain} representing the potentially caught rejection
+   */
+  catch<B>(fn: (error: unknown | Error) => Operation<B>): From<A | B>;
+
+  /**
+   * Create a new {Chain} that behaves exactly like the original chain, except that operation specified with
+   * `fn` will run in all cases.
+   *
+   * @param `fn` - a function returning an operation that is always
+   *   evaluate just before the current chain yields its value.
+   */
+  finally(fn: () => Operation<void>): From<A>;
+}
+
+function from<T>(source: Operation<T>): From<T> {
+  let resolvers: WithResolvers<T> | undefined = undefined;
+  let chain: From<T> = {
+    *[Symbol.iterator]() {
+      if (!resolvers) {
+        resolvers = withResolvers<T>();
+        try {
+          resolvers.resolve(yield* source);
+        } catch (e) {
+          resolvers.reject(e as Error);
+        }
+      }
+      return yield* resolvers.operation;
+    },
+    then: (fn) =>
+      from(call(function* () {
+        return yield* fn(yield* chain);
+      })),
+
+    catch: (fn) =>
+      from(call(function* () {
+        try {
+          return yield* chain;
+        } catch (e) {
+          return yield* fn(e);
+        }
+      })),
+
+    finally: (fn) =>
+      from(call(function* () {
+        try {
+          return yield* chain;
+        } finally {
+          yield* fn();
+        }
+      })),
+  };
+  return chain;
+}

deno.json

@@ -27,6 +27,7 @@
     ]
   },
   "workspace": [
+    "./chain",
     "./context-api",
     "./deno-deploy",
     "./bdd",