feat!: remove thenable behavior from Try instances

Try is no longer thenable for any wrapped function. Callers must use
.value()/.unwrap()/.error()/.result() to execute.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: w01fgang

.changeset/remove-thenable-instances.md

@@ -0,0 +1,4 @@
+---
+'@power-rent/try-catch': major
+---
+Remove thenable behavior from `Try` instances entirely. No `Try` instance is ever thenable — `await new Try(fn)` yields the `Try` instance itself regardless of whether the wrapped function is sync or async. Callers must use `.value()`, `.unwrap()`, `.error()`, or `.result()` to execute and read the result. Migration: replace `await new Try(asyncFn, ...args)` with `await new Try(asyncFn, ...args).value()` (or `.unwrap()` / `.result()` / `.error()` depending on desired semantics).

README.md

@@ -65,9 +65,9 @@ import { Try } from '@power-rent/try-catch';
 
 ## Sync vs Async
 
-Only `async` functions (declared with the `async` keyword) produce a thenable `Try` instance. Everything else — sync functions, *and sync functions that happen to return a Promise* — must be consumed via a terminal method.
+`Try` instances are never thenable. Whether the wrapped function is sync or async, you must call a terminal method (`.value()`, `.unwrap()`, `.error()`, or `.result()`) to run it and read the outcome.
 
-**Async functions** — `await` the terminal method (or the `Try` instance directly):
+**Async functions** — `await` the terminal method:
 
 ```ts doctest
 import { Try } from '@power-rent/try-catch';
@@ -76,14 +76,10 @@ async function asyncFn(arg: number) {
   return arg * 2;
 }
 
-// Async function: await the terminal call
 const result = await new Try(asyncFn, 21).value();
 
-// Or await the Try instance itself (works for async functions only)
-const same = await new Try(asyncFn, 21);
-
-if (result !== 42 || same !== 42) {
-  throw new Error(`expected 42, got ${String(result)} / ${String(same)}`);
+if (result !== 42) {
+  throw new Error(`expected 42, got ${String(result)}`);
 }
 ```
 
@@ -103,7 +99,7 @@ function returnsPromise(): Promise<number> {
 }
 const n = await new Try(returnsPromise).value();
 
-// Awaiting a non-async Try yields the Try instance, NOT the result.
+// Awaiting a Try instance directly yields the Try instance, NOT the result.
 // The instance is not thenable, so `await` cannot trigger execution.
 // Use .value() / .unwrap() / .error() / .result() instead.
 if ((result as { ok: boolean }).ok !== true || n !== 42) {
@@ -355,9 +351,9 @@ Execute and return a discriminated union:
 Breadcrumbs are recorded on the error branch.
 
 Sync functions return values immediately; async functions return Promises.
-Only `AsyncFunction`-wrapped `Try` instances are awaitable —
-`await new Try(nonAsyncFn)` yields the `Try` instance itself, use
-`.value()` / `.unwrap()` / `.error()` / `.result()` instead.
+`Try` instances are never thenable — `await new Try(fn)` yields the `Try`
+instance itself regardless of whether the wrapped function is sync or async.
+Use `.value()` / `.unwrap()` / `.error()` / `.result()` to execute.
 
 ## Examples
 

docs/ARCHITECTURE.md

@@ -86,13 +86,15 @@ When `.report()` is **not** configured but `.breadcrumbs()` is, each terminal me
 
 ## Sync vs async execution paths
 
-The library resolves the sync/async split at construction time using a single check:
+The library resolves the sync/async split at terminal-method call time. `Try` instances are **never thenable** — no `.then` is ever installed — so `await new Try(fn)` always yields the `Try` instance itself without triggering execution. Any thenability probe (`Promise.resolve`, `util.inspect`, deep-equality matchers, serializers) is guaranteed not to invoke the wrapped function.
+
+Callers consume the result with `.value()`, `.unwrap()`, `.result()`, or `.error()`. Each terminal routes through `execute()`:
 
 **Async path (declared `async` functions)**
-`fn.constructor.name === 'AsyncFunction'` is true. `installThenable()` defines `.then` as an owned data property immediately, so `await new Try(asyncFn)` works without executing the function early.
+`fn.constructor.name === 'AsyncFunction'` is true. The terminal returns a `Promise<...>` that callers `await`.
 
 **Non-async path (everything else)**
-No `.then` property is installed. The instance is **not thenable**, so `await new Try(nonAsyncFn)` yields the `Try` instance itself rather than triggering execution. This holds even when the wrapped function happens to return a `Promise` — any thenability probe (`Promise.resolve`, `util.inspect`, deep-equality matchers, serializers) is guaranteed not to invoke the wrapped function. Callers must use `.value()`, `.unwrap()`, `.result()`, or `.error()` directly. Each terminal routes through `execute()`, which detects a `Promise` return value and returns a `Promise<TryResult>` so awaiting the terminal still works.
+The terminal runs synchronously. If the wrapped function happens to return a `Promise`, `execute()` detects it and returns a `Promise<TryResult>` so `await` still works on the terminal call.
 
 Both paths cache the result in `this.exec` so that subsequent terminal method calls return the same settled value.
 

docs/GETTING-STARTED.md

@@ -96,9 +96,9 @@ Try.setDefaultReporter(new ConsoleReporter());
 
 ## Sync vs Async
 
-Only `async` functions (declared with the `async` keyword) produce a thenable `Try` instance. Everything else — sync functions, *and sync functions that happen to return a Promise* — must be consumed via a terminal method.
+`Try` instances are never thenable. Whether the wrapped function is sync or async, you must call a terminal method (`.value()`, `.unwrap()`, `.error()`, or `.result()`) to run it and read the outcome.
 
-**Async functions** — `await` the terminal method (or the `Try` instance directly):
+**Async functions** — `await` the terminal method:
 
 ```ts doctest
 import { Try } from '@power-rent/try-catch';
@@ -107,14 +107,10 @@ async function asyncFn(arg: number) {
   return arg * 2;
 }
 
-// Async function: await the terminal call
 const result = await new Try(asyncFn, 21).value();
 
-// Or await the Try instance itself (works for async functions only)
-const same = await new Try(asyncFn, 21);
-
-if (result !== 42 || same !== 42) {
-  throw new Error(`expected 42, got ${String(result)} / ${String(same)}`);
+if (result !== 42) {
+  throw new Error(`expected 42, got ${String(result)}`);
 }
 ```
 
@@ -134,7 +130,7 @@ function returnsPromise(): Promise<number> {
 }
 const n = await new Try(returnsPromise).value();
 
-// Awaiting a non-async Try yields the Try instance, NOT the result.
+// Awaiting a Try instance directly yields the Try instance, NOT the result.
 // The instance is not thenable, so `await` cannot trigger execution.
 // Use .value() / .unwrap() / .error() / .result() instead.
 if ((result as { ok: boolean }).ok !== true || n !== 42) {
@@ -163,7 +159,7 @@ npm install @sentry/nextjs
 
 Supported version range: `>=8.0.0 <11.0.0`.
 
-**`await new Try(syncFn)` returns the `Try` instance** — This is expected behaviour. Awaiting a `Try` that wraps a non-async function (sync, or sync-returning-Promise) yields the `Try` instance itself because the instance is not thenable. Use `.value()`, `.unwrap()`, `.error()`, or `.result()` to retrieve the result.
+**`await new Try(fn)` returns the `Try` instance** — This is expected behaviour for every wrapped function (sync or async). `Try` instances are not thenable, so `await` cannot trigger execution. Use `.value()`, `.unwrap()`, `.error()`, or `.result()` to retrieve the result.
 
 ## Next Steps
 

src/__tests__/Try.test.ts

@@ -224,7 +224,8 @@ describe('Try', () => {
 
       await new Try(throwingFunction, params)
         .debug(false)
-        .breadcrumbs(['parameterKey']);
+        .breadcrumbs(['parameterKey'])
+        .value();
 
       expect(Sentry.addBreadcrumb).toHaveBeenCalledWith(
         expect.objectContaining({
@@ -1750,12 +1751,6 @@ describe('Try', () => {
 
       expect(awaited).toBe(t);
     });
-
-    it('AsyncFunction-wrapped Try IS thenable and await works', async () => {
-      const t = new Try(async () => 1);
-      expect('then' in t).toBe(true);
-      await expect(Promise.resolve(t)).resolves.toBe(1);
-    });
   });
 
   describe('.default() shares exec state with parent', () => {

src/__tests__/all-usecases.test.ts

@@ -116,31 +116,7 @@ describe('Result methods', () => {
 // --- PromiseLike / await behavior --------------------------------------
 
 describe('PromiseLike / await', () => {
-  it('await async Try resolves to T | undefined', async () => {
-    const result = await new Try(asyncNoArgs);
-    expectTypeOf(result).toEqualTypeOf<number | undefined>();
-    expect(result).toBe(42);
-  });
-
-  it('await async Try.default resolves to T | D', async () => {
-    const result = await new Try(asyncNoArgs).default('fallback' as const);
-    expectTypeOf(result).toEqualTypeOf<number | 'fallback'>();
-  });
-
-  it('async .then typechecks', async () => {
-    const result = await new Try(asyncNoArgs).then((v) => {
-      expectTypeOf(v).toEqualTypeOf<number | undefined>();
-      return v ?? 0;
-    });
-    expect(result).toBe(42);
-  });
-
-  it('sync .then type is never', () => {
-    const t = new Try(syncNoArgs);
-    expectTypeOf(t.then).toEqualTypeOf<never>();
-  });
-
-  it('sync Try has no runtime then (await returns instance as-is)', async () => {
+  it('Try has no runtime then (await returns instance as-is)', async () => {
     const t = new Try(syncNoArgs);
     expect((t as unknown as { then?: unknown }).then).toBeUndefined();
     const awaited = await (t as unknown as Promise<unknown>);

src/__tests__/coverage-gaps.test.ts

@@ -266,20 +266,6 @@ describe('coverage gaps', () => {
     });
   });
 
-  describe('Try thenable branch', () => {
-    it('then(null, reject) covers null onfulfilled branch', async () => {
-      async function asyncOk() {
-        return 7;
-      }
-      const t = new Try(asyncOk);
-      const value = await (t as unknown as PromiseLike<number>).then(
-        null,
-        () => -1,
-      );
-      expect(value).toBe(7);
-    });
-  });
-
   describe('extractDoctests untagged unterminated fence', () => {
     it('breaks scanning on untagged unterminated fence without throw', () => {
       const source = 'intro\n```js\nconst x = 1;\n';

src/__tests__/review-regressions.test.ts

@@ -144,25 +144,25 @@ describe('Regression: multi-CLI review findings', () => {
    * `Function.prototype.bind` output (constructor name = 'Function').
    * Bound async methods should still be thenable.
    */
-  describe('R-04 bound async functions are thenable', () => {
-    it('await new Try(asyncMethod.bind(instance)) executes and resolves', async () => {
+  describe('R-04 bound async functions resolve via .value()', () => {
+    it('new Try(asyncMethod.bind(instance)).value() executes and resolves', async () => {
       class C {
         async run() {
           return 42;
         }
       }
       const c = new C();
 
-      const result = await new Try(c.run.bind(c));
+      const result = await new Try(c.run.bind(c)).value();
 
       expect(result).toBe(42);
     });
 
-    it('Try(arrowReturningPromiseFromAsync) with type declared async should be thenable', async () => {
+    it('Try(arrowReturningPromiseFromAsync) with type declared async resolves via .value()', async () => {
       const asyncFn = async () => 'ok';
       const bound = asyncFn.bind(null);
 
-      const result = await new Try(bound);
+      const result = await new Try(bound).value();
 
       expect(result).toBe('ok');
     });

src/core/Try.ts

@@ -159,40 +159,6 @@ export class Try<
     this.config = { tags: {} };
     this.exec = { state: 'pending', finallyRan: new Set(), breadcrumbsEmitted: new Set() };
     this.local = { breadcrumbsAdded: false };
-    // Only `AsyncFunction`s are thenable: `installThenable()` defines an owned
-    // `.then` data property so `await new Try(asyncFn)` works without
-    // triggering execution at probe time. Non-async functions (including
-    // sync functions that happen to return a Promise) are NOT thenable —
-    // any thenability probe (Promise.resolve, util.inspect, jest deep-equal,
-    // Sentry serialization, ...) must never silently invoke the wrapped
-    // function. Use `.value()` / `.unwrap()` / `.error()` / `.result()`
-    // (which still handle Promise-returning sync fns via `execute()`).
-    if (fn.constructor.name === 'AsyncFunction') {
-      this.installThenable();
-    }
-  }
-
-  /**
-   * Install a thenable `.then` method directly on this instance for
-   * `AsyncFunction`-wrapped Try instances. Defers to `.value()` (never throws;
-   * returns the configured default on error) and wraps in `Promise.resolve(...)`
-   * so it also works once the underlying promise has settled.
-   */
-  private installThenable(): void {
-    const thenFn = (
-      onfulfilled?: ((value: unknown) => unknown) | null,
-      onrejected?: ((reason: unknown) => unknown) | null,
-    ): Promise<unknown> =>
-      Promise.resolve(this.value() as unknown).then(
-        onfulfilled ?? undefined,
-        onrejected ?? undefined,
-      );
-    Object.defineProperty(this, 'then', {
-      configurable: true,
-      enumerable: false,
-      writable: true,
-      value: thenFn,
-    });
   }
 
   /**
@@ -905,41 +871,4 @@ export class Try<
     return BreadcrumbExtractorUtil.extract(config, this.args, this.config.debug);
   }
 
-  /**
-   * Make the Try instance thenable so it can be `await`-ed directly (async only).
-   * This executes the underlying function with the current configuration and resolves
-   * with the same result as calling `.value()` (never throws, returns undefined on error).
-   *
-   * For sync wrapped functions, `.then` is typed as `never` to prevent misuse —
-   * use `.value()` / `.unwrap()` directly instead of awaiting.
-   *
-   * @example
-   * ```typescript
-   * // Direct await - equivalent to .value()
-   * const user = await new Try(fetchUser, userId)
-   *   .report('Failed to fetch user');
-   *
-   * // Can be used in Promise chains
-   * const result = await new Try(processData, input)
-   *   .default('fallback')
-   *   .then(data => data?.toUpperCase() || 'NO DATA');
-   *
-   * // Behaves like .value() - never throws
-   * const users = await new Try(fetchUsers); // undefined if error
-   * ```
-   */
-  declare then: IfPromise<
-    TReturn,
-    <TResult1 = Awaited<TReturn> | TDefault, TResult2 = never>(
-      onfulfilled?:
-        | ((
-            value: Awaited<TReturn> | TDefault,
-          ) => TResult1 | PromiseLike<TResult1>)
-        | null,
-      onrejected?:
-        | ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
-        | null,
-    ) => Promise<TResult1 | TResult2>,
-    never
-  >;
 }