Interface Executor<Value>

Manages the async task execution process and provides ways to access execution results, abort or replace a task execution, and subscribe to execution state changes.

interface Executor<Value = any> {
    annotations: Record<PropertyKey, any>;
    invalidatedAt: number;
    isActive: boolean;
    isFulfilled: boolean;
    isInvalidated: boolean;
    isPending: boolean;
    isRejected: boolean;
    isSettled: boolean;
    key: any;
    manager: ExecutorManager;
    promise: AbortablePromise<Value> | null;
    reason: any;
    settledAt: number;
    task: ExecutorTask<Value> | null;
    value: Value | undefined;
    version: number;
    abort(reason?: unknown): void;
    activate(): () => void;
    annotate(patch: Record<PropertyKey, any>): void;
    clear(): void;
    execute(
        task: ExecutorTask<Value> | ExecutorTaskCallback<Value>,
    ): AbortablePromise<Value>;
    get(): Value;
    getOrAwait(): AbortablePromise<Value>;
    getOrDefault(): Value | undefined;
    getOrDefault<DefaultValue>(
        defaultValue: DefaultValue,
    ): Value | DefaultValue;
    getStateSnapshot(): ExecutorState<Value>;
    invalidate(invalidatedAt?: number): void;
    publish(event: PartialExecutorEvent): void;
    reject(reason: any, settledAt?: number): void;
    resolve(value: Value | PromiseLike<Value>, settledAt?: number): void;
    retry(): void;
    subscribe(listener: (value: ExecutorEvent) => void): () => void;
}

Type Parameters

Value = any
The value stored by the executor.

Hierarchy (View Summary)

ReadonlyExecutor<Value>
- Executor

Properties

`Readonly`annotations

annotations: Record<PropertyKey, any>

The map of annotations associated with the executor.

`Readonly`invalidatedAt

invalidatedAt: number

The timestamp when the executor was invalidated, or 0 if the executor isn't invalidated.

`Readonly`isActive

isActive: boolean

true if the executor was activated more times than deactivated.

`Readonly`isFulfilled

isFulfilled: boolean

true if the executor was fulfilled with a value, or false otherwise.

`Readonly`isInvalidated

isInvalidated: boolean

true if invalidate was called on a settled executor and a new settlement hasn't occurred yet.

`Readonly`isPending

isPending: boolean

true if the execution is currently pending, or false otherwise.

`Readonly`isRejected

isRejected: boolean

true if the executor was rejected with a reason, or false otherwise.

`Readonly`isSettled

isSettled: boolean

true if the executor is fulfilled or rejected, or false otherwise.

`Readonly`key

key: any

The key of this executor, unique in scope of the manager.

`Readonly`manager

manager: ExecutorManager

The manager that created the executor.

`Readonly`promise

promise: AbortablePromise<Value> | null

The promise of the pending task execution, or null if there's no pending task execution.

Note: This promise is aborted if the task is replaced. Use getOrAwait to wait until the executor becomes settled.

`Readonly`reason

reason: any

The reason of the latest failure.

Note: An executor may still have a rejection reason even if it was fulfilled. Check isRejected to ensure that an executor is actually rejected.

`Readonly`settledAt

settledAt: number

The timestamp when the executor was settled, or 0 if it isn't settled.

task

task: ExecutorTask<Value> | null

The latest task that was executed, or null if the executor hasn't executed any tasks.

Note: Unlike ReadonlyExecutor.task, this property is writable to allow plugins and advanced use cases to replace the stored task reference directly.

`Readonly`value

value: Value | undefined

The value of the latest fulfillment.

Note: An executor may still have a value even if it was rejected. Use get, getOrDefault, or getOrAwait to retrieve the value of a fulfilled executor.

`Readonly`version

version: number

The integer version of the state of this executor that is incremented every time the executor is mutated.

Methods

abort

abort(reason?: unknown): void
Instantly aborts pending execution and preserves available results as-is. The value (or error) returned from the pending task callback is ignored, and the signal passed to the task callback is aborted.

Note: This method only affects the pending task promise, not the executor's settled state. To also clear or reject the executor's value, call clear or reject afterwards.
Parameters
- Optionalreason: unknown
  The abort reason used to reject the pending task promise.
Returns void

activate

activate(): () => void
Marks the executor as being actively monitored by an external consumer.

An activated executor stays active until all returned deactivate callbacks are invoked.

Returns () => void
The callback that deactivates the executor if there are no more active consumers.

annotate

annotate(patch: Record<PropertyKey, any>): void
Merges the patch into the existing annotations.
Parameters
- patch: Record<PropertyKey, any>
  The patch containing new annotations.
Returns void

clear

clear(): void
Clears available results and doesn't affect the pending task execution.

The latest task can still be retried after the executor is cleared.

Returns void

execute

execute(
task: ExecutorTask<Value> | ExecutorTaskCallback<Value>,
): AbortablePromise<Value>
Executes a task and populates the executor with the returned result.

Instantly aborts pending execution (if any), marks the executor as pending and then invokes the task callback.

If a new task is executed before the returned promise is fulfilled then the signal is aborted and the result is ignored.
Parameters
- task: ExecutorTask<Value> | ExecutorTaskCallback<Value>
  The task object or the task callback that returns the new result for the executor to store.
Returns AbortablePromise<Value>
The promise that is resolved with the result of the task.

get

get(): Value
Returns a value if the executor is fulfilled. Throws a reason if the executor is rejected. Otherwise, throws an Error.

Returns Value
Inherited from ReadonlyExecutor.get

getOrAwait

getOrAwait(): AbortablePromise<Value>
Waits for the executor to become settled and non-pending. The returned promise is then resolved with a value if the executor is fulfilled, or rejected with a reason if the executor is rejected.

If the executor is detached during this operation, the returned promise is rejected with an AbortError.

Returns AbortablePromise<Value>
Inherited from ReadonlyExecutor.getOrAwait

getOrDefault

getOrDefault(): Value | undefined
Returns a value if the executor is fulfilled. Otherwise, returns undefined.

Returns Value | undefined
Inherited from ReadonlyExecutor.getOrDefault
getOrDefault<DefaultValue>(defaultValue: DefaultValue): Value | DefaultValue
Returns a value if the executor is fulfilled. Otherwise, returns the default value.
Type Parameters
- DefaultValue
  The type of the default value.
Parameters
- defaultValue: DefaultValue
  The default value.
Returns Value | DefaultValue
Inherited from ReadonlyExecutor.getOrDefault

getStateSnapshot

getStateSnapshot(): ExecutorState<Value>
Captures the snapshot of the current executor state.

Returns ExecutorState<Value>
Inherited from ReadonlyExecutor.getStateSnapshot

invalidate

invalidate(invalidatedAt?: number): void
If the executor is settled, marks the result as invalidated.
Parameters
- OptionalinvalidatedAt: number
  The timestamp to record as the invalidation time. Defaults to Date.now().
Returns void

publish

publish(event: PartialExecutorEvent): void
Publishes the event to subscribers of the executor and its manager.
Parameters
- event: PartialExecutorEvent
  The event to publish.
Returns void

reject

reject(reason: any, settledAt?: number): void
Instantly aborts pending execution and rejects the executor with the reason.
Parameters
- reason: any
  The reason of failure.
- OptionalsettledAt: number
  The timestamp when the reason was acquired. Defaults to Date.now().
Returns void

resolve

resolve(value: Value | PromiseLike<Value>, settledAt?: number): void
Aborts pending execution and fulfills the executor with the value.

Note: If the value is a PromiseLike, it is wrapped internally and the task is updated to reflect the pending resolution. This differs from passing a plain value, where settlement is immediate.
Parameters
- value: Value | PromiseLike<Value>
  The value.
- OptionalsettledAt: number
  The timestamp when the value was acquired. Ignored if value is a PromiseLike.
Returns void

retry

retry(): void
If the executor is not pending, the latest task is executed again. If there's no task then this is a no-op.

Returns void

subscribe(listener: (value: ExecutorEvent) => void): () => void
Subscribes the listener to changes of the observed value.
Parameters
- listener: (value: ExecutorEvent) => void
  The listener to subscribe.
Returns () => void
Inherited from ReadonlyExecutor.subscribe

Interface Executor<Value>

Type Parameters

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonlyannotations

ReadonlyinvalidatedAt

ReadonlyisActive

ReadonlyisFulfilled

ReadonlyisInvalidated

ReadonlyisPending

ReadonlyisRejected

ReadonlyisSettled

Readonlykey

Readonlymanager

Readonlypromise

Readonlyreason

ReadonlysettledAt

task

Readonlyvalue

Readonlyversion

Methods

abort

Parameters

Returns void

activate

Returns () => void

annotate

Parameters

Returns void

clear

Returns void

execute

Parameters

Returns AbortablePromise<Value>

get

Returns Value

getOrAwait

Returns AbortablePromise<Value>

getOrDefault

Returns Value | undefined

Type Parameters

Parameters

Returns Value | DefaultValue

getStateSnapshot

Returns ExecutorState<Value>

invalidate

Parameters

Returns void

publish

Parameters

Returns void

reject

Parameters

Returns void

resolve

Parameters

Returns void

retry

Returns void

subscribe

Parameters

Returns () => void

Settings

On This Page

`Readonly`annotations

`Readonly`invalidatedAt

`Readonly`isActive

`Readonly`isFulfilled

`Readonly`isInvalidated

`Readonly`isPending

`Readonly`isRejected

`Readonly`isSettled

`Readonly`key

`Readonly`manager

`Readonly`promise

`Readonly`reason

`Readonly`settledAt

`Readonly`value

`Readonly`version