From 3dd3f95ca61215b96fd2ea137c06d2e1ef96b251 Mon Sep 17 00:00:00 2001
From: Charles Lowell <cowboyd@frontside.com>
Date: Fri, 13 Dec 2024 16:19:21 -0600
Subject: [PATCH] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20Deprecate=20non-functio?=
 =?UTF-8?q?n=20invocations=20of=20`call()`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

There were too many overloads of call that ended up throwing off the
typings. Specifically, there were difficulties in disambiguating
between: `() => T` as a callable and `() => Promise<T>`, because `T`
could be `Promise<T>`.

This deprecates every other call() aside from async functions and
operation functions (generator functions).
---
 lib/call.ts          | 44 +++++++++++++++++++++++++-------------------
 test/context.test.ts |  4 ++--
 2 files changed, 27 insertions(+), 21 deletions(-)

diff --git a/lib/call.ts b/lib/call.ts
index fb9cfb89..77f0eb6f 100644
--- a/lib/call.ts
+++ b/lib/call.ts
@@ -32,22 +32,13 @@ export type Callable<T> =
   | (() => T);
 
 /**
- * Pause the current operation, then runs a promise, async function, plain function,
- * or operation within a new scope. The calling operation will be resumed (or errored)
+ * Pause the current operation, then run an async function, or operation function in a new scope. The calling operation will be resumed (or errored)
  * once call is completed.
  *
  * `call()` is a uniform integration point for calling async functions,
- * evaluating promises, generator functions, operations, and plain
- * functions.
+ * and generator functions.
  *
- * It can be used to treat a promise as an operation:
- *
- * @example
- * ```javascript
- * let response = yield* call(fetch('https://google.com'));
- * ```
- *
- * or an async function:
+ * It can be used to invoke an async function:
  *
  * @example
  * ```typescript
@@ -70,13 +61,6 @@ export type Callable<T> =
  * }); // => socket is destroyed before returning
  * ```
  *
- * It can be used to run a plain function:
- *
- * @example
- * ```javascript
- * yield* call(() => "a string");
- * ```
- *
  * Because `call()` runs within its own {@link Scope}, it can also be used to
  * establish [error boundaries](https://frontside.com/effection/docs/errors).
  *
@@ -110,9 +94,31 @@ export type Callable<T> =
  */
 export function call<T>(callable: () => Operation<T>): Operation<T>;
 export function call<T>(callable: () => Promise<T>): Operation<T>;
+
+/**
+ * @deprecated Using call with simple functions will be removed in v4.
+ * To convert simple functions into operations, use @{link lift}.
+ */
 export function call<T>(callable: () => T): Operation<T>;
+
+/**
+ * @deprecated calling bare promises, operations, and constants will
+ * be removed in v4, always pass a function to call()
+ *
+ * before: call(operation);
+ * after:  call(() => operation);
+ */
 export function call<T>(callable: Operation<T>): Operation<T>;
+
+/**
+ * @deprecated calling bare promises, operations, and constants will
+ * be removed in v4, always pass a function to call()
+ *
+ * before: call(promise);
+ * after:  call(() => promise);
+ */
 export function call<T>(callable: Promise<T>): Operation<T>;
+
 export function call<T>(callable: Callable<T>): Operation<T> {
   return action(function* (resolve, reject) {
     try {
diff --git a/test/context.test.ts b/test/context.test.ts
index f7c373d8..16e2dd28 100644
--- a/test/context.test.ts
+++ b/test/context.test.ts
@@ -8,7 +8,7 @@ describe("context", () => {
   it("has the initial value available at all times", async () => {
     expect(
       await run(function* () {
-        return yield* numbers;
+        return yield* numbers.expect();
       }),
     ).toEqual(3);
   });
@@ -20,7 +20,7 @@ describe("context", () => {
         yield* numbers.set(22);
         return yield* numbers.expect();
       });
-      let after = yield* numbers;
+      let after = yield* numbers.expect();
       return [before, within, after];
     });