new search api configuration props; adding tests for the query conversion functionality

AleksandrRogov · AleksandrRogov · commit bee94eef1980 · 2025-03-17T20:20:21.000-04:00
diff --git a/src/dynamics-web-api.ts b/src/dynamics-web-api.ts
@@ -915,7 +915,7 @@ export type SearchEntity = {
     filter?: string;
 };
 
-export type SearchOptions = {
+export type SearchOptions = Record<string, any> & {
     /**Values can be simple or lucene. */
     querytype?: "simple" | "lucene";
     /**Enables intelligent query workflow to return probable set of results if no good matches are found for the search request terms.*/
@@ -952,7 +952,7 @@ export interface Query extends SearchQueryBase {
     /**A list of comma-separated clauses where each clause consists of a column name followed by 'asc' (ascending, which is the default) or 'desc' (descending). This list specifies how to order the results in order of precedence. */
     orderBy?: string[];
     /**V2. Options are settings configured to search a search term. */
-    options?: SearchOptions;
+    options?: string | SearchOptions;
     /**
      * V1. Specifies whether any or all the search terms must be matched to count the document as a match. The default is 'any'.
      * @deprecated Use "options.searchmode".
@@ -1000,11 +1000,18 @@ export interface AutocompleteRequest extends BaseRequest {
     query: Autocomplete;
 }
 
-export interface ApiConfig {
-    /** API Version to use, for example: "9.2" or "1.0" */
+export type SearchApiOptions = {
+    /**Escapes the search string. Special characters that require escaping include the following: + - & | ! ( ) { } [ ] ^ " ~ * ? : \ /. */
+    escapeSpecialCharacters?: boolean;
+}
+
+export interface ApiConfig<TOptions = any> {
+    /** API Version to use, for example: "9.2" or "1.0". */
     version?: string;
-    /** API Path, for example: "data" or "search" */
+    /** API Path, for example: "data" or "search". */
     path?: string;
+    /** Specific API options. Currently it is only available for the Search API .*/
+    options?: TOptions;
 }
 
 export interface AccessToken {
@@ -1036,7 +1043,7 @@ export interface Config {
     /**Configuration object for Dataverse Web API (with path "data"). */
     dataApi?: ApiConfig;
     /**Configuration object for Dataverse Search API (with path "search"). */
-    searchApi?: ApiConfig;
+    searchApi?: ApiConfig<SearchApiOptions>;
     /**Default headers to supply with each request. */
     headers?: HeaderCollection;
 }
diff --git a/src/helpers/Regex.ts b/src/helpers/Regex.ts
@@ -131,3 +131,8 @@ export const FETCH_XML_PAGE_REGEX = /^<fetch.+page=/;
 export const FETCH_XML_REPLACE_REGEX = /^(<fetch)/;
 
 export const DATE_FORMAT_REGEX = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:Z|[-+]\d{2}:\d{2})$/;
+
+const SEARCH_SPECIAL_CHARACTERS_REGEX = /[+\-&|!(){}[\]^"~*?:\\\/]/g;
+export function escapeSearchSpecialCharacters(value: string): string {
+    return value.replace(SEARCH_SPECIAL_CHARACTERS_REGEX, "\\$&");
+}
diff --git a/src/requests/search/autocomplete.ts b/src/requests/search/autocomplete.ts
@@ -22,7 +22,7 @@ export async function autocomplete(request: string | AutocompleteRequest, client
 
     internalRequest.functionName = internalRequest.collection = FUNCTION_NAME;
     internalRequest.method = "POST";
-    internalRequest.data = convertSearchQuery(internalRequest.query, FUNCTION_NAME, client.config);
+    internalRequest.data = convertSearchQuery(internalRequest.query, FUNCTION_NAME, client.config.searchApi);
     internalRequest.apiConfig = client.config.searchApi;
 
     delete internalRequest.query;
diff --git a/src/requests/search/convertSearchQuery.ts b/src/requests/search/convertSearchQuery.ts
@@ -1,24 +1,41 @@
-import type { Autocomplete, Suggest, Query, SearchEntity } from "../../dynamics-web-api";
-import { InternalConfig } from "../../utils/Config";
+import type { Autocomplete, Suggest, Query, SearchEntity, SearchOptions } from "../../dynamics-web-api";
+import { escapeSearchSpecialCharacters } from "../../helpers/Regex";
+import { InternalApiConfig } from "../../utils/Config";
 
-export function convertSearchQuery(query: Query | Suggest | Autocomplete, functionName: string, config: InternalConfig) {
+type SearchApiFunction = "query" | "suggest" | "autocomplete";
+
+export function convertSearchQuery(query: Query | Suggest | Autocomplete, functionName: SearchApiFunction, config: InternalApiConfig) {
     if (!query) return query;
 
-    query.entities = convertEntitiesProperty(query.entities, config.searchApi?.version);
+    //escape special characters in a search query only if the option is set to true
+    if (config?.escapeSpecialCharacters === true) {
+        query.search = escapeSearchSpecialCharacters(query.search);
+    }
+
+    if (query.entities?.length) {
+        query.entities = convertEntitiesProperty(query.entities, config?.version);
+    }
+
     if (functionName === "query") {
-        query = convertQuery(query as Query, config.searchApi?.version);
+        convertQuery(query as Query, config?.version);
     }
 
     return query;
 }
 
-function convertEntitiesProperty(entities?: string | string[] | SearchEntity[], version: string = "1.0"): string | string[] | SearchEntity[] | undefined {
+export function convertEntitiesProperty(entities?: string | string[] | SearchEntity[], version: string = "1.0"): string | string[] | undefined {
     if (!entities) return entities;
     if (typeof entities === "string") {
         if (version !== "1.0") return entities;
-        throw new Error(
-            "The 'entities' property must be an array of strings in the Search API v1.0. It cannot be a string. Or set Search API version to v2.0.",
-        );
+        try {
+            entities = JSON.parse(entities) as SearchEntity[];
+        } catch {
+            throw new Error("The 'query.entities' property must be a valid JSON string.");
+        }
+
+        if (!Array.isArray(entities)) {
+            throw new Error("The 'query.entities' property must be an array of strings or objects.");
+        }
     }
 
     const toStringArray = (entity: string | SearchEntity) => {
@@ -31,54 +48,74 @@ function convertEntitiesProperty(entities?: string | string[] | SearchEntity[],
         return entity;
     };
 
-    return entities.map((entity: string | SearchEntity) => (version === "1.0" ? toStringArray(entity) : toSearchEntity(entity))) as string[] | SearchEntity[];
+    const toReturn = entities.map((entity: string | SearchEntity) => (version === "1.0" ? toStringArray(entity) : toSearchEntity(entity)));
+
+    if (version !== "1.0") return JSON.stringify(toReturn);
+    return toReturn as string[];
 }
 
-function convertQuery(query: Query, version: string = "1.0") {
+export function convertQuery(query: Query, version: string = "1.0"): void {
     const toV1 = (query: Query) => {
         if (query.count != null) {
-            query.returnTotalRecordCount = query.count;
+            if (query.returnTotalRecordCount == null) {
+                query.returnTotalRecordCount = query.count;
+            }
             delete query.count;
         }
 
         if (query.options) {
+            if (typeof query.options === "string") {
+                try {
+                    query.options = JSON.parse(query.options) as SearchOptions;
+                } catch {
+                    throw new Error("The 'query.options' property must be a valid JSON string.");
+                }
+            }
+
             if (!query.searchMode) {
                 query.searchMode = query.options.searchmode;
             }
 
             if (!query.searchType) {
-                query.searchType = query.options.querytype === "simple" ? "simple" : "full";
+                query.searchType = query.options.querytype === "lucene" ? "full" : query.options.querytype;
             }
 
             delete query.options;
         }
-
-        return query;
     };
 
     const toV2 = (query: Query) => {
         if (query.returnTotalRecordCount != null) {
-            query.count = query.returnTotalRecordCount;
+            if (query.count == null) {
+                query.count = query.returnTotalRecordCount;
+            }
             delete query.returnTotalRecordCount;
         }
 
+
         if (query.searchMode || query.searchType) {
-            if (!query.options) query.options = {};
+            //only set the options property if it's not a string
+            if (typeof query.options !== "string") {
+                if (!query.options) query.options = {};
 
-            if (!query.options.searchmode) {
-                query.options.searchmode = query.searchMode;
-            }
+                if (!query.options.searchmode) {
+                    query.options.searchmode = query.searchMode;
+                }
 
-            if (!query.options.querytype) {
-                query.options.querytype = query.searchType === "simple" ? "simple" : "lucene";
+                if (!query.options.querytype) {
+                    query.options.querytype = query.searchType === "full" ? "lucene" : query.searchType;
+                }
             }
 
             delete query.searchMode;
             delete query.searchType;
         }
 
-        return query;
+        //convert options to string if it's an object
+        if (query.options && typeof query.options !== "string") {
+            query.options = JSON.stringify(query.options);
+        }
     };
 
-    return version === "1.0" ? toV1(query) : toV2(query);
+    version === "1.0" ? toV1(query) : toV2(query);
 }
diff --git a/src/requests/search/query.ts b/src/requests/search/query.ts
@@ -6,7 +6,7 @@ import { InternalRequest } from "../../types";
 import { LIBRARY_NAME } from "../constants";
 import { convertSearchQuery } from "./convertSearchQuery";
 
-const FUNCTION_NAME = "search";
+const FUNCTION_NAME = "query";
 const REQUEST_NAME = `${LIBRARY_NAME}.${FUNCTION_NAME}`;
 
 export async function query<TValue = any>(request: string | QueryRequest, client: IDataverseClient): Promise<SearchResponse<TValue>> {
@@ -23,7 +23,7 @@ export async function query<TValue = any>(request: string | QueryRequest, client
     internalRequest.collection = "query";
     internalRequest.functionName = FUNCTION_NAME;
     internalRequest.method = "POST";
-    internalRequest.data = convertSearchQuery(internalRequest.query, FUNCTION_NAME, client.config);
+    internalRequest.data = convertSearchQuery(internalRequest.query, FUNCTION_NAME, client.config.searchApi);
     internalRequest.apiConfig = client.config.searchApi;
 
     delete internalRequest.query;
diff --git a/src/requests/search/suggest.ts b/src/requests/search/suggest.ts
@@ -22,7 +22,7 @@ export async function suggest<TValueDocument = any>(request: string | SuggestReq
 
     internalRequest.functionName = internalRequest.collection = FUNCTION_NAME;
     internalRequest.method = "POST";
-    internalRequest.data = convertSearchQuery(internalRequest.query, FUNCTION_NAME, client.config);
+    internalRequest.data = convertSearchQuery(internalRequest.query, FUNCTION_NAME, client.config.searchApi);
     internalRequest.apiConfig = client.config.searchApi;
 
     delete internalRequest.query;
diff --git a/src/utils/Config.ts b/src/utils/Config.ts
@@ -1,11 +1,15 @@
 import { isRunningWithinPortals, getClientUrl } from "./Utility";
 import { ErrorHelper } from "../helpers/ErrorHelper";
-import { ApiConfig, Config } from "../dynamics-web-api";
+import { ApiConfig, Config, SearchApiOptions } from "../dynamics-web-api";
+import { LIBRARY_NAME } from "../requests/constants";
 
 type ApiType = "dataApi" | "searchApi";
 
+const FUNCTION_NAME = `${LIBRARY_NAME}.setConfig`;
+
 export interface InternalApiConfig extends ApiConfig {
     url: string;
+    escapeSpecialCharacters?: boolean;
 }
 
 export interface InternalConfig extends Config {
@@ -26,65 +30,78 @@ const mergeApiConfigs = (apiConfig: ApiConfig | undefined, apiType: ApiType, int
     const internalApiConfig = internalConfig[apiType] as InternalApiConfig;
 
     if (apiConfig?.version) {
-        ErrorHelper.stringParameterCheck(apiConfig.version, "DynamicsWebApi.setConfig", `config.${apiType}.version`);
+        ErrorHelper.stringParameterCheck(apiConfig.version, FUNCTION_NAME, `config.${apiType}.version`);
         internalApiConfig.version = apiConfig.version;
     }
 
     if (apiConfig?.path) {
-        ErrorHelper.stringParameterCheck(apiConfig.path, "DynamicsWebApi.setConfig", `config.${apiType}.path`);
+        ErrorHelper.stringParameterCheck(apiConfig.path, FUNCTION_NAME, `config.${apiType}.path`);
         internalApiConfig.path = apiConfig.path;
     }
 
+    if (apiType === "searchApi") {
+        mergeSearchApiOptions(apiConfig?.options, internalApiConfig);
+    }
+
     internalApiConfig.url = getApiUrl(internalConfig.serverUrl, internalApiConfig);
 };
 
+const mergeSearchApiOptions = (options: SearchApiOptions | undefined, internalApiConfig: InternalApiConfig): void => {
+    if (!options) return;
+
+    if (internalApiConfig.escapeSpecialCharacters != null) {
+        ErrorHelper.boolParameterCheck(options.escapeSpecialCharacters, FUNCTION_NAME, `config.searchApi.options.escapeSpecialCharacters`);
+        internalApiConfig.escapeSpecialCharacters = options.escapeSpecialCharacters;
+    }
+}
+
 export class ConfigurationUtility {
     static mergeApiConfigs = mergeApiConfigs;
 
     static merge(internalConfig: InternalConfig, config?: Config): void {
         if (config?.serverUrl) {
-            ErrorHelper.stringParameterCheck(config.serverUrl, "DynamicsWebApi.setConfig", "config.serverUrl");
+            ErrorHelper.stringParameterCheck(config.serverUrl, FUNCTION_NAME, "config.serverUrl");
             internalConfig.serverUrl = config.serverUrl;
         }
 
         mergeApiConfigs(config?.dataApi, "dataApi", internalConfig);
         mergeApiConfigs(config?.searchApi, "searchApi", internalConfig);
 
         if (config?.impersonate) {
-            internalConfig.impersonate = ErrorHelper.guidParameterCheck(config.impersonate, "DynamicsWebApi.setConfig", "config.impersonate");
+            internalConfig.impersonate = ErrorHelper.guidParameterCheck(config.impersonate, FUNCTION_NAME, "config.impersonate");
         }
 
         if (config?.impersonateAAD) {
-            internalConfig.impersonateAAD = ErrorHelper.guidParameterCheck(config.impersonateAAD, "DynamicsWebApi.setConfig", "config.impersonateAAD");
+            internalConfig.impersonateAAD = ErrorHelper.guidParameterCheck(config.impersonateAAD, FUNCTION_NAME, "config.impersonateAAD");
         }
 
         if (config?.onTokenRefresh) {
-            ErrorHelper.callbackParameterCheck(config.onTokenRefresh, "DynamicsWebApi.setConfig", "config.onTokenRefresh");
+            ErrorHelper.callbackParameterCheck(config.onTokenRefresh, FUNCTION_NAME, "config.onTokenRefresh");
             internalConfig.onTokenRefresh = config.onTokenRefresh;
         }
 
         if (config?.includeAnnotations) {
-            ErrorHelper.stringParameterCheck(config.includeAnnotations, "DynamicsWebApi.setConfig", "config.includeAnnotations");
+            ErrorHelper.stringParameterCheck(config.includeAnnotations, FUNCTION_NAME, "config.includeAnnotations");
             internalConfig.includeAnnotations = config.includeAnnotations;
         }
 
         if (config?.timeout) {
-            ErrorHelper.numberParameterCheck(config.timeout, "DynamicsWebApi.setConfig", "config.timeout");
+            ErrorHelper.numberParameterCheck(config.timeout, FUNCTION_NAME, "config.timeout");
             internalConfig.timeout = config.timeout;
         }
 
         if (config?.maxPageSize) {
-            ErrorHelper.numberParameterCheck(config.maxPageSize, "DynamicsWebApi.setConfig", "config.maxPageSize");
+            ErrorHelper.numberParameterCheck(config.maxPageSize, FUNCTION_NAME, "config.maxPageSize");
             internalConfig.maxPageSize = config.maxPageSize;
         }
 
         if (config?.returnRepresentation) {
-            ErrorHelper.boolParameterCheck(config.returnRepresentation, "DynamicsWebApi.setConfig", "config.returnRepresentation");
+            ErrorHelper.boolParameterCheck(config.returnRepresentation, FUNCTION_NAME, "config.returnRepresentation");
             internalConfig.returnRepresentation = config.returnRepresentation;
         }
 
         if (config?.useEntityNames) {
-            ErrorHelper.boolParameterCheck(config.useEntityNames, "DynamicsWebApi.setConfig", "config.useEntityNames");
+            ErrorHelper.boolParameterCheck(config.useEntityNames, FUNCTION_NAME, "config.useEntityNames");
             internalConfig.useEntityNames = config.useEntityNames;
         }
 
@@ -93,15 +110,15 @@ export class ConfigurationUtility {
         }
 
         if (!global.DWA_BROWSER && config?.proxy) {
-            ErrorHelper.parameterCheck(config.proxy, "DynamicsWebApi.setConfig", "config.proxy");
+            ErrorHelper.parameterCheck(config.proxy, FUNCTION_NAME, "config.proxy");
 
             if (config.proxy.url) {
-                ErrorHelper.stringParameterCheck(config.proxy.url, "DynamicsWebApi.setConfig", "config.proxy.url");
+                ErrorHelper.stringParameterCheck(config.proxy.url, FUNCTION_NAME, "config.proxy.url");
 
                 if (config.proxy.auth) {
-                    ErrorHelper.parameterCheck(config.proxy.auth, "DynamicsWebApi.setConfig", "config.proxy.auth");
-                    ErrorHelper.stringParameterCheck(config.proxy.auth.username, "DynamicsWebApi.setConfig", "config.proxy.auth.username");
-                    ErrorHelper.stringParameterCheck(config.proxy.auth.password, "DynamicsWebApi.setConfig", "config.proxy.auth.password");
+                    ErrorHelper.parameterCheck(config.proxy.auth, FUNCTION_NAME, "config.proxy.auth");
+                    ErrorHelper.stringParameterCheck(config.proxy.auth.username, FUNCTION_NAME, "config.proxy.auth.username");
+                    ErrorHelper.stringParameterCheck(config.proxy.auth.password, FUNCTION_NAME, "config.proxy.auth.password");
                 }
             }
 
diff --git a/tests/searchApi.convertQuery.spec.ts b/tests/searchApi.convertQuery.spec.ts
diff --git a/tests/searchApi.spec.ts b/tests/searchApi.spec.ts
diff --git a/tests/stubs.ts b/tests/stubs.ts
