`mapOk` sync throw creates an unhandled rejection and leaves the Future permanently unsettled

[baptou12]

When the callback passed to mapOk throws synchronously, the error escapes as an unhandled rejection. The resulting Future never resolves, making it impossible for any downstream consumer to handle the error.

Reproduction

import { Future, Result } from "@swan-io/boxed";

process.on("unhandledRejection", (e) =>
  console.log("unhandledRejection:", e),
);

const future = Future.fromPromise(Promise.resolve({ name: null }))
  .mapOk((data) => data.name.toUpperCase()); // throws TypeError

// None of these ever fire:
future.tap((result) => console.log("tap:", result));
future.toPromise().then(console.log).catch(console.log);
future.resultToPromise().then(console.log).catch(console.log);

// Output: unhandledRejection: TypeError: Cannot read properties of null (reading 'toUpperCase')
// → tap, toPromise, resultToPromise never settle

What happens

When the callback passed to mapOk throws, the exception escapes the Future abstraction. The error becomes an unhandled Promise rejection and the derived Future never settles, leaving downstream consumers hanging.

Expected behavior

The throw should be caught and the Future should resolve with Result.Error(thrownError), so that .mapError, .tap, .resultToPromise etc. can handle it normally.

Workaround

Using mapOkToResult + Result.fromExecution works:

Future.fromPromise(Promise.resolve({ name: null }))
  .mapOkToResult((data) =>
    Result.fromExecution(() => data.name.toUpperCase()),
  )
  .tap(console.log);
// → Result.Error(TypeError: Cannot read properties of null ...)

Suggested fix

Make mapOk internally delegate to mapOkToResult + Result.fromExecution:

mapOk(func) {
  return this.mapOkToResult((value) =>
    Result.fromExecution(() => func(value))
  );
}

Same issue likely applies to map, flatMapOk, and other methods that invoke user callbacks during resolution.

Note: since JavaScript allows throwing arbitrary values, this would result in Result<_, unknown>, consistent with Result.fromExecution.

Context

We hit this in a NestJS/Fastify backend. A corrupted database record caused mapOk to throw during entity mapping. The HTTP request hung indefinitely because the Future never settled and no response was sent. The only trace was a logged unhandled rejection.

Version: 3.2.1

[zoontek]

@baptou12 There's no issue here, the Promise resolves, so data is { name: null } and you can't call .toUpperCase() on it:

I guess you expect a behavior similar to Promise, where items throwed in .then(() => {}) are catched, but this is impossible to type as literally anything could be thrown.

[bloodyowl]

@baptou12 yeah, as @zoontek said, this would make the library pointless because caught exceptions can only be typed as any in TypeScript. this behavior in promises is one the reasons why the Promise type only has the fulfillment type parameter and not the error one.

[baptou12]

Thanks for your time :-)

The issue isn’t that data.name is null — the throw is intentional. The problem is what happens afterward.

When a callback passed to mapOk throws synchronously:

• the exception escapes the Future abstraction
• it becomes an unhandledRejection
• and the derived Future never settles (tap, toPromise, resultToPromise never resolve)

So downstream consumers cannot handle the error at all, which can cause real hangs in production.

The key point to us is: a thrown exception in a callback should not break the Future chain or leave it pending.

[zoontek]

The key point to us is: a thrown exception in a callback should not break the Future chain or leave it pending.

It's impossible. Let's say you call a function that throws "banana" and the Future abstraction would catch it, like a Promise do. This makes the Future typing impossible, as it should be Future<Result<YourData, YourErrors | "banana">>, and there's no way to achieve that in TS.

[baptou12]

Ok, I get the typing point and you’re right: my proposed change would effectively alter mapOk’s return typing (because caught exceptions are unknown), so doing that silently inside mapOk isn’t OK.

However, the core problem I’m reporting is not “data.name is null” nor “please catch exceptions while keeping perfect types.” The real issue, I think, is runtime behavior: when the callback passed to mapOk throws synchronously, the derived Future never settles. It stays pending forever, while the error escapes as an unhandledRejection.

That’s a footgun in production: downstream consumers (tap, toPromise, resultToPromise, HTTP handlers, etc.) can’t observe or handle anything because there is nothing to handle — the chain is just stuck.

[bloodyowl]

@baptou12 the workaround you shared initially is the recommended way to deal with such cases

[baptou12]

Another option to avoid degrading the current methods would be to introduce a panic channel alongside the existing error channel.

I also have an example MR ready that demonstrates this approach (need rework) : #102

What do you think ?