support for Enums or collection of enum values as root of the payload

Author: koros

packages/abstractions/src/apiClientProxifier.ts

@@ -150,6 +150,24 @@ function send(
         metadata.responseBodyFactory as ParsableFactory<Parsable>,
         metadata.errorMappings,
       );
+    case "sendEnum":
+      if (!metadata.enumObject) {
+        throw new Error("couldn't find response body factory");
+      }
+      return requestAdapter.sendEnum(
+        requestInfo,
+        metadata.enumObject,
+        metadata.errorMappings,
+      );
+    case "sendCollectionOfEnum":
+      if (!metadata.enumObject) {
+        throw new Error("couldn't find response body factory");
+      }
+      return requestAdapter.sendCollectionOfEnum(
+        requestInfo,
+        metadata.enumObject,
+        metadata.errorMappings,
+      );
     case "sendCollectionOfPrimitive":
       if (!metadata.responseBodyFactory) {
         throw new Error("couldn't find response body factory");
@@ -416,6 +434,7 @@ export interface RequestMetadata {
   requestInformationContentSetMethod?: keyof RequestInformationSetContent;
   queryParametersMapper?: Record<string, string>;
   uriTemplate: string;
+  enumObject?: EnumObject;
 }
 export interface RequestsMetadata {
   delete?: RequestMetadata;
@@ -435,6 +454,8 @@ export interface NavigationMetadata {
   pathParametersMappings?: string[];
 }
 
+type EnumObject<T extends Record<string, unknown> = Record<string, unknown>> = T;
+
 export type KeysToExcludeForNavigationMetadata =
   | KeysOfRequestsMetadata
   | "toDeleteRequestInformation"

packages/abstractions/src/requestAdapter.ts

@@ -84,6 +84,34 @@ export interface RequestAdapter {
     requestInfo: RequestInformation,
     errorMappings: ErrorMappings | undefined,
   ): Promise<void>;
+  /**
+   * Executes the HTTP request specified by the given RequestInformation and returns the deserialized enum response model.
+   *
+   * @template EnumObject - The type of the enum object. Must extend Record<string, unknown>.
+   * @param {RequestInformation} requestInfo - The request info to execute.
+   * @param {EnumObject} enumObject - The Enum object expected in the response.
+   * @param {ErrorMappings | undefined} errorMappings - the error factories mapping to use in case of a failed request.
+   * @returns {Promise<EnumObject[keyof EnumObject] | undefined>} - A promise that resolves to the response of the request, or undefined if an error occurred.
+   */
+  sendEnum<EnumObject extends Record<string, unknown>>(
+    requestInfo: RequestInformation,
+    enumObject: EnumObject,
+    errorMappings: ErrorMappings | undefined,
+  ): Promise<EnumObject[keyof EnumObject] | undefined>;
+  /**
+   * Executes the HTTP request specified by the given RequestInformation and returns the deserialized response model collection.
+   *
+   * @template EnumObject - The type of the enum objects. Must extend Record<string, unknown>.
+   * @param {RequestInformation} requestInfo - The request info to execute.
+   * @param {EnumObject} enumObject - The Enum object expected in the response.
+   * @param {ErrorMappings | undefined} errorMappings - the error factories mapping to use in case of a failed request.
+   * @returns {Promise<EnumObject[keyof EnumObject][] | undefined>} - with the deserialized response model collection.
+   */
+  sendCollectionOfEnum<EnumObject extends Record<string, unknown>>(
+    requestInfo: RequestInformation,
+    enumObject: EnumObject,
+    errorMappings: ErrorMappings | undefined,
+  ): Promise<EnumObject[keyof EnumObject][] | undefined>;
   /**
    * Enables the backing store proxies for the SerializationWriters and ParseNodes in use.
    * @param backingStoreFactory the backing store factory to use.

packages/http/fetch/src/fetchRequestAdapter.ts

@@ -281,6 +281,74 @@ export class FetchRequestAdapter implements RequestAdapter {
 			}
 		});
 	};
+	public sendEnum = <EnumObject extends Record<string, unknown>>(requestInfo: RequestInformation, enumObject: EnumObject, errorMappings: ErrorMappings | undefined): Promise<EnumObject[keyof EnumObject] | undefined> => {
+		if (!requestInfo) {
+			throw new Error("requestInfo cannot be null");
+		}
+		return this.startTracingSpan(requestInfo, "sendEnum", async (span) => {
+			try {
+				const response = await this.getHttpResponseMessage(requestInfo, span);
+				const responseHandler = this.getResponseHandler(requestInfo);
+				if (responseHandler) {
+					span.addEvent(FetchRequestAdapter.eventResponseHandlerInvokedKey);
+					return await responseHandler.handleResponse(response, errorMappings);
+				} else {
+					try {
+						await this.throwIfFailedResponse(response, errorMappings, span);
+						if (this.shouldReturnUndefined(response)) return undefined;
+						const rootNode = await this.getRootParseNode(response);
+						return trace.getTracer(this.observabilityOptions.getTracerInstrumentationName()).startActiveSpan("getEnumValue", (deserializeSpan) => {
+							try {
+								span.setAttribute(FetchRequestAdapter.responseTypeAttributeKey, "enum");
+								const result = rootNode.getEnumValue(enumObject);
+								return result as unknown as EnumObject[keyof EnumObject];
+							} finally {
+								deserializeSpan.end();
+							}
+						});
+					} finally {
+						await this.purgeResponseBody(response);
+					}
+				}
+			} finally {
+				span.end();
+			}
+		}) as Promise<EnumObject[keyof EnumObject]>;
+	}
+	public sendCollectionOfEnum = <EnumObject extends Record<string, unknown>>(requestInfo: RequestInformation, enumObject: EnumObject, errorMappings: ErrorMappings | undefined): Promise<EnumObject[keyof EnumObject][] | undefined> => {
+		if (!requestInfo) {
+			throw new Error("requestInfo cannot be null");
+		}
+		return this.startTracingSpan(requestInfo, "sendCollectionOfEnum", async (span) => {
+			try {
+				const response = await this.getHttpResponseMessage(requestInfo, span);
+				const responseHandler = this.getResponseHandler(requestInfo);
+				if (responseHandler) {
+					span.addEvent(FetchRequestAdapter.eventResponseHandlerInvokedKey);
+					return await responseHandler.handleResponse(response, errorMappings);
+				} else {
+					try {
+						await this.throwIfFailedResponse(response, errorMappings, span);
+						if (this.shouldReturnUndefined(response)) return undefined;
+						const rootNode = await this.getRootParseNode(response);
+						return trace.getTracer(this.observabilityOptions.getTracerInstrumentationName()).startActiveSpan("getCollectionOfEnumValues", (deserializeSpan) => {
+							try {
+								const result = rootNode.getCollectionOfEnumValues(enumObject);
+								span.setAttribute(FetchRequestAdapter.responseTypeAttributeKey, "enum[]");
+								return result as unknown as EnumObject[keyof EnumObject][];
+							} finally {
+								deserializeSpan.end();
+							}
+						});
+					} finally {
+						await this.purgeResponseBody(response);
+					}
+				}
+			} finally {
+				span.end();
+			}
+		});
+	}
 	public enableBackingStore = (backingStoreFactory?: BackingStoreFactory | undefined): void => {
 		this.parseNodeFactory = enableBackingStoreForParseNodeFactory(this.parseNodeFactory);
 		this.serializationWriterFactory = enableBackingStoreForSerializationWriterFactory(this.serializationWriterFactory);