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> {
    annotations: ExecutorAnnotations;
    invalidatedAt: number;
    isActive: boolean;
    isFulfilled: boolean;
    isInvalidated: boolean;
    isPending: boolean;
    isRejected: boolean;
    isSettled: boolean;
    key: any;
    manager: ExecutorManager;
    pendingPromise: null | AbortablePromise<Value>;
    reason: any;
    settledAt: number;
    task: null | ExecutorTask<Value>;
    value: undefined | Value;
    version: number;
    abort(reason?): void;
    activate(): (() => void);
    annotate(patch): void;
    clear(): void;
    execute(task): AbortablePromise<Value>;
    get(): Value;
    getOrAwait(): AbortablePromise<Value>;
    getOrDefault(): undefined | Value;
    getOrDefault<DefaultValue>(defaultValue): Value | DefaultValue;
    invalidate(invalidatedAt?): void;
    publish<Payload>(eventType, payload?): void;
    reject(reason, settledAt?): void;
    resolve(value, settledAt?): void;
    retry(): void;
    subscribe(listener): (() => void);
    toJSON(): ExecutorState<Value>;
}

Type Parameters

  • Value = any

    The value stored by the executor.

Hierarchy (view full)

Properties

annotations invalidatedAt isActive isFulfilled isInvalidated isPending isRejected isSettled key manager pendingPromise reason settledAt task value version

Methods

abort activate annotate clear execute get getOrAwait getOrDefault invalidate publish reject resolve retry subscribe toJSON

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 pendingPromise

pendingPromise: 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?): 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

    • Optional reason: 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.

      • (): void

      • Returns void

annotate

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): 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

getOrAwait

getOrDefault

invalidate

  • invalidate(invalidatedAt?): void

  • If the executor is settled the result is masted as invalidated.

    Parameters

    • Optional invalidatedAt: number

      The timestamp when the executor result was invalidated.

    Returns void

publish

  • publish<Payload>(eventType, payload?): void

  • Publishes the event for subscribers of the executor and its manager.

    Type Parameters

    • Payload

      The payload published with the event.

    Parameters

    • eventType: "pending" | "activated" | "fulfilled" | "rejected" | string & {} | "attached" | "detached" | "deactivated" | "aborted" | "cleared" | "invalidated" | "annotated" | "plugin_configured"

      The type of the published event.

    • Optional payload: Payload

      The optional payload associated with the event.

    Returns void

reject

  • reject(reason, settledAt?): void

  • Instantly aborts pending execution and rejects the executor with the reason.

    Parameters

    • reason: any

      The reason of failure.

    • Optional settledAt: number

      The timestamp when the reason was acquired.

    Returns void

resolve

  • resolve(value, settledAt?): 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.

    • Optional settledAt: number

      The timestamp when the value was acquired. If value is a promise then the timestamp is ignored.

    Returns void

retry

subscribe

  • subscribe(listener): (() => void)

  • Subscribes the listener to changes of the observed value.

    Parameters

    • listener: ((value) => void)

      The listener to subscribe.

    Returns (() => void)

      • (): void

      • Returns void

toJSON

Settings

Member Visibility

Theme

On This Page

annotationsinvalidatedAtisActiveisFulfilledisInvalidatedisPendingisRejectedisSettledkeymanagerpendingPromisereasonsettledAttaskvalueversionabortactivateannotateclearexecutegetgetOrAwaitgetOrDefaultinvalidatepublishrejectresolveretrysubscribetoJSON