Merge pull request #290 from tharropoulos/infix

feat: add type-safe infix parameter validation & separate test TypeScript config

Author: jasonbosco

package.json

@@ -98,6 +98,7 @@
     "build": "npm run build:tsc && npm run build:web:dev && npm run build:web:prod",
     "test:vitest": "vitest",
     "build:tsc": "tsc",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "build:web:dev": "webpack --config webpack.config.js --mode development",
     "build:web:prod": "webpack --config webpack.config.js --mode production",
     "build:tsc:watch": "tsc --watch",

src/Typesense/Documents.ts

@@ -40,8 +40,10 @@ export type ImportResponse = ImportResponseSuccess | ImportResponseFail;
 
 export type DocumentSchema = Record<string, any>;
 
-export interface SearchParamsWithPreset<T extends DocumentSchema>
-  extends Partial<SearchParams<T>> {
+export interface SearchParamsWithPreset<
+  T extends DocumentSchema,
+  Infix extends string,
+> extends Partial<SearchParams<T, Infix>> {
   preset: string;
 }
 

src/Typesense/Keys.ts

@@ -10,8 +10,10 @@ export interface KeysRetrieveSchema {
   keys: KeySchema[];
 }
 
-export interface GenerateScopedSearchKeyParams<T extends DocumentSchema>
-  extends Partial<SearchParams<T>> {
+export interface GenerateScopedSearchKeyParams<
+  T extends DocumentSchema,
+  Infix extends string,
+> extends Partial<SearchParams<T, Infix>> {
   expires_at?: number;
   cache_ttl?: number;
   limit_multi_searches?: number;
@@ -30,15 +32,17 @@ export default class Keys {
     return this.apiCall.get<KeysRetrieveSchema>(RESOURCEPATH);
   }
 
-  generateScopedSearchKey<T extends DocumentSchema>(
+  generateScopedSearchKey<T extends DocumentSchema, const Infix extends string>(
     searchKey: string,
-    parameters: GenerateScopedSearchKeyParams<T>,
+    parameters: GenerateScopedSearchKeyParams<T, Infix>,
   ): string {
     // Note: only a key generated with the `documents:search` action will be
-    // accepted by the server, when usined with the search endpoint.
-    const normalizedParams = normalizeArrayableParams<T, SearchParams<T>>(
-      parameters,
-    );
+    // accepted by the server, when used with the search endpoint.
+    const normalizedParams = normalizeArrayableParams<
+      T,
+      SearchParams<T, Infix>,
+      Infix
+    >(parameters);
     const paramsJSON = JSON.stringify(normalizedParams);
     const digest = Buffer.from(
       createHmac("sha256", searchKey).update(paramsJSON).digest("base64"),

src/Typesense/MultiSearch.ts

@@ -35,48 +35,63 @@ export default class MultiSearch {
     this.requestWithCache.clearCache();
   }
 
-  async perform<const T extends DocumentSchema[] = []>(
-    searchRequests: MultiSearchRequestsWithUnionSchema<T[number]>,
-    commonParams?: MultiSearchUnionParameters<T[number]>,
+  async perform<
+    const T extends DocumentSchema[] = [],
+    const Infix extends string = string,
+  >(
+    searchRequests: MultiSearchRequestsWithUnionSchema<T[number], Infix>,
+    commonParams?: MultiSearchUnionParameters<T[number], Infix>,
     options?: { cacheSearchResultsForSeconds?: number },
   ): Promise<UnionSearchResponse<T[number]>>;
 
-  async perform<const T extends DocumentSchema[] = []>(
-    searchRequests: MultiSearchRequestsWithoutUnionSchema<T[number]>,
-    commonParams?: MultiSearchResultsParameters<T>,
+  async perform<
+    const T extends DocumentSchema[] = [],
+    const Infix extends string = string,
+  >(
+    searchRequests: MultiSearchRequestsWithoutUnionSchema<T[number], Infix>,
+    commonParams?: MultiSearchResultsParameters<T, Infix>,
     options?: { cacheSearchResultsForSeconds?: number },
   ): Promise<{
     results: { [Index in keyof T]: SearchResponse<T[Index]> } & {
       length: T["length"];
     };
   }>;
 
-  async perform<const T extends DocumentSchema[] = []>(
-    searchRequests: MultiSearchRequestsSchema<T[number]>,
+  async perform<
+    const T extends DocumentSchema[] = [],
+    const Infix extends string = string,
+  >(
+    searchRequests: MultiSearchRequestsSchema<T[number], Infix>,
     commonParams?:
-      | MultiSearchUnionParameters<T[number]>
-      | MultiSearchResultsParameters<T>,
+      | MultiSearchUnionParameters<T[number], Infix>
+      | MultiSearchResultsParameters<T, Infix>,
     {
       cacheSearchResultsForSeconds = this.configuration
         .cacheSearchResultsForSeconds,
     }: { cacheSearchResultsForSeconds?: number } = {},
-  ): Promise<MultiSearchResponse<T>> {
+  ): Promise<MultiSearchResponse<T, Infix>> {
     const params = commonParams ? { ...commonParams } : {};
 
     if (this.configuration.useServerSideSearchCache === true) {
       params.use_cache = true;
     }
 
     const normalizedSearchRequests: Omit<typeof searchRequests, "searches"> & {
-      searches: ExtractBaseTypes<SearchParams<T[number]>>[];
+      searches: ExtractBaseTypes<SearchParams<T[number], Infix>>[];
     } = {
       union: searchRequests.union,
-      searches: searchRequests.searches.map(normalizeArrayableParams),
+      searches: searchRequests.searches.map(
+        normalizeArrayableParams<
+          T[number],
+          SearchParams<T[number], Infix>,
+          Infix
+        >,
+      ),
     };
 
     const { streamConfig, ...paramsWithoutStream } = params;
     const normalizedQueryParams = normalizeArrayableParams(
-      paramsWithoutStream as SearchParams<T[number]>,
+      paramsWithoutStream as SearchParams<T[number], Infix>,
     );
 
     return this.requestWithCache.perform(

src/Typesense/Preset.ts

@@ -3,7 +3,7 @@ import { DocumentSchema } from "./Documents";
 import Presets, { PresetCreateSchema } from "./Presets";
 
 export interface PresetSchema<T extends DocumentSchema>
-  extends PresetCreateSchema<T> {
+  extends PresetCreateSchema<T, string> {
   name: string;
 }
 

src/Typesense/Presets.ts

@@ -6,8 +6,11 @@ import { normalizeArrayableParams } from "./Utils";
 
 const RESOURCEPATH = "/presets";
 
-export interface PresetCreateSchema<T extends DocumentSchema> {
-  value: SearchParams<T> | MultiSearchRequestsSchema<T>;
+export interface PresetCreateSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> {
+  value: SearchParams<T, Infix> | MultiSearchRequestsSchema<T, Infix>;
 }
 
 export interface PresetsRetrieveSchema<T extends DocumentSchema> {
@@ -17,22 +20,24 @@ export interface PresetsRetrieveSchema<T extends DocumentSchema> {
 export default class Presets {
   constructor(private apiCall: ApiCall) {}
 
-  async upsert<T extends DocumentSchema>(
+  async upsert<T extends DocumentSchema, const Infix extends string>(
     presetId: string,
-    params: PresetCreateSchema<T>,
+    params: PresetCreateSchema<T, Infix>,
   ): Promise<PresetSchema<T>> {
     if (typeof params.value === "object" && "searches" in params.value) {
       const normalizedParams = params.value.searches.map((search) =>
-        normalizeArrayableParams<T, SearchParams<T>>(search),
+        normalizeArrayableParams<T, SearchParams<T, Infix>, Infix>(search),
       );
 
       return this.apiCall.put<PresetSchema<T>>(this.endpointPath(presetId), {
         value: { searches: normalizedParams },
       });
     }
-    const normalizedParams = normalizeArrayableParams<T, SearchParams<T>>(
-      params.value,
-    );
+    const normalizedParams = normalizeArrayableParams<
+      T,
+      SearchParams<T, Infix>,
+      Infix
+    >(params.value);
 
     return this.apiCall.put<PresetSchema<T>>(this.endpointPath(presetId), {
       value: normalizedParams,

src/Typesense/SearchOnlyDocuments.ts

@@ -28,8 +28,8 @@ export class SearchOnlyDocuments<T extends DocumentSchema>
     this.requestWithCache.clearCache();
   }
 
-  async search(
-    searchParameters: SearchParams<T> | SearchParamsWithPreset<T>,
+  async search<const Infix extends string>(
+    searchParameters: SearchParams<T, Infix> | SearchParamsWithPreset<T, Infix>,
     {
       cacheSearchResultsForSeconds = this.configuration
         .cacheSearchResultsForSeconds,
@@ -43,7 +43,8 @@ export class SearchOnlyDocuments<T extends DocumentSchema>
 
     const { streamConfig, ...rest } = normalizeArrayableParams<
       T,
-      SearchParams<T>
+      SearchParams<T, Infix>,
+      Infix
     >(searchParameters);
 
     const queryParams = {