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 an execution state changes.

interface Executor<Value = any> {
    annotations: ExecutorAnnotations;
    invalidatedAt: number;
    isActive: boolean;
    isFulfilled: boolean;
    isInvalidated: boolean;
    isPending: boolean;
    isRejected: boolean;
    isSettled: boolean;
    key: any;
    manager: ExecutorManager;
    promise: null | AbortablePromise<Value>;
    reason: any;
    settledAt: number;
    task: null | ExecutorTask<Value>;
    value: undefined | Value;
    version: number;
    abort(reason?: unknown): void;
    activate(): () => void;
    annotate(patch: ExecutorAnnotations): void;
    clear(): void;
    execute(task: ExecutorTask<Value>): AbortablePromise<Value>;
    get(): Value;
    getOrAwait(): AbortablePromise<Value>;
    getOrDefault(): undefined | Value;
    getOrDefault<DefaultValue>(
        defaultValue: DefaultValue,
    ): Value | DefaultValue;
    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;
    toJSON(): ExecutorState<Value>;
}

Type Parameters

Value = any
The value stored by the executor.

Hierarchy (View Summary)

ReadonlyExecutor<Value>
- Executor

Properties

`Readonly`annotations

annotations: ExecutorAnnotations

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 then 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 Executor.manager.

`Readonly`manager

manager: ExecutorManager

The manager that created the executor.

`Readonly`promise

promise: null | AbortablePromise<Value>

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.

`Readonly`task

task: null | ExecutorTask<Value>

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

`Readonly`value

value: undefined | Value

The value of the latest fulfillment.

Note: An executor may still have value even if it was rejected. Use get, getOrDefault, or getOrAwait to retrieve a value of the 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. Value (or error) returned from pending task callback is ignored. The signal passed to the executed task callback is aborted.
Parameters
- Optionalreason: unknown
  The abort reason that is used for rejection of the pending task promise.
Returns void

activate

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

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: ExecutorAnnotations): void
Assigns patch to existing annotations.
Parameters
- patch: ExecutorAnnotations
  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>): 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>
  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. Then, the returned promise is 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, then the returned promise is rejected with the AbortError.

Returns AbortablePromise<Value>
Inherited from ReadonlyExecutor.getOrAwait

getOrDefault

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

Returns undefined | Value
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 default value.
Parameters
- defaultValue: DefaultValue
  The default value.
Returns Value | DefaultValue
Inherited from ReadonlyExecutor.getOrDefault

invalidate

invalidate(invalidatedAt?: number): void
If the executor is settled the result is masted as invalidated.
Parameters
- OptionalinvalidatedAt: number
  The timestamp when the executor result was invalidated.
Returns void

publish

publish(event: PartialExecutorEvent): void
Publishes the event for 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.
Returns void

resolve

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

Note: If value is a promise-like then execute is implicitly called which replaces the task.
Parameters
- value: Value | PromiseLike<Value>
  The value.
- OptionalsettledAt: number
  The timestamp when the value was acquired. If value is a promise then the timestamp is ignored.
Returns void

retry

retry(): void
If the executor isn't pending then the latest task is executed again. If there's no task then 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

toJSON

toJSON(): ExecutorState<Value>
Returns the serializable executor state.

Returns ExecutorState<Value>
Inherited from ReadonlyExecutor.toJSON

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

Readonlytask

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 undefined | Value

Type Parameters

Parameters

Returns Value | DefaultValue

invalidate

Parameters

Returns void

publish

Parameters

Returns void

reject

Parameters

Returns void

resolve

Parameters

Returns void

retry

Returns void

subscribe

Parameters

Returns () => void

toJSON

Returns ExecutorState<Value>

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`task

`Readonly`value

`Readonly`version