inverting response compatibility option in a search api

Author: AleksandrRogov

.github/README.md

@@ -342,7 +342,7 @@ Both `dataApi` and `searchApi` can be omitted from a configuration. Their defaul
 | Property Name | Type | Description |
 |--------|--------|--------|
 | escapeSpecialCharacters | `boolean` | `v2.3.0+` **Works only with Search API 2.0**. Optional. Escapes special characters in the search string. |
-| disableResponseCompatibility | `boolean` | `v2.3.0+`. Disables forced compatibility of the responses between v1 and v2. It's highly recommended to enable this option, because all response properties are duplicated by default for compatibility reasons. |
+| enableResponseCompatibility | `boolean` | `v2.3.0+`. Enables compatibility of the responses between v1 and v2. Only enable this option temporarily, because it will force all response properties to be duplicated to achieve a full compatibility. |
 
 ## Request Examples
 
@@ -2196,12 +2196,32 @@ All functions: Query, Suggest and Autocomplete, - can be called with a single `s
 
 _Examples below follow Microsoft's official documenation._
 
-> [!NOTE]
+> [!IMPORTANT]
 > All request properties are `camelCase`, even though in Dataverse Search API v2.0 they are lowercase.
 
-> [!TIP]
+> [!NOTE]
 > All objects in requests and responses are automatically converted and encoded as necessary (per official documentation), simplifying developer's work to construct the request and process the response.
 
+> [!TIP]
+> To enable a full compatibility between Search API v1 and v2 responses, you can temporarily set `enableResponseCompatibility` to `true` (in a `searchApi` config, see the code snippet below). The downside is that this will force all properties in the responses to be duplicated which will consume more memory (and cpu), thus it is not enabled by default.
+>
+> This option can be useful to test if your search api v1.0 queries are compatible with v2.0 before rewriting your code. The main compatibility issue could be a `filter` value because its syntax has been changed by Microsoft.
+>
+> Another use-case could be if you would like to rewrite your code to be fully compatible with v2.0 without switching to v2.0 queries (by keeping `version: "1.0"`) and having to deal with exceptions because of the `filter` incompatibility.
+
+To turn on the response compatibility:
+
+```ts
+const webApi = new DynamicsWebApi({
+    searchApi: {
+        // version: "2.0",
+        options: {
+            enableResponseCompatibility: true
+        }
+    }
+})
+```
+
 ### Query
 
 The following table describes all parameters for a `query` request:

src/dynamics-web-api.ts

@@ -1121,10 +1121,10 @@ export type SearchApiOptions = {
      */
     escapeSpecialCharacters?: boolean;
     /**
-     * Disables compatibility of the responses between v1 and v2.
-     * Enabling this option is highly recommended, because all response properties are duplicated by default for compatibility reasons.
+     * Enables compatibility of the responses between v1 and v2.
+     * Only enable this option temporarily, because it will force all response properties to be duplicated to achieve a full compatibility.
      */
-    disableResponseCompatibility?: boolean;
+    enableResponseCompatibility?: boolean;
 };
 
 export interface ApiConfig<TOptions = any> {

src/requests/search/responseParsers/parseAutocompleteResponse.ts

@@ -17,7 +17,7 @@ export function parseAutocompleteResponse(queryResponse: AutocompleteResponseInt
             response: responseValue,
         };
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             toReturn.value = responseValue.Value;
             toReturn.querycontext = responseValue.QueryContext;
         }
@@ -28,10 +28,10 @@ export function parseAutocompleteResponse(queryResponse: AutocompleteResponseInt
     const toV2 = (): AutocompleteResponse => {
         // @ts-ignore we don't enforce to have all properties in the response if the compatibility is disabled
         const toReturn: AutocompleteResponse = {
-            ...queryResponse
-        }
+            ...queryResponse,
+        };
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             toReturn.response = {
                 Value: queryResponse.value,
                 QueryContext: queryResponse.querycontext,

src/requests/search/responseParsers/parseQueryResponse.ts

@@ -17,7 +17,7 @@ export function parseQueryResponse(queryResponse: QueryResponseInternal, config:
             response: responseValue,
         };
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             toReturn.value = responseValue.Value;
             toReturn.facets = responseValue.Facets;
             toReturn.totalrecordcount = responseValue.Count;
@@ -33,7 +33,7 @@ export function parseQueryResponse(queryResponse: QueryResponseInternal, config:
             ...queryResponse,
         };
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             toReturn.response = {
                 Count: queryResponse.totalrecordcount,
                 Value: queryResponse.value,

src/requests/search/responseParsers/parseSuggestResponse.ts

@@ -12,7 +12,7 @@ export function parseSuggestResponse(queryResponse: SuggestResponseInternal, con
     const toV1 = (): SuggestResponse => {
         const responseValue = JSON.parse(queryResponse.response, dateReviver) as SuggestResponse["response"];
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             responseValue.Value?.forEach((item: SuggestResponseValue) => {
                 item.document = item.Document;
                 item.text = item.Text;
@@ -24,7 +24,7 @@ export function parseSuggestResponse(queryResponse: SuggestResponseInternal, con
             response: responseValue,
         };
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             toReturn.value = responseValue.Value;
             toReturn.querycontext = responseValue.QueryContext;
         }
@@ -33,7 +33,7 @@ export function parseSuggestResponse(queryResponse: SuggestResponseInternal, con
     };
 
     const toV2 = (): SuggestResponse => {
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             queryResponse.value?.forEach((item: SuggestResponseValue) => {
                 item.Document = item.document;
                 item.Text = item.text;
@@ -45,7 +45,7 @@ export function parseSuggestResponse(queryResponse: SuggestResponseInternal, con
             ...queryResponse,
         };
 
-        if (!config.disableSearchApiResponseCompatibility) {
+        if (config.enableSearchApiResponseCompatibility) {
             toReturn.response = {
                 Value: queryResponse.value,
                 QueryContext: queryResponse.querycontext,

src/utils/Config.ts

@@ -12,7 +12,7 @@ const apiConfigs: ApiType[] = ["dataApi", "searchApi", "serviceApi"];
 export interface InternalApiConfig extends ApiConfig {
     url: string;
     escapeSpecialCharacters?: boolean;
-    disableSearchApiResponseCompatibility?: boolean;
+    enableSearchApiResponseCompatibility?: boolean;
 }
 
 export interface InternalConfig extends Config {
@@ -47,9 +47,9 @@ const mergeSearchApiOptions = (internalApiConfig: InternalApiConfig, options: Se
         internalApiConfig.escapeSpecialCharacters = options.escapeSpecialCharacters;
     }
 
-    if (options.disableResponseCompatibility != null) {
-        ErrorHelper.boolParameterCheck(options.disableResponseCompatibility, FUNCTION_NAME, `config.searchApi.options.disableResponseCompatibility`);
-        internalApiConfig.disableSearchApiResponseCompatibility = options.disableResponseCompatibility;
+    if (options.enableResponseCompatibility != null) {
+        ErrorHelper.boolParameterCheck(options.enableResponseCompatibility, FUNCTION_NAME, `config.searchApi.options.enableResponseCompatibility`);
+        internalApiConfig.enableSearchApiResponseCompatibility = options.enableResponseCompatibility;
     }
 };
 

tests/searchApi.parseQuery.spec.ts

@@ -7,7 +7,7 @@ import type { AutocompleteResponse, QueryResponse, SuggestResponse } from "../sr
 
 describe("parseQueryResponse", () => {
     it("returns undefined if response is undefined", () => {
-        const result = parseQueryResponse(undefined!, { version: "2.0", url: "" });
+        const result = parseQueryResponse(undefined!, { version: "2.0", url: "", enableSearchApiResponseCompatibility: true });
         expect(result).to.be.undefined;
     });
 
@@ -31,7 +31,7 @@ describe("parseQueryResponse", () => {
         };
 
         it("should parse the query response correctly", () => {
-            const result = parseQueryResponse(queryResponse, { version: "2.0", url: "" });
+            const result = parseQueryResponse(queryResponse, { version: "2.0", url: "", enableSearchApiResponseCompatibility: true });
             expect(result).to.deep.equal({
                 ...queryResponse,
                 value: responseValue.Value,
@@ -54,7 +54,7 @@ describe("parseQueryResponse", () => {
         };
 
         it("should parse the query response correctly", () => {
-            const result = parseQueryResponse(queryResponse, { version: "1.0", url: "" });
+            const result = parseQueryResponse(queryResponse, { version: "1.0", url: "", enableSearchApiResponseCompatibility: true });
             expect(result).to.deep.equal({
                 ...queryResponse,
                 response: {
@@ -71,7 +71,7 @@ describe("parseQueryResponse", () => {
 
 describe("parseSuggestResponse", () => {
     it("returns undefined if response is undefined", () => {
-        const result = parseSuggestResponse(undefined!, { version: "2.0", url: "" });
+        const result = parseSuggestResponse(undefined!, { version: "2.0", url: "", enableSearchApiResponseCompatibility: true });
         expect(result).to.be.undefined;
     });
 
@@ -90,7 +90,7 @@ describe("parseSuggestResponse", () => {
             "@odata.context": "https://example.com/#QueryResponse",
         };
 
-        const result = parseSuggestResponse(queryResponse, { version: "2.0", url: "" });
+        const result = parseSuggestResponse(queryResponse, { version: "2.0", url: "", enableSearchApiResponseCompatibility: true });
 
         it("should parse the query response correctly", () => {
             expect(result).to.deep.equal({
@@ -114,7 +114,7 @@ describe("parseSuggestResponse", () => {
             "@odata.context": "https://example.com/#QueryResponse",
         };
 
-        const result = parseSuggestResponse(queryResponse, { version: "1.0", url: "" });
+        const result = parseSuggestResponse(queryResponse, { version: "1.0", url: "", enableSearchApiResponseCompatibility: true });
 
         it("should parse the query response correctly", () => {
             expect(result).to.deep.equal({
@@ -135,7 +135,7 @@ describe("parseSuggestResponse", () => {
 
 describe("parseAutocompleteResponse", () => {
     it("returns undefined if response is undefined", () => {
-        const result = parseAutocompleteResponse(undefined!, { version: "2.0", url: "" });
+        const result = parseAutocompleteResponse(undefined!, { version: "2.0", url: "", enableSearchApiResponseCompatibility: true });
         expect(result).to.be.undefined;
     });
 
@@ -154,7 +154,7 @@ describe("parseAutocompleteResponse", () => {
             "@odata.context": "https://example.com/#QueryResponse",
         };
 
-        const result = parseAutocompleteResponse(queryResponse, { version: "2.0", url: "" });
+        const result = parseAutocompleteResponse(queryResponse, { version: "2.0", url: "", enableSearchApiResponseCompatibility: true });
 
         it("should parse the autocomplete response correctly", () => {
             expect(result).to.deep.equal({
@@ -174,7 +174,7 @@ describe("parseAutocompleteResponse", () => {
             "@odata.context": "https://example.com/#QueryResponse",
         };
 
-        const result = parseAutocompleteResponse(queryResponse, { version: "1.0", url: "" });
+        const result = parseAutocompleteResponse(queryResponse, { version: "1.0", url: "", enableSearchApiResponseCompatibility: true });
 
         it("should parse the autocomplete response correctly", () => {
             expect(result).to.deep.equal({

tests/searchApi.spec.ts

@@ -5,27 +5,27 @@ import * as mocks from "./stubs";
 import { DynamicsWebApi, Query, Autocomplete, Suggest } from "../src/dynamics-web-api";
 
 const dynamicsWebApiTest = new DynamicsWebApi({
-    dataApi: {
-        version: "8.2",
+    searchApi: {
+        options: {
+            enableResponseCompatibility: true,
+        },
     },
 });
 
 const dynamicsWebApiSearchV2 = new DynamicsWebApi({
     searchApi: {
         version: "2.0",
+        options: {
+            enableResponseCompatibility: true,
+        },
     },
 });
 
-const dynamicsWebApiSearchV1NoCompatibility = new DynamicsWebApi({
-    searchApi: {
-        options: { disableResponseCompatibility: true },
-    },
-});
+const dynamicsWebApiSearchV1NoCompatibility = new DynamicsWebApi();
 
 const dynamicsWebApiSearchV2NoCompatibility = new DynamicsWebApi({
     searchApi: {
         version: "2.0",
-        options: { disableResponseCompatibility: true },
     },
 });
 
@@ -170,7 +170,7 @@ describe("dynamicsWebApi.query -", () => {
         });
     });
 
-    describe("v2.0 - disableResponseCompatibility = true", () => {
+    describe("v2.0 - enableResponseCompatibility = false", () => {
         let scope;
         const searchQuery: Query = {
             search: "test",
@@ -205,7 +205,7 @@ describe("dynamicsWebApi.query -", () => {
         });
     });
 
-    describe("v1.0 - disableResponseCompatibility = true", () => {
+    describe("v1.0 - enableResponseCompatibility = false", () => {
         let scope;
         const searchQuery: Query = {
             search: "test",
@@ -345,7 +345,7 @@ describe("dynamicsWebApi.suggest -", () => {
         });
     });
 
-    describe("v1.0 - disableResponseCompatibility = true", () => {
+    describe("v1.0 - enableResponseCompatibility = false", () => {
         let scope;
         const suggestQuery: Suggest = {
             search: "test",
@@ -379,7 +379,7 @@ describe("dynamicsWebApi.suggest -", () => {
         });
     });
 
-    describe("v2.0 - disableResponseCompatibility = true", () => {
+    describe("v2.0 - enableResponseCompatibility = false", () => {
         let scope;
         const suggestQuery: Suggest = {
             search: "test",
@@ -517,7 +517,7 @@ describe("dynamicsWebApi.autocomplete -", () => {
             expect(scope.isDone()).to.be.true;
         });
     });
-    describe("v1.0 - disableResponseCompatibility = true", () => {
+    describe("v1.0 - enableResponseCompatibility = false", () => {
         let scope;
         const autocompleteQuery: Autocomplete = {
             search: "test",
@@ -550,7 +550,7 @@ describe("dynamicsWebApi.autocomplete -", () => {
             expect(scope.isDone()).to.be.true;
         });
     });
-    describe("v2.0 - disableResponseCompatibility = true", () => {
+    describe("v2.0 - enableResponseCompatibility = false", () => {
         let scope;
         const autocompleteQuery: Autocomplete = {
             search: "test",