Merge pull request #983 from thefrontside/backport-context-with

🎒bring Context.with() to v3

Author: cowboyd

lib/context.ts

@@ -1,4 +1,4 @@
-import type { Context } from "./types.ts";
+import type { Context, Operation } from "./types.ts";
 import { create } from "./run/create.ts";
 import { useScope } from "./run/scope.ts";
 
@@ -14,6 +14,19 @@ export function createContext<T>(key: string, defaultValue?: T): Context<T> {
       return scope.set(context, value);
     },
     expect,
+    *with<R>(value: T, operation: (value: T) => Operation<R>): Operation<R> {
+      let scope = yield* useScope();
+      let original = scope.hasOwn(context) ? scope.get(context) : undefined;
+      try {
+        return yield* operation(scope.set(context, value));
+      } finally {
+        if (typeof original === "undefined") {
+          scope.delete(context);
+        } else {
+          scope.set(context, original);
+        }
+      }
+    },
     [Symbol.iterator]() {
       console.warn(
         `⚠️ using a context (${key}) directly as an operation is deprecated. Use context.expect() instead`,

lib/types.ts

@@ -298,6 +298,22 @@ export interface Context<T> extends Operation<T> {
    * @return an operation providing the context value in the current scope.
    */
   expect(): Operation<T>;
+
+  /**
+   * Evaluate an operation using `value` for the context. Once the operation is completed, the context
+   * will be reverted to its original value, or removed if it was not present originally.
+   *
+   * @example
+   * ```ts
+   * let user = yield* login();
+   * yield* UserContext.with(user, function*() {
+   *   //do stuff
+   * })
+   * ```
+   *
+   * @returns the result of evaluating the operation.
+   */
+  with<R>(value: T, operation: (value: T) => Operation<R>): Operation<R>;
 }
 
 /**

test/context.test.ts

@@ -13,6 +13,21 @@ describe("context", () => {
     ).toEqual(3);
   });
 
+  it("can delimit the bounds of a context within a single scope", async () => {
+    let values = await run(function* () {
+      let before = yield* numbers.get();
+
+      let within = yield* numbers.with(22, function* () {
+        return yield* numbers.get();
+      });
+
+      let after = yield* numbers.get();
+      return [before, within, after];
+    });
+
+    expect(values).toEqual([3, 22, 3]);
+  });
+
   it("can be set within a given scope, but reverts after", async () => {
     let values = await run(function* () {
       let before = yield* numbers.expect();