@azure/core-lro

Azure Core LRO client library for JavaScript

This is the default implementation of long running operations in Azure SDK JavaScript client libraries which work in both the browser and NodeJS. This library is primarily intended to be used in code generated by the TypeSpec @azure-tools/typespec-ts emitter.

@azure/core-lro follows The Azure SDK Design Guidelines for Long Running Operations

Key links:

• Source code
• Package (npm)
• API Reference Documentation
• Samples

Getting started

Currently supported environments

• LTS versions of Node.js
• Latest versions of Safari, Chrome, Edge, and Firefox.

Installation

This package is primarily used in generated code and not meant to be consumed directly by end users.

Key concepts

PollerLike

A poller is an object that can poll the long running operation on the server for its state until it reaches a terminal state. It also extends Promise<TResult>, so you can await it directly to get the final result. It provides the following:

• operationState: a property that returns the current state of the operation, typed as a type that extends OperationState. It is undefined if the poller has not been submitted yet.
• result: a property that returns the result of the operation when it completes and undefined otherwise
• isDone: a property that returns whether the operation is in a terminal state
• onProgress: registers callback functions to be called every time a polling response is received
• poll: sends a single polling request
• pollUntilDone: returns a promise that will resolve with the result of the operation
• serialize: returns a promise that resolves to a serialized representation of the poller's state
• submitted: returns a promise that resolves when the poller has been submitted successfully

OperationState

A type for the operation state. It contains a status field with the following possible values: notStarted, running, succeeded, failed, and canceled. It can be accessed as follows:

switch (poller.operationState?.status) {
  case "succeeded": // return poller.result;
  case "failed": // throw poller.operationState?.error;
  case "canceled": // throw new Error("Operation was canceled");
  case "running": // ...
  case "notStarted": // ...
}

createHttpPoller

A function that returns an object of type PollerLike. This poller behaves as follows in the presence of errors:

• calls to poll and pollUntilDone will throw an error in case the operation has failed or canceled unless the resolveOnUnsuccessful option was set to true.
• poller.operationState?.status will be set to "failed" or "canceled" when either the operation fails or it returns an error response.

Examples

Examples can be found in the samples folder.

Troubleshooting

Logging

Logs can be added at the discretion of the library implementing the Long Running Operation poller. Packages inside of azure-sdk-for-js use @azure/logger.

Next steps

Please take a look at the samples directory for detailed examples on how to use this library.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

Testing

To run our tests, first install the dependencies (with pnpm install), then run the unit tests with: pnpm run test:node.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.

Similar packages

Other packages similar to @azure/core-lro

async

The 'async' package provides utilities for working with asynchronous JavaScript, including control flow, iteration, and utilities functions. While it doesn't specifically target long-running operations, it offers tools that could be used to manage asynchronous tasks and operations, which could indirectly support LRO scenarios. However, it lacks the direct LRO management and polling capabilities of @azure/core-lro.

rxjs

RxJS is a library for reactive programming using Observables, to make it easier to compose asynchronous or callback-based code. This can be particularly useful for managing streams of events or asynchronous tasks, which could include long-running operations. However, RxJS does not provide specific abstractions for LROs like @azure/core-lro does, focusing instead on a broader set of reactive programming tools.