LazyPromise presented as lightweight alternative to Effect library

LazyPromise introduces a lazy, cancelable primitive that only runs its constructor when a subscriber attaches, unlike the eager execution of native Promise. This behavior mirrors a single-shot Observable and allows each subscription to trigger independent work. The library keeps the familiar Promise-like API, map, catch, finally, all, race, while replacing microtasks with synchronous emission. By doing so, it aims to give developers finer control over when asynchronous work starts and when it can be stopped.

Adopting LazyPromise means shifting from fire-and-forget promises to an explicit subscribe/dispose model, which adds a small amount of boilerplate but gives guaranteed cleanup through the returned teardown function. Engineers must remember that values are emitted synchronously, so code that relied on the microtask ordering of promise.then may see different timing. The library also requires learning generator syntax (yield*) for async-await style flow, though the underlying mechanics are similar to async functions. These changes come with virtually no external dependencies beyond the core package.

LazyPromise is not a drop-in replacement for every use case; its lazy nature means it cannot be used where an eager promise is required to start work immediately, such as in race conditions that depend on immediate scheduling. Higher-order LazyPromise values are flattened, preventing patterns that nest promises as values, which may limit certain compositional patterns. While the library provides fromEager and toEager helpers to bridge with AbortController and standard Promise, the bridge adds an extra step and does not preserve the original eager semantics. Consequently, teams that rely heavily on microtask guarantees or promise chaining patterns may find LazyPromise unsuitable for those specific scenarios.