@escapace/deferred

Deferred promise that exposes resolve() and reject() as methods, with synchronous access to the promise's settlement status.

Installation

pnpm add @escapace/deferred

Usage

Each deferred tracks two axes from the promises specification — state and fate. fate locks synchronously when resolve() or reject() is called. state updates asynchronously via microtask.

import { Deferred } from '@escapace/deferred'

const deferred = new Deferred<string>()

// fate is locked synchronously; state updates on the next microtask
deferred.resolve('hello')

deferred.fate // 'resolved' — outcome is determined
deferred.state // 'pending'  — settlement has not propagated yet

await deferred.promise

deferred.state // 'fulfilled' — settlement has propagated

Rejection works the same way — both resolve() and reject() lock the fate:

const deferred = new Deferred<string>()

deferred.reject(new Error('timeout'))

deferred.fate // 'resolved'
deferred.state // 'pending'

await deferred.promise.catch(() => {})

deferred.state // 'rejected'

Calling resolve() or reject() a second time throws:

const deferred = new Deferred<string>()

deferred.resolve('first')
deferred.resolve('second') // throws "Deferred fate is already resolved"

Introspection helpers

const deferred = new Deferred<number>()

deferred.isPending() // true
deferred.isSettled() // false — not yet fulfilled or rejected
deferred.isResolved() // false — fate is still unresolved

deferred.resolve(42)
await deferred.promise

deferred.isFulfilled() // true
deferred.isSettled() // true
deferred.isResolved() // true
deferred.isRejected() // false

API

class Deferred ↗

Promise whose outcome can be determined externally.

export declare class Deferred<T>

Type Parameters

Parameter	Description
T	Fulfillment value type of the underlying promise.

Remarks

Wraps a standard Promise and exposes its resolve and reject callbacks as instance methods. The Deferred.fate and Deferred.state fields provide synchronous introspection into the promise lifecycle.

new Deferred

Constructs a new instance of the Deferred class

constructor()

Deferred.isFulfilled

Indicates whether the promise has fulfilled.

isFulfilled(): boolean;

Returns

true when Deferred.state is "fulfilled".

Deferred.isPending

Indicates whether the promise is still pending.

isPending(): boolean;

Returns

true when Deferred.state is "pending".

Deferred.isRejected

Indicates whether the promise has rejected.

isRejected(): boolean;

Returns

true when Deferred.state is "rejected".

Deferred.isResolved

Indicates whether the deferred fate has been locked in.

isResolved(): boolean;

Returns

true when Deferred.fate is "resolved".

Remarks

Returns true after either Deferred.resolve or Deferred.reject has been called. A resolved fate does not imply fulfillment — rejected deferreds are also resolved.

Deferred.isSettled

Indicates whether the promise has settled (fulfilled or rejected).

isSettled(): boolean;

Returns

true when Deferred.state is not "pending".

Deferred.reject

Rejects the underlying promise.

reject(reason?: any): void;

Parameters

Parameter	Type	Description
reason	any	Rejection reason forwarded to the underlying promise.

Throws

When the deferred fate is already resolved.

Remarks

Sets Deferred.fate to "resolved" synchronously. Deferred.state transitions to "rejected" asynchronously on the next microtask.

Deferred.resolve

Resolves the underlying promise.

resolve(value?: PromiseLike<T> | T): void;

Parameters

Parameter	Type	Description
value	PromiseLike<T> | T	Fulfillment value or thenable forwarded to the underlying promise.

Throws

When the deferred fate is already resolved.

Remarks

Sets Deferred.fate to "resolved" synchronously. Deferred.state transitions to "fulfilled" asynchronously on the next microtask. When value is a PromiseLike, the state remains "pending" until that thenable settles.

Deferred.fate

Whether the deferred has been locked in.

fate: DeferredFate

Remarks

Set to "resolved" by either Deferred.resolve or Deferred.reject. A resolved fate means the outcome is determined; it does not imply fulfillment.

Deferred.promise

Underlying promise whose outcome is controlled by this deferred.

promise: Promise<T>

Deferred.state

Current settlement state of the underlying promise.

state: DeferredState

Remarks

Mirrors the internal [[PromiseState]] slot. Updated asynchronously via microtask after Deferred.resolve or Deferred.reject is called, so a brief window exists where Deferred.fate is "resolved" but this field is still "pending".

const DEFERRED_ERROR_ALREADY_RESOLVED ↗

Error message thrown when attempting to resolve or reject an already-resolved deferred.

DEFERRED_ERROR_ALREADY_RESOLVED = 'Deferred fate is already resolved'

const DEFERRED_FATE_RESOLVED ↗

Fate value indicating the deferred outcome has been determined.

DEFERRED_FATE_RESOLVED: 'resolved'

const DEFERRED_FATE_UNRESOLVED ↗

Fate value indicating the deferred outcome has not yet been determined.

DEFERRED_FATE_UNRESOLVED: 'unresolved'

const DEFERRED_STATE_FULFILLED ↗

State value indicating the promise completed successfully.

DEFERRED_STATE_FULFILLED: 'fulfilled'

const DEFERRED_STATE_PENDING ↗

State value indicating the promise has not yet settled.

DEFERRED_STATE_PENDING: 'pending'

const DEFERRED_STATE_REJECTED ↗

State value indicating the promise failed.

DEFERRED_STATE_REJECTED: 'rejected'

type DeferredFate ↗

Possible fates of a Deferred: "resolved" or "unresolved".

export type DeferredFate = typeof DEFERRED_FATE_RESOLVED | typeof DEFERRED_FATE_UNRESOLVED

type DeferredState ↗

Possible states of a Deferred: "fulfilled", "pending", or "rejected".

export type DeferredState =
  | typeof DEFERRED_STATE_FULFILLED
  | typeof DEFERRED_STATE_PENDING
  | typeof DEFERRED_STATE_REJECTED