@azure/core-lro package

  • Reference

Classes

LroEngine

The LRO Engine, a class that performs polling.
Poller

A class that represents the definition of a program that polls through consecutive requests until it reaches a state of completion.

A poller can be executed manually, by polling request by request by calling to the poll() method repeatedly, until its operation is completed. It also provides a way to wait until the operation completes, by calling pollUntilDone() and waiting until the operation finishes. Pollers can also request the cancellation of the ongoing process to whom is providing the underlying long running operation.

const poller = new MyPoller();

// Polling just once:
await poller.poll();

// We can try to cancel the request here, by calling:
//
//     await poller.cancelOperation();
//

// Getting the final result:
const result = await poller.pollUntilDone();

The Poller is defined by two types, a type representing the state of the poller, which must include a basic set of properties from PollOperationState<TResult>, and a return type defined by TResult, which can be anything.

The Poller class implements the PollerLike interface, which allows poller implementations to avoid having to export the Poller's class directly, and instead only export the already instantiated poller with the PollerLike type.

class Client {
  public async makePoller: PollerLike<MyOperationState, MyResult> {
    const poller = new MyPoller({});
    // It might be preferred to return the poller after the first request is made,
    // so that some information can be obtained right away.
    await poller.poll();
    return poller;
  }
}

const poller: PollerLike<MyOperationState, MyResult> = myClient.makePoller();

A poller can be created through its constructor, then it can be polled until it's completed. At any point in time, the state of the poller can be obtained without delay through the getOperationState method. At any point in time, the intermediate forms of the result type can be requested without delay. Once the underlying operation is marked as completed, the poller will stop and the final value will be returned.

const poller = myClient.makePoller();
const state: MyOperationState = poller.getOperationState();

// The intermediate result can be obtained at any time.
const result: MyResult | undefined = poller.getResult();

// The final result can only be obtained after the poller finishes.
const result: MyResult = await poller.pollUntilDone();
PollerCancelledError

When the operation is cancelled, the poller will be rejected with an instance of the PollerCancelledError.
PollerStoppedError

When a poller is manually stopped through the stopPolling method, the poller will be rejected with an instance of the PollerStoppedError.

Interfaces

CreateHttpPollerOptions

Options for createPoller.
LongRunningOperation

Description of a long running operation.
LroEngineOptions

Options for the LRO poller.
LroResponse

The type of the response of a LRO.
OperationState

While the poller works as the local control mechanism to start triggering and wait for a long-running operation, OperationState documents the status of the remote long-running operation. It gets updated after each poll.
PollOperation

PollOperation is an interface that defines how to update the local reference of the state of the remote long running operation, just as well as how to request the cancellation of the same operation.

It also has a method to serialize the operation so that it can be stored and resumed at any time.
PollOperationState

PollOperationState contains an opinionated list of the smallest set of properties needed to define any long running operation poller.

While the Poller class works as the local control mechanism to start triggering, wait for, and potentially cancel a long running operation, the PollOperationState documents the status of the remote long running operation.

It should be updated at least when the operation starts, when it's finished, and when it's cancelled. Though, implementations can have any other number of properties that can be updated by other reasons.
PollerLike

Abstract representation of a poller, intended to expose just the minimal API that the user needs to work with.
RawResponse

Simple type of the raw response.
SimplePollerLike

A simple poller interface.

Type Aliases

CancelOnProgress

CancelOnProgress is used as the return value of a Poller's onProgress method. When a user invokes onProgress, they're required to pass in a function that will be called as a callback with the new data received each time the poll operation is updated. onProgress returns a function that will prevent any further update to reach the original callback.
LroResourceLocationConfig

The potential location of the result of the LRO if specified by the LRO extension in the swagger.
OperationStatus

The set of possible states an operation can be in at any given time.
PollProgressCallback

PollProgressCallback is the type of the callback functions sent to onProgress. These functions will receive a TState that is defined by your implementation of the Poller class.

Functions

createHttpPoller<TResult, TState>(LongRunningOperation<unknown>, CreateHttpPollerOptions<TResult, TState>)

Creates a poller that can be used to poll a long-running operation.

Function Details

createHttpPoller<TResult, TState>(LongRunningOperation<unknown>, CreateHttpPollerOptions<TResult, TState>)

Creates a poller that can be used to poll a long-running operation.

function createHttpPoller<TResult, TState>(lro: LongRunningOperation<unknown>, options?: CreateHttpPollerOptions<TResult, TState>): Promise<SimplePollerLike<TState, TResult>>

Parameters

lro

LongRunningOperation<unknown>

Description of the long-running operation

options

CreateHttpPollerOptions<TResult, TState>

options to configure the poller

Returns

Promise<SimplePollerLike<TState, TResult>>

an initialized poller