[core-client] Switch _response property for callback. (#13132)

* Switch _response property for callback.

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

@@ -202,6 +202,7 @@ export interface OperationArguments {
 // @public
 export interface OperationOptions {
     abortSignal?: AbortSignalLike;
+    onResponse?: RawResponseCallback;
     requestOptions?: OperationRequestOptions;
     serializerOptions?: SerializerOptions;
     tracingOptions?: OperationTracingOptions;
@@ -241,13 +242,6 @@ export interface OperationRequestOptions {
     timeout?: number;
 }
 
-// @public
-export interface OperationResponse {
-    // (undocumented)
-    [key: string]: any;
-    _response: FullOperationResponse;
-}
-
 // @public
 export interface OperationResponseMap {
     bodyMapper?: Mapper;
@@ -297,6 +291,9 @@ export interface PolymorphicDiscriminator {
 // @public
 export type QueryCollectionFormat = "CSV" | "SSV" | "TSV" | "Pipes" | "Multi";
 
+// @public
+export type RawResponseCallback = (rawResponse: FullOperationResponse, flatResponse: unknown) => void;
+
 // @public (undocumented)
 export interface SequenceMapper extends BaseMapper {
     // (undocumented)
@@ -347,7 +344,7 @@ export interface SerializerOptions {
 // @public
 export class ServiceClient {
     constructor(options?: ServiceClientOptions);
-    sendOperationRequest(operationArguments: OperationArguments, operationSpec: OperationSpec): Promise<OperationResponse>;
+    sendOperationRequest<T>(operationArguments: OperationArguments, operationSpec: OperationSpec): Promise<T>;
     sendRequest(request: PipelineRequest): Promise<PipelineResponse>;
 }
 

sdk/core/core-client/src/index.ts

@@ -36,14 +36,14 @@ export {
   OperationRequestInfo,
   QueryCollectionFormat,
   ParameterPath,
-  OperationResponse,
   FullOperationResponse,
   PolymorphicDiscriminator,
   SpanConfig,
   XML_ATTRKEY,
   XML_CHARKEY,
   XmlOptions,
-  SerializerOptions
+  SerializerOptions,
+  RawResponseCallback
 } from "./interfaces";
 export {
   deserializationPolicy,

sdk/core/core-client/src/interfaces.ts

@@ -105,6 +105,13 @@ export interface OperationOptions {
    * Options to override serialization/de-serialization behavior.
    */
   serializerOptions?: SerializerOptions;
+
+  /**
+   * A function to be called each time a response is received from the server
+   * while performing the requested operation.
+   * May be called multiple times.
+   */
+  onResponse?: RawResponseCallback;
 }
 
 /**
@@ -333,17 +340,14 @@ export interface FullOperationResponse extends PipelineResponse {
 }
 
 /**
- * The processed and flattened response to an operation call.
- * Contains merged properties of the parsed body and headers.
+ * A function to be called each time a response is received from the server
+ * while performing the requested operation.
+ * May be called multiple times.
  */
-export interface OperationResponse {
-  /**
-   * The underlying HTTP response containing both raw and deserialized response data.
-   */
-  _response: FullOperationResponse;
-
-  [key: string]: any;
-}
+export type RawResponseCallback = (
+  rawResponse: FullOperationResponse,
+  flatResponse: unknown
+) => void;
 
 /**
  * Used to map raw response objects to final shapes.

sdk/core/core-client/src/serviceClient.ts

@@ -13,7 +13,6 @@ import {
   InternalPipelineOptions
 } from "@azure/core-https";
 import {
-  OperationResponse,
   OperationArguments,
   OperationSpec,
   OperationRequest,
@@ -125,13 +124,14 @@ export class ServiceClient {
 
   /**
    * Send an HTTP request that is populated using the provided OperationSpec.
+   * @typeParam T The typed result of the request, based on the OperationSpec.
    * @param {OperationArguments} operationArguments The arguments that the HTTP request's templated values will be populated from.
    * @param {OperationSpec} operationSpec The OperationSpec to use to populate the httpRequest.
    */
-  async sendOperationRequest(
+  async sendOperationRequest<T>(
     operationArguments: OperationArguments,
     operationSpec: OperationSpec
-  ): Promise<OperationResponse> {
+  ): Promise<T> {
     const baseUri: string | undefined = operationSpec.baseUrl || this._baseUri;
     if (!baseUri) {
       throw new Error(
@@ -200,7 +200,14 @@ export class ServiceClient {
 
     try {
       const rawResponse = await this.sendRequest(request);
-      return flattenResponse(rawResponse, operationSpec.responses[rawResponse.status]);
+      const flatResponse = flattenResponse(
+        rawResponse,
+        operationSpec.responses[rawResponse.status]
+      ) as T;
+      if (options?.onResponse) {
+        options.onResponse(rawResponse, flatResponse);
+      }
+      return flatResponse;
     } catch (error) {
       if (error.response) {
         error.details = flattenResponse(
@@ -285,29 +292,18 @@ export function createClientPipeline(options: ClientPipelineOptions = {}): Pipel
 function flattenResponse(
   fullResponse: FullOperationResponse,
   responseSpec: OperationResponseMap | undefined
-): OperationResponse {
+): unknown {
   const parsedHeaders = fullResponse.parsedHeaders;
   const bodyMapper = responseSpec && responseSpec.bodyMapper;
 
-  function addResponse<T extends object>(
-    obj: T
-  ): T & { readonly _response: FullOperationResponse } {
-    return Object.defineProperty(obj, "_response", {
-      configurable: false,
-      enumerable: false,
-      writable: false,
-      value: fullResponse
-    });
-  }
-
   if (bodyMapper) {
     const typeName = bodyMapper.type.name;
     if (typeName === "Stream") {
-      return addResponse({
+      return {
         ...parsedHeaders,
         blobBody: fullResponse.blobBody,
         readableStreamBody: fullResponse.readableStreamBody
-      });
+      };
     }
 
     const modelProperties =
@@ -330,14 +326,14 @@ function flattenResponse(
           arrayResponse[key] = parsedHeaders[key];
         }
       }
-      return addResponse(arrayResponse);
+      return arrayResponse;
     }
 
     if (typeName === "Composite" || typeName === "Dictionary") {
-      return addResponse({
+      return {
         ...parsedHeaders,
         ...fullResponse.parsedBody
-      });
+      };
     }
   }
 
@@ -346,16 +342,16 @@ function flattenResponse(
     fullResponse.request.method === "HEAD" ||
     isPrimitiveType(fullResponse.parsedBody)
   ) {
-    return addResponse({
+    return {
       ...parsedHeaders,
       body: fullResponse.parsedBody
-    });
+    };
   }
 
-  return addResponse({
+  return {
     ...parsedHeaders,
     ...fullResponse.parsedBody
-  });
+  };
 }
 
 function getCredentialScopes(options: ServiceClientOptions): string | string[] | undefined {

sdk/core/core-client/test/serviceClient.spec.ts

@@ -14,7 +14,8 @@ import {
   Mapper,
   CompositeMapper,
   OperationSpec,
-  serializationPolicy
+  serializationPolicy,
+  FullOperationResponse
 } from "../src";
 import {
   createHttpHeaders,
@@ -249,20 +250,26 @@ describe("ServiceClient", function() {
     assert.deepEqual(request!.headers.toJSON(), expected);
   });
 
-  it("responses should not show the _response property when serializing", async function() {
+  it("should call rawResponseCallback with the full response", async function() {
     let request: OperationRequest;
     const client = new ServiceClient({
       httpsClient: {
         sendRequest: (req) => {
           request = req;
-          return Promise.resolve({ request, status: 200, headers: createHttpHeaders() });
+          return Promise.resolve({
+            request,
+            status: 200,
+            headers: createHttpHeaders({ "X-Extra-Info": "foo" })
+          });
         }
       },
       pipeline: createEmptyPipeline()
     });
 
+    let rawResponse: FullOperationResponse | undefined;
+
     const response = await client.sendOperationRequest(
-      {},
+      { options: { onResponse: (response) => (rawResponse = response) } },
       {
         httpMethod: "GET",
         baseUrl: "https://example.com",
@@ -275,8 +282,10 @@ describe("ServiceClient", function() {
     );
 
     assert(request!);
-    // _response should be not enumerable
     assert.strictEqual(JSON.stringify(response), "{}");
+    assert.strictEqual(rawResponse?.status, 200);
+    assert.strictEqual(rawResponse?.request, request!);
+    assert.strictEqual(rawResponse?.headers.get("X-Extra-Info"), "foo");
   });
 
   it("should serialize collection:csv query parameters", async function() {
@@ -336,8 +345,15 @@ describe("ServiceClient", function() {
       pipeline
     });
 
-    const res = await client1.sendOperationRequest(
-      {},
+    let rawResponse: FullOperationResponse | undefined;
+    const res = await client1.sendOperationRequest<Array<number>>(
+      {
+        options: {
+          onResponse: (response) => {
+            rawResponse = response;
+          }
+        }
+      },
       {
         serializer: createSerializer(),
         httpMethod: "GET",
@@ -359,7 +375,7 @@ describe("ServiceClient", function() {
       }
     );
 
-    assert.strictEqual(res._response.status, 200);
+    assert.strictEqual(rawResponse?.status, 200);
     assert.deepStrictEqual(res.slice(), [1, 2, 3]);
   });