@azure/core-lro 3.0.0-beta.1 → 3.0.0

package/.tshy/esm.json

@@ -1,12 +0,0 @@
-{
-  "extends": "./build.json",
-  "include": [
-    "../src/**/*.ts",
-    "../src/**/*.mts",
-    "../src/**/*.tsx"
-  ],
-  "exclude": [],
-  "compilerOptions": {
-    "outDir": "../.tshy-build/esm"
-  }
-}

package/.tshy/react-native.json

@@ -1,12 +0,0 @@
-{
-  "extends": "./build.json",
-  "include": [
-    "../src/**/*.ts",
-    "../src/**/*.mts",
-    "../src/**/*.tsx"
-  ],
-  "exclude": [],
-  "compilerOptions": {
-    "outDir": "../.tshy-build/react-native"
-  }
-}

package/CHANGELOG.md

@@ -1,179 +0,0 @@
-# Release History
-
-## 3.0.0-beta.1 (2024-02-25)
-
-Initial implementation of next-generation for Long Running Operations (LROs) in which we deprecate the `LroEngine` support and change poller creation to a synchronized way.
-
-- `LroEngine` is deprecated and no long supported
-- The return type of `createHttpPoller` is changed from `Promise<SimplePollerLike>` to `PollerLike`
-- Some interfaces are renamed. `SimplePollerLike` is renamed as `PollerLike`, `LroResponse` is renamed as `OperationResponse` and `LroResourceLocationConfig` is to `ResourceLocationConfig`
-- Functions `getOperationState()`, `getResult()`, `isDone()` and `isStopped()` is changed to read-only attributes `operationState`, `result`, `isDone` and `isStopped`
-- Deprecated the attributes `requestMethod` and `requestPath` in `LongRunningOperation`
-- Added a new function `serialize` to help serialize the poller
-- Added a new function `submitted` to help wait for the poller submitted succesffully
-- Added a new parameter `TRequest` for `OperationResponse` to accept the raw request
-- Export the function `deserializeState` to the public
-
-## 2.6.0 (2024-02-01)
-
-### Other Changes
-
-- Search for the `resourceLocation` property in the raw response body if it cannot be found in the parsed response body.
-- Upgrade dependency `@azure/abort-controller` version to `^2.0.0`.
-
-## 2.5.4 (2023-07-24)
-
-### Bugs Fixed
-
-- Support non-standard PATCH operations.
-
-## 2.5.3 (2023-05-04)
-
-### Other Changes
-
-- Include detailed error information in failed polling error messages.
-
-## 2.5.2 (2023-04-06)
-
-### Bugs Fixed
-
-- Change the logging level for unrecognized operation statuses from warning to verbose.
-
-## 2.5.1 (2023-02-02)
-
-### Bugs Fixed
-
-- The operation will be considered failed when an HTTP response error is received and not when any arbitrary error is raised.
-
-## 2.5.0 (2023-01-10)
-
-### Other Changes
-
-- poll() is optimized to no longer send a polling request if the operation is already in a terminal state.
-
-## 2.4.0 (2022-09-29)
-
-### Features Added
-
-- Add `resolveOnUnsuccessful` to `CreateHttpPollerOptions` and `LroEngineOptions` to control whether to throw an error if the operation failed or was canceled.
-
-### Bugs Fixed
-
-- Precisely detect when an operation failed without relying on exceptions raised by the underlying core library.
-- Handle bad status fields.
-
-## 2.3.1 (2022-09-09)
-
-### Bugs Fixed
-
-- Add missing support for fetching resources linked to in the body of the final polling response.
-
-## 2.3.0 (2022-09-01)
-
-### Features Added
-
-- Provides `createHttpPoller` which creates a simple poller that can work out of the box for most Azure long-running operations.
-- Deprecates `cancelOperation` in `PollerLike` because not every operation supports cancellation.
-
-## 2.2.5 (2022-08-08)
-
-### Bugs Fixed
-
-- `LroEngine` no longer throws an error when it receives a 204 polling response.
-
-### Other Changes
-
-- Support LROs with GET as the initial request method.
-- Better logging support for the operation and the poller.
-- Removed the unused dependency `@azure/core-tracing`.
-
-## 2.3.0-beta.1 (2022-05-18)
-
-### Features Added
-
-- `lroEngine` now supports cancellation of the long-running operation.
-
-### Other Changes
-
-- Removed the unused dependency `@azure/core-tracing`.
-
-## 2.2.4 (2022-03-07)
-
-### Bugs Fixed
-
-- Fix polling so that resources created in a different URL will be retrieved once polling is done. [PR #20656](https://github.com/Azure/azure-sdk-for-js/pull/20656)
-
-## 2.2.3 (2022-01-06)
-
-### Bugs Fixed
-
-- Fix an issue where we treat Retry-After value as milliseconds. It is actually in seconds. [PR #19479](https://github.com/Azure/azure-sdk-for-js/pull/19479)
-
-## 2.2.2 (2021-12-02)
-
-### Bugs Fixed
-
-- Fix LRO PATCH operations when their results are located in a different URL. [PR #18820](https://github.com/Azure/azure-sdk-for-js/pull/18820)
-
-## 2.2.1 (2021-09-30)
-
-### Bugs Fixed
-
-- Check for string type before calling toLowerCase(). [PR #17573](https://github.com/Azure/azure-sdk-for-js/pull/17573)
-
-### Other Changes
-
-- Updates package to work with the react native bundler. [PR #17783](https://github.com/Azure/azure-sdk-for-js/pull/17783)
-
-## 2.2.0 (2021-08-05)
-
-### Features Added
-
-- `LroEngine` supports a new `isDone()` function in its options bag which can be used to provide a custom logic for determining when an LRO finished processing.
-
-## 2.1.0 (2021-07-19)
-
-### Features Added
-
-- Provides a long-running operation engine.
-
-## 2.0.0 (2021-06-30)
-
-### New Features
-
-- Changed TS compilation target to ES2017 in order to produce smaller bundles and use more native platform features
-
-## 1.0.5 (2021-04-12)
-
-- No functionality changes from 1.0.4. This release is to correct an issue where 1.0.4 shipped with modules in the wrong format (cjs instead of es6.)
-
-## 1.0.4 (2021-03-30)
-
-- Bug fix: Fix an issue where we might return stale state if the `update` implementation reassigns `operation.state`.
-
-### Breaking Changes
-
-- Updated @azure/core-tracing to version `1.0.0-preview.11`. See [@azure/core-tracing CHANGELOG](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-tracing/CHANGELOG.md) for details about breaking changes with tracing.
-
-## 1.0.3 (2021-01-07)
-
-- Updates the `tslib` dependency to version 2.x.
-
-## 1.0.2 (2020-04-28)
-
-- Moved `@opentelemetry/types` to the `devDependencies`.
-
-## 1.0.1 (2020-02-28)
-
-- `getOperationState()` now returns `TState`.
-- `TState` of `PollerLike` can be a subset of `TState` of `Poller`,
-
-## 1.0.0 (2019-10-29)
-
-This release marks the general availability of the `@azure/core-lro` package.
-
-- Updated PollOperation to be more strictly typed.
-
-## 1.0.0-preview.1 (2019-10-22)
-
-- Initial implementation of an abstraction for Long Running Operations (LROs).

package/api-extractor.json

@@ -1,31 +0,0 @@
-{
-  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "mainEntryPointFilePath": "dist/esm/index.d.ts",
-  "docModel": {
-    "enabled": true
-  },
-  "apiReport": {
-    "enabled": true,
-    "reportFolder": "./review"
-  },
-  "dtsRollup": {
-    "enabled": true,
-    "untrimmedFilePath": "",
-    "publicTrimmedFilePath": "./dist/core-lro.d.ts"
-  },
-  "messages": {
-    "tsdocMessageReporting": {
-      "default": {
-        "logLevel": "none"
-      }
-    },
-    "extractorMessageReporting": {
-      "ae-missing-release-tag": {
-        "logLevel": "none"
-      },
-      "ae-unresolved-link": {
-        "logLevel": "none"
-      }
-    }
-  }
-}

package/config/rush-project.json

@@ -1,3 +0,0 @@
-{
-  "extends": "../../../../common/config/rush-project.json",
-}

package/core-lro.build.cache.error.log

@@ -1 +0,0 @@
-Unable to include "dist/node_modules/@azure/core-lro" in build cache. It is a symbolic link.

package/core-lro.build_samples.cache.log

@@ -1 +0,0 @@
-This project does not define the caching behavior of the "build:samples" command, so caching has been disabled.

package/core-lro.build_samples.log

@@ -1,2 +0,0 @@
-Invoking: echo Obsolete 
-Obsolete

package/core-lro.pack.cache.log

@@ -1 +0,0 @@
-This project does not define the caching behavior of the "pack" command, so caching has been disabled.

package/core-lro.pack.log

@@ -1 +0,0 @@
-Invoking: npm pack 2>&1 

package/docs/LROEngine.md

@@ -1,158 +0,0 @@
-# Modular Support for Long-Running Operations
-
-Long-running operations (LROs) are operations that the service _could_ take a long time to finish processing and they follow a common convention:
-
-- the customer first send an initiation request to the service, which in turn sends back a response, from which the customer can learn how to poll for the status of the operation, if it has not been completed already,
-- using their learnings, the customer polls the status of the operation until it is done,
-- again, using their learnings, the customer can now get the desired result of the operation once its status says it is done.
-
-Ideally, we can write an algorithm that implements this convention once and use it in all Azure clients for LRO APIs, however, in reality, this convention is implemented differently across Azure services. The good news is that the TypeScript Autorest extension is AFAIK able to generate code that implements those different ones, but this implementation has a couple of limitations:
-
-1. it is located in a few files that the code generator copies into every generated package that has LROs. So if in the future there is a bug fix needed in the LRO logic, the package has to be regenerated with the fix.
-2. it works only with clients that use `@azure/core-client`, so clients that use `@azure-rest/core-client` or `@azure/core-http` can not use this implementation as-is.
-
-To fix limitation #1, the most straightforward thing to do is to move those files into `@azure/core-lro`, but without fixing limitation #2 first, `@azure/core-lro` will have to depend on `@azure/core-client` in this case which will force clients that depend on `@azure/core-lro` but not necessarily depend on `@azure/core-client` to transitively depend on the latter, posing concerns about unnecessarily larger bundle sizes.
-
-This document presents a design that fixes limitation #2 and naturally fixes limitation #1 too.
-
-## Things to know before reading
-
-- Some details not related to the high-level concept are not illustrated; the scope of this is limited to the high-level shape and paradigms for the feature area.
-
-## Terminology
-
-- **Azure Async Operation**, **Body**, and **Location** are names for the LRO implementations currently supported in the TypeScript Autorest extension. They vary in how to calculate the path to poll from, the algorithm for detecting whether the operation has finished, and the location to retrieve the desired results from. Currently, these pieces of information can be calculated from the response received after sending the initiation request.
-
-## Why this is needed
-
-The China team is currently waiting for fixing limitation #1 which they regard as a blocker for GAing the TypeScript Autorest extension. Furthermore, having this LRO implementation being part of `@azure/core-lro` and not tied to `@azure/core-client` will significantly help streamline the underway effort to add convenience helpers for LROs in `@azure-rest` clients.
-
-## Design
-
-This document presents a design of an LRO engine to be part of `@azure/core-lro` and could be used by any client regardless of how it is implemented. Furthermore, specific implementations of the engine are also provided to be auto-generated by Autorest.
-
-The design consists of three main pieces:
-
-- an interface, named `LongRunningOperation<T>` which groups various primitives needed to implement LROs
-- a class, named `LroEngine`, that implements the LRO engine and its constructor takes as input an object that implements `LongRunningOperation<T>`
-- a class that implement `LongRunningOperation<T>` that works with clients that use either `@azure/core-http` and `@azure/core-client`. @joheredi also created one for `@azure-rest/core-client` in https://github.com/Azure/azure-sdk-for-js/pull/15898
-
-### `LongRunningOperation<T>`
-
-This interface contains two methods: **sendInitialRequest** and **sendPollRequest**.
-
-#### `sendInitialRequest`
-
-This method should be implemented to send the initial request to start the operation and it has the following signature:
-
-```ts
-sendInitialRequest: () => Promise<LroResponse<T>>
-```
-
-The method does not take the path or the HTTP request method as parameters because they're members of the interface since they're needed to control many aspects of subsequent polling. This is how this method can be implemented:
-
-```ts
-public async sendInitialRequest(): Promise<LroResponse<T>> {
-  return this.sendOperation(this.args, this.spec); // the class will have sendOperation, args, and spec as private fields
-}
-```
-
-#### `sendPollRequest`
-
-This method should be implemented to send a polling (GET) request, a request the service should respond to with the current status of the operation, and it has the following signature:
-
-```ts
-sendPollRequest: (path: string) => Promise<LroResponse<T>>;
-```
-
-This method takes the polling path as input and here is what a simplified implementation would look like:
-
-```ts
-  public async sendPollRequest(path: string): Promise<LroResponse<T>> {
-    return this.sendOperationFn(this.args, { // the class will have sendOperation, args, and spec as private fields
-      ...this.spec,
-      path,
-      httpMethod: "GET")
-    });
-  }
-```
-
-### `LroEngine`
-
-This class implements the `PollerLike` interface and does the heavy lifting for LROs and has the following type signature:
-
-```ts
-class LroEngine<TResult, TState extends PollOperationState<TResult>> extends Poller<TState, TResult>
-```
-
-The class also has the following constructor:
-
-```ts
-constructor(lro: LongRunningOperation<TResult>, options?: LroEngineOptions);
-```
-
-Currently `options` have `intervalInMs` to control the polling interval, `resumeFrom` to enable resuming from a serialized state, and `lroResourceLocationConfig` which could determine where to find the results of the LRO after the operation is finished. Typically, Autorest figures out the value for `LroResourceLocationConfig` from the `x-ms-long-running-operation-options` swagger extension. If there are new arguments to be added to the class, they could be added to the options type.
-
-### `LroImpl`
-
-This class implements the `LongRunningOperation<T>` interface and is auto-generated by Autorest. `LroImpl` needs access to a few pieces: operation specification and operation arguments and a primitive function that can take them as input to send a request and converts the received response into one of type `LroResponse<T>` which has both the flattened and the raw responses.
-
-## Usage examples
-
-### Create an object of `LroImpl`
-
-```ts
-const directSendOperation = async (
-  args: OperationArguments,
-  spec: OperationSpec
-): Promise<unknown> => {
-  return this.client.sendOperationRequest(args, spec);
-};
-const sendOperation = async (
-  args: OperationArguments,
-  spec: OperationSpec
-) => {
-  let currentRawResponse: FullOperationResponse | undefined = undefined;
-  const providedCallback = args.options?.onResponse;
-  const callback: RawResponseCallback = (
-    rawResponse: FullOperationResponse,
-    flatResponse: unknown
-  ) => {
-    currentRawResponse = rawResponse;
-    providedCallback?.(rawResponse, flatResponse);
-  };
-  const updatedArgs = {
-    ...args,
-    options: {
-      ...args.options,
-      onResponse: callback
-    }
-  };
-  const flatResponse = await directSendOperation(updatedArgs, spec);
-  return {
-    flatResponse,
-    rawResponse: {
-      statusCode: currentRawResponse!.status,
-      body: currentRawResponse!.parsedBody,
-      headers: currentRawResponse!.headers.toJSON()
-    }
-  };
-};
-
-const lro = new LroImpl(
-  sendOperation,
-  { options }, // arguments are just the operation options
-  spec
-);
-```
-
-### Using `LroEngine`
-
-```ts
-const pollerEngine = new LroEngine(lro, { intervalInMs: 2000 }); // lro was instantiated in the previous section
-const result = pollerEngine.pollUntilDone();
-```
-
-## Testing
-
-We have [extensive test suite for LROs](https://github.com/Azure/autorest.typescript/blob/main/packages/autorest.typescript/test/integration/lro.spec.ts) in the TypeScript code generator repo. I both added those tests here and re-implemented the [lro routes](https://github.com/Azure/autorest.testserver/blob/main/legacy/routes/lros.js) in the Autorest test server. For this to work, I created a [fairly low-level instantiation for `LongRunningOperation<T>` with just `@azure/core-rest-pipeline`](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-lro/test/utils/coreRestPipelineLro.ts).

package/review/core-lro.api.md

@@ -1,106 +0,0 @@
-## API Report File for "@azure/core-lro"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-
-import { AbortSignalLike } from '@azure/abort-controller';
-
-// @public
-export type CancelOnProgress = () => void;
-
-// @public
-export function createHttpPoller<TResult, TState extends OperationState<TResult>>(lro: LongRunningOperation, options?: CreateHttpPollerOptions<TResult, TState>): PollerLike<TState, TResult>;
-
-// @public
-export interface CreateHttpPollerOptions<TResult, TState> {
-    intervalInMs?: number;
-    processResult?: (result: unknown, state: TState) => TResult | Promise<TResult>;
-    resolveOnUnsuccessful?: boolean;
-    resourceLocationConfig?: ResourceLocationConfig;
-    restoreFrom?: string;
-    updateState?: (state: TState, response: OperationResponse) => void;
-    withOperationLocation?: (operationLocation: string) => void;
-}
-
-// @public
-export function deserializeState<TState>(serializedState: string): RestorableOperationState<TState>;
-
-// @public
-export interface LongRunningOperation<T = unknown> {
-    sendInitialRequest: () => Promise<OperationResponse<unknown>>;
-    sendPollRequest: (path: string, options?: {
-        abortSignal?: AbortSignalLike;
-    }) => Promise<OperationResponse<T>>;
-}
-
-// @public
-export interface OperationConfig {
-    initialUrl?: string;
-    metadata?: Record<string, string>;
-    operationLocation?: string;
-    requestMethod?: string;
-    resourceLocation?: string;
-}
-
-// @public
-export interface OperationResponse<T = unknown, TRequest extends RawRequest = RawRequest> {
-    flatResponse: T;
-    rawResponse: RawResponse<TRequest>;
-}
-
-// @public
-export interface OperationState<TResult> {
-    error?: Error;
-    result?: TResult;
-    status: OperationStatus;
-}
-
-// @public
-export type OperationStatus = "notStarted" | "running" | "succeeded" | "canceled" | "failed";
-
-// @public
-export interface PollerLike<TState extends OperationState<TResult>, TResult> extends Promise<TResult> {
-    readonly isDone: boolean;
-    readonly isStopped: boolean;
-    onProgress(callback: (state: TState) => void): CancelOnProgress;
-    readonly operationState: TState | undefined;
-    poll(options?: {
-        abortSignal?: AbortSignalLike;
-    }): Promise<TState>;
-    pollUntilDone(pollOptions?: {
-        abortSignal?: AbortSignalLike;
-    }): Promise<TResult>;
-    readonly result: TResult | undefined;
-    serialize(): Promise<string>;
-    submitted(): Promise<void>;
-}
-
-// @public
-export interface RawRequest {
-    body?: unknown;
-    method: string;
-    url: string;
-}
-
-// @public
-export interface RawResponse<TRequest extends RawRequest = RawRequest> {
-    body?: unknown;
-    headers: {
-        [headerName: string]: string;
-    };
-    request: TRequest;
-    statusCode: number;
-}
-
-// @public
-export type ResourceLocationConfig = "azure-async-operation" | "location" | "original-uri";
-
-// @public
-export type RestorableOperationState<T> = T & {
-    config: OperationConfig;
-};
-
-// (No @packageDocumentation comment for this package)
-
-```