[core-lro] Deprecate cancelOperation and introduce createPoller

sdk/core/core-lro/CHANGELOG.md

@@ -1,14 +1,11 @@
 # Release History
 
-## 2.2.6 (Unreleased)
+## 2.3.0 (Unreleased)
 
 ### Features Added
 
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Provides `createPoller` 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)
 

sdk/core/core-lro/package.json

@@ -2,7 +2,7 @@
   "name": "@azure/core-lro",
   "author": "Microsoft Corporation",
   "sdk-type": "client",
-  "version": "2.2.6",
+  "version": "2.3.0",
   "description": "Isomorphic client library for supporting long-running operations in node.js and browser.",
   "tags": [
     "isomorphic",
@@ -96,16 +96,13 @@
     "tslib": "^2.2.0"
   },
   "devDependencies": {
-    "@azure/core-http": "^2.0.0",
     "@azure/core-rest-pipeline": "^1.1.0",
     "@azure/eslint-plugin-azure-sdk": "^3.0.0",
     "@azure/dev-tool": "^1.0.0",
     "@azure/test-utils": "^1.0.0",
     "@microsoft/api-extractor": "7.18.11",
-    "@types/chai": "^4.1.6",
     "@types/mocha": "^7.0.2",
     "@types/node": "^12.0.0",
-    "chai": "^4.2.0",
     "cross-env": "^7.0.2",
     "eslint": "^8.0.0",
     "karma": "^6.2.0",
@@ -121,12 +118,10 @@
     "karma-sourcemap-loader": "^0.3.8",
     "mocha": "^7.1.1",
     "mocha-junit-reporter": "^2.0.0",
-    "npm-run-all": "^4.1.5",
     "nyc": "^15.0.0",
     "prettier": "^2.5.1",
     "rimraf": "^3.0.0",
     "ts-node": "^10.0.0",
-    "typescript": "~4.6.0",
-    "uglify-js": "^3.4.9"
+    "typescript": "~4.6.0"
   }
 }

sdk/core/core-lro/review/core-lro.api.md

@@ -10,11 +10,26 @@ import { AbortSignalLike } from '@azure/abort-controller';
 export type CancelOnProgress = () => void;
 
 // @public
-export interface LongRunningOperation<T> {
-    requestMethod: string;
-    requestPath: string;
-    sendInitialRequest: () => Promise<LroResponse<T>>;
-    sendPollRequest: (path: string) => Promise<LroResponse<T>>;
+export function createHttpPoller<TResult, TState extends OperationState<TResult>>(lro: LongRunningOperation, options?: CreateHttpPollerOptions<TResult, TState>): Promise<SimplePollerLike<TState, TResult>>;
+
+// @public
+export interface CreateHttpPollerOptions<TResult, TState> {
+    intervalInMs?: number;
+    processResult?: (result: unknown, state: TState) => TResult;
+    resourceLocationConfig?: LroResourceLocationConfig;
+    restoreFrom?: string;
+    updateState?: (state: TState, response: LroResponse) => void;
+    withOperationLocation?: (operationLocation: string) => void;
+}
+
+// @public
+export interface LongRunningOperation<T = unknown> {
+    requestMethod?: string;
+    requestPath?: string;
+    sendInitialRequest: () => Promise<LroResponse<unknown>>;
+    sendPollRequest: (path: string, options?: {
+        abortSignal?: AbortSignalLike;
+    }) => Promise<LroResponse<T>>;
 }
 
 // @public
@@ -37,11 +52,21 @@ export interface LroEngineOptions<TResult, TState> {
 export type LroResourceLocationConfig = "azure-async-operation" | "location" | "original-uri";
 
 // @public
-export interface LroResponse<T> {
+export interface LroResponse<T = unknown> {
     flatResponse: T;
     rawResponse: RawResponse;
 }
 
+// @public
+export interface OperationState<TResult> {
+    error?: Error;
+    result?: TResult;
+    status: OperationStatus;
+}
+
+// @public
+export type OperationStatus = "notStarted" | "running" | "succeeded" | "canceled" | "failed";
+
 // @public
 export abstract class Poller<TState extends PollOperationState<TResult>, TResult> implements PollerLike<TState, TResult> {
     constructor(operation: PollOperation<TState, TResult>);
@@ -58,7 +83,9 @@ export abstract class Poller<TState extends PollOperationState<TResult>, TResult
     poll(options?: {
         abortSignal?: AbortSignalLike;
     }): Promise<void>;
-    pollUntilDone(): Promise<TResult>;
+    pollUntilDone(pollOptions?: {
+        abortSignal?: AbortSignalLike;
+    }): Promise<TResult>;
     stopPolling(): void;
     toString(): string;
 }
@@ -70,6 +97,7 @@ export class PollerCancelledError extends Error {
 
 // @public
 export interface PollerLike<TState extends PollOperationState<TResult>, TResult> {
+    // @deprecated
     cancelOperation(options?: {
         abortSignal?: AbortSignalLike;
     }): Promise<void>;
@@ -81,7 +109,9 @@ export interface PollerLike<TState extends PollOperationState<TResult>, TResult>
     poll(options?: {
         abortSignal?: AbortSignalLike;
     }): Promise<void>;
-    pollUntilDone(): Promise<TResult>;
+    pollUntilDone(pollOptions?: {
+        abortSignal?: AbortSignalLike;
+    }): Promise<TResult>;
     stopPolling(): void;
     toString(): string;
 }
@@ -93,6 +123,7 @@ export class PollerStoppedError extends Error {
 
 // @public
 export interface PollOperation<TState, TResult> {
+    // @deprecated
     cancel(options?: {
         abortSignal?: AbortSignalLike;
     }): Promise<PollOperation<TState, TResult>>;
@@ -125,6 +156,23 @@ export interface RawResponse {
     statusCode: number;
 }
 
+// @public
+export interface SimplePollerLike<TState extends OperationState<TResult>, TResult> {
+    getOperationState(): TState;
+    getResult(): TResult | undefined;
+    isDone(): boolean;
+    isStopped(): boolean;
+    onProgress(callback: (state: TState) => void): CancelOnProgress;
+    poll(options?: {
+        abortSignal?: AbortSignalLike;
+    }): Promise<void>;
+    pollUntilDone(pollOptions?: {
+        abortSignal?: AbortSignalLike;
+    }): Promise<TResult>;
+    stopPolling(): void;
+    toString(): string;
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

sdk/core/core-lro/src/http/models.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { AbortSignalLike } from "@azure/abort-controller";
+
+// TODO: rename to ResourceLocationConfig
+/**
+ * The potential location of the result of the LRO if specified by the LRO extension in the swagger.
+ */
+export type LroResourceLocationConfig = "azure-async-operation" | "location" | "original-uri";
+
+/**
+ * The type of a LRO response body. This is just a convenience type for checking the status of the operation.
+ */
+
+export interface ResponseBody extends Record<string, unknown> {
+  /** The status of the operation. */
+  status?: string;
+  /** The state of the provisioning process */
+  provisioningState?: string;
+  /** The properties of the provisioning process */
+  properties?: { provisioningState?: string } & Record<string, unknown>;
+}
+
+/**
+ * Simple type of the raw response.
+ */
+export interface RawResponse {
+  /** The HTTP status code */
+  statusCode: number;
+  /** A HttpHeaders collection in the response represented as a simple JSON object where all header names have been normalized to be lower-case. */
+  headers: {
+    [headerName: string]: string;
+  };
+  /** The parsed response body */
+  body?: unknown;
+}
+
+// TODO: rename to OperationResponse
+/**
+ * The type of the response of a LRO.
+ */
+export interface LroResponse<T = unknown> {
+  /** The flattened response */
+  flatResponse: T;
+  /** The raw response */
+  rawResponse: RawResponse;
+}
+
+/**
+ * Description of a long running operation.
+ */
+export interface LongRunningOperation<T = unknown> {
+  /**
+   * The request path. This should be set if the operation is a PUT and needs
+   * to poll from the same request path.
+   */
+  requestPath?: string;
+  /**
+   * The HTTP request method. This should be set if the operation is a PUT or a
+   * DELETE.
+   */
+  requestMethod?: string;
+  /**
+   * A function that can be used to send initial request to the service.
+   */
+  sendInitialRequest: () => Promise<LroResponse<unknown>>;
+  /**
+   * A function that can be used to poll for the current status of a long running operation.
+   */
+  sendPollRequest: (
+    path: string,
+    options?: { abortSignal?: AbortSignalLike }
+  ) => Promise<LroResponse<T>>;
+}
+
+export type HttpOperationMode = "OperationLocation" | "ResourceLocation" | "Body";
+
+/**
+ * Options for `createPoller`.
+ */
+export interface CreateHttpPollerOptions<TResult, TState> {
+  /**
+   * Defines how much time the poller is going to wait before making a new request to the service.
+   */
+  intervalInMs?: number;
+  /**
+   * A serialized poller which can be used to resume an existing paused Long-Running-Operation.
+   */
+  restoreFrom?: string;
+  /**
+   * The potential location of the result of the LRO if specified by the LRO extension in the swagger.
+   */
+  resourceLocationConfig?: LroResourceLocationConfig;
+  /**
+   * A function to process the result of the LRO.
+   */
+  processResult?: (result: unknown, state: TState) => TResult;
+  /**
+   * A function to process the state of the LRO.
+   */
+  updateState?: (state: TState, response: LroResponse) => void;
+  /**
+   * A function to be called each time the operation location is updated by the
+   * service.
+   */
+  withOperationLocation?: (operationLocation: string) => void;
+}