@azure/core-lro

What is @azure/core-lro?

The @azure/core-lro package provides a framework for building and working with long-running operations (LROs) in Azure services. It offers a standardized way to poll for the status of these operations and retrieve the final results, abstracting the complexity involved in handling LROs.

What are @azure/core-lro's main functionalities?

Creating and managing long-running operations

This feature allows developers to implement custom pollers for managing long-running operations. The code sample demonstrates how to extend the Poller class to create a custom LRO poller.

const { Poller } = require('@azure/core-lro');

class MyLroPoller extends Poller {
  async cancelOperation() {
    // Cancel the operation if supported
  }

  async delay() {
    // Implement delay between polls
  }
}

const myPoller = new MyLroPoller();
await myPoller.pollUntilDone();

Polling for operation status

This feature enables polling for the status of a long-running operation until it is completed. The code sample shows how to use the Poller class to poll an operation until it's done.

const { Poller } = require('@azure/core-lro');

async function pollOperation(operation) {
  const poller = new Poller({
    operation,
  });

  return await poller.pollUntilDone();
}

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.

README

Azure Core LRO client library for JavaScript

@azure/core-lro is a JavaScript library that manages long running operations (LROs) against Azure services. Until completion, such operations require consecutive calls to Azure services to update a local representation of the remote operation status.

Please note: This library is included with other Azure SDK libraries that need it. It should not be used as a direct dependency in your projects.

@azure/core-lro is made following our Long Running Operations guidelines

Key links:

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

Getting started

Install the package

To install this library for a project under the azure-sdk-for-js, make sure you are at the root of that project, then use Rush as follows:

rush add -p @azure/core-lro

To install this package outside of the azure-sdk-for-js, use npm install --save @azure/core-lro.

Configure TypeScript

TypeScript users need to have Node type definitions installed:

npm install @types/node

They will also need to enable compilerOptions.allowSyntheticDefaultImports in their tsconfig.json. Note that if you have enabled compilerOptions.esModuleInterop, allowSyntheticDefaultImports is enabled by default. See TypeScript's compiler options handbook for more information.

Key concepts

@azure/core-lro makes a distinction between the Long Running Operation and its Poller.

• Whenever we talk about an operation, we mean the static representation of a Long Running Operation. Any operation will have a definition of a state, which has an opinionated default set of properties. The definition of the operation will also have functions that will define how to request new information about the pending operation, how to request its cancellation, and how to serialize it.
• A Poller is an object who's main function is to interact with an operation until the poller is manually stopped, the operation finishes (either by succeeding or failing) or if a manual request to cancel the operation has succeeded.
  Some characteristics of the pollers are:
  • Pollers show the status of the polling behavior.
  • Pollers support manual as well as automatic polling.
  • Pollers are serializable and can resume from a serialized operation.
  • Pollers also specify how much of the operation's state is going to be available to the public.
• A PollerLike is the public interface of a Poller, which allows for different implementations to be used.

Examples

You will be able to find some working examples of an implementation of an operation and a poller in:

• The @azure/core-lro samples.
• The @azure/core-lro tests.

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 npm install or rush install), then run the unit tests with: npm run unit-test.

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.