@depup/typesense 3.0.3-depup.0

package/src/Typesense/RequestWithCache.ts

@@ -0,0 +1,209 @@
+import { AxiosRequestConfig } from "axios";
+import type { DocumentSchema } from "./Documents";
+import { HttpClient } from "./ApiCall";
+import type { RequestParams } from "./Types";
+
+const defaultCacheResponseForSeconds = 2 * 60;
+const defaultMaxSize = 100;
+
+interface CacheEntry<T> {
+  requestTimestamp: number;
+  response: T;
+}
+
+interface PromiseCacheEntry<T> {
+  requestTimestamp: number;
+  responsePromise: Promise<T>;
+}
+
+export default class RequestWithCache {
+  private responseCache: Map<string, CacheEntry<unknown>> = new Map();
+  private responsePromiseCache: Map<string, PromiseCacheEntry<unknown>> =
+    new Map();
+
+  clearCache() {
+    this.responseCache = new Map();
+    this.responsePromiseCache = new Map();
+  }
+
+  async perform<
+    const TContext extends HttpClient,
+    const TMethod extends keyof HttpClient,
+    const TDoc extends DocumentSchema[],
+    TResult,
+  >(
+    requestContext: TContext,
+    methodName: TMethod,
+    requestParams: RequestParams<TDoc>,
+    cacheOptions: CacheOptions | undefined,
+  ): Promise<TResult> {
+    const {
+      cacheResponseForSeconds = defaultCacheResponseForSeconds,
+      maxSize = defaultMaxSize,
+    } = cacheOptions || {};
+    const isCacheDisabled =
+      cacheOptions === undefined ||
+      cacheResponseForSeconds <= 0 ||
+      maxSize <= 0;
+
+    const {
+      path,
+      queryParams,
+      body,
+      headers,
+      streamConfig,
+      abortSignal,
+      responseType,
+      isStreamingRequest,
+    } = requestParams;
+
+    if (isCacheDisabled) {
+      return this.executeRequest<TResult>(
+        requestContext,
+        methodName,
+        path,
+        queryParams,
+        body,
+        headers,
+        { abortSignal, responseType, streamConfig, isStreamingRequest },
+      );
+    }
+
+    const requestParamsJSON = JSON.stringify(requestParams);
+    const cacheEntry = this.responseCache.get(requestParamsJSON);
+    const now = Date.now();
+
+    if (cacheEntry) {
+      const isEntryValid =
+        now - cacheEntry.requestTimestamp < cacheResponseForSeconds * 1000;
+      if (isEntryValid) {
+        this.responseCache.delete(requestParamsJSON);
+        this.responseCache.set(requestParamsJSON, cacheEntry);
+        return cacheEntry.response as TResult;
+      } else {
+        this.responseCache.delete(requestParamsJSON);
+      }
+    }
+
+    const cachePromiseEntry = this.responsePromiseCache.get(requestParamsJSON);
+
+    if (cachePromiseEntry) {
+      const isEntryValid =
+        now - cachePromiseEntry.requestTimestamp <
+        cacheResponseForSeconds * 1000;
+      if (isEntryValid) {
+        this.responsePromiseCache.delete(requestParamsJSON);
+        this.responsePromiseCache.set(requestParamsJSON, cachePromiseEntry);
+        return cachePromiseEntry.responsePromise as Promise<TResult>;
+      } else {
+        this.responsePromiseCache.delete(requestParamsJSON);
+      }
+    }
+
+    const responsePromise = this.executeRequest<TResult>(
+      requestContext,
+      methodName,
+      path,
+      queryParams,
+      body,
+      headers,
+      { abortSignal, responseType, streamConfig, isStreamingRequest },
+    );
+
+    this.responsePromiseCache.set(requestParamsJSON, {
+      requestTimestamp: now,
+      responsePromise,
+    });
+
+    const response = await responsePromise;
+    this.responseCache.set(requestParamsJSON, {
+      requestTimestamp: now,
+      response: response,
+    });
+
+    const isCacheOverMaxSize = this.responseCache.size > maxSize;
+    if (isCacheOverMaxSize) {
+      const oldestEntry = this.responseCache.keys().next().value;
+      if (oldestEntry) {
+        this.responseCache.delete(oldestEntry);
+      }
+    }
+    const isResponsePromiseCacheOverMaxSize =
+      this.responsePromiseCache.size > maxSize;
+    if (isResponsePromiseCacheOverMaxSize) {
+      const oldestEntry = this.responsePromiseCache.keys().next().value;
+      if (oldestEntry) {
+        this.responsePromiseCache.delete(oldestEntry);
+      }
+    }
+    return response;
+  }
+
+  private executeRequest<TResult>(
+    context: HttpClient,
+    methodName: keyof HttpClient,
+    path: string,
+    queryParams: Record<string, unknown> = {},
+    body?: unknown,
+    headers?: Record<string, string>,
+    options?: {
+      abortSignal?: AbortSignal | null;
+      responseType?: AxiosRequestConfig["responseType"];
+      streamConfig?: any;
+      isStreamingRequest: boolean | undefined;
+    },
+  ): Promise<TResult> {
+    const method = context[methodName];
+
+    switch (methodName) {
+      case "get":
+        return (method as HttpClient["get"]).call(context, path, queryParams, {
+          abortSignal: options?.abortSignal,
+          responseType: options?.responseType,
+          streamConfig: options?.streamConfig,
+          isStreamingRequest: options?.isStreamingRequest,
+        }) as Promise<TResult>;
+
+      case "delete":
+        return (method as HttpClient["delete"]).call(
+          context,
+          path,
+          queryParams,
+        ) as Promise<TResult>;
+
+      case "post":
+        return (method as HttpClient["post"]).call(
+          context,
+          path,
+          body,
+          queryParams,
+          headers || {},
+          {
+            abortSignal: options?.abortSignal,
+            responseType: options?.responseType,
+            streamConfig: options?.streamConfig,
+            isStreamingRequest: options?.isStreamingRequest,
+          },
+        ) as Promise<TResult>;
+
+      case "put":
+      case "patch":
+        return (method as HttpClient[typeof methodName]).call(
+          context,
+          path,
+          body,
+          queryParams,
+        ) as Promise<TResult>;
+
+      default:
+        throw new Error(`Unsupported method: ${String(methodName)}`);
+    }
+  }
+}
+
+interface CacheOptions {
+  cacheResponseForSeconds?: number;
+  maxSize?: number;
+}
+
+export type { RequestParams } from "./Types";

package/src/Typesense/SearchClient.ts

@@ -0,0 +1,64 @@
+import Configuration, { ConfigurationOptions } from "./Configuration";
+import ApiCall from "./ApiCall";
+import MultiSearch from "./MultiSearch";
+import { DocumentSchema } from "./Documents";
+import { SearchOnlyCollection } from "./SearchOnlyCollection";
+
+export default class SearchClient {
+  public readonly multiSearch: MultiSearch;
+  private readonly configuration: Configuration;
+  private readonly apiCall: ApiCall;
+  private readonly individualCollections: Record<
+    string,
+    SearchOnlyCollection<DocumentSchema>
+  >;
+
+  constructor(options: ConfigurationOptions) {
+    options.sendApiKeyAsQueryParam = options.sendApiKeyAsQueryParam ?? true;
+    if (
+      options.sendApiKeyAsQueryParam === true &&
+      (options.apiKey || "").length > 2000
+    ) {
+      console.warn(
+        "[typesense] API Key is longer than 2000 characters which is over the allowed limit, so disabling sending it as a query parameter."
+      );
+      options.sendApiKeyAsQueryParam = false;
+    }
+
+    this.configuration = new Configuration(options);
+    this.apiCall = new ApiCall(this.configuration);
+    this.multiSearch = new MultiSearch(this.apiCall, this.configuration, true);
+    this.individualCollections = {};
+  }
+
+  clearCache() {
+    this.multiSearch.clearCache();
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    Object.entries(this.individualCollections).forEach(([_, collection]) => {
+      collection.documents().clearCache();
+    });
+  }
+
+  collections<TDocumentSchema extends DocumentSchema>(
+    collectionName: string,
+  ): SearchOnlyCollection<TDocumentSchema> {
+    if (!collectionName) {
+      throw new Error(
+        "Typesense.SearchClient only supports search operations, so the collectionName that needs to " +
+          "be searched must be specified. Use Typesense.Client if you need to access the collection object."
+      );
+    } else {
+      if (this.individualCollections[collectionName] === undefined) {
+        this.individualCollections[collectionName] = new SearchOnlyCollection(
+          collectionName,
+          this.apiCall,
+          this.configuration
+        );
+      }
+      return this.individualCollections[
+        collectionName
+      ] as SearchOnlyCollection<TDocumentSchema>;
+    }
+  }
+}

package/src/Typesense/SearchOnlyCollection.ts

@@ -0,0 +1,24 @@
+import type { DocumentSchema } from "./Documents";
+import ApiCall from "./ApiCall";
+import { SearchOnlyDocuments } from "./SearchOnlyDocuments";
+import type { SearchableDocuments } from "./Types";
+
+export class SearchOnlyCollection<T extends DocumentSchema> {
+  private readonly _documents: SearchableDocuments<T>;
+
+  constructor(
+    private readonly name: string,
+    private readonly apiCall: ApiCall,
+    private readonly configuration: any
+  ) {
+    this._documents = new SearchOnlyDocuments(
+      this.name,
+      this.apiCall,
+      this.configuration
+    );
+  }
+
+  documents(): SearchableDocuments<T> {
+    return this._documents;
+  }
+}

package/src/Typesense/SearchOnlyDocuments.ts

@@ -0,0 +1,87 @@
+import RequestWithCache from "./RequestWithCache";
+import ApiCall from "./ApiCall";
+import Configuration from "./Configuration";
+import Collections from "./Collections";
+import type {
+  DocumentSchema,
+  SearchOptions,
+  SearchParamsWithPreset,
+  SearchResponse,
+} from "./Documents";
+import { normalizeArrayableParams } from "./Utils";
+import { SearchableDocuments, SearchParams } from "./Types";
+
+const RESOURCEPATH = "/documents";
+
+export class SearchOnlyDocuments<T extends DocumentSchema>
+  implements SearchableDocuments<T>
+{
+  protected requestWithCache: RequestWithCache = new RequestWithCache();
+
+  constructor(
+    protected collectionName: string,
+    protected apiCall: ApiCall,
+    protected configuration: Configuration,
+  ) {}
+
+  clearCache() {
+    this.requestWithCache.clearCache();
+  }
+
+  async search<const Infix extends string>(
+    searchParameters: SearchParams<T, Infix> | SearchParamsWithPreset<T, Infix>,
+    {
+      cacheSearchResultsForSeconds = this.configuration
+        .cacheSearchResultsForSeconds,
+      abortSignal = null,
+    }: SearchOptions = {},
+  ): Promise<SearchResponse<T>> {
+    const additionalQueryParams = {};
+    if (this.configuration.useServerSideSearchCache === true) {
+      additionalQueryParams["use_cache"] = true;
+    }
+
+    const { streamConfig, ...rest } = normalizeArrayableParams<
+      T,
+      SearchParams<T, Infix>,
+      Infix
+    >(searchParameters);
+
+    const queryParams = {
+      ...additionalQueryParams,
+      ...rest,
+    };
+
+    const isStreamingRequest = queryParams.conversation_stream === true;
+
+    return this.requestWithCache.perform<
+      ApiCall,
+      "get",
+      [T],
+      SearchResponse<T>
+    >(
+      this.apiCall,
+      "get",
+      {
+        path: this.endpointPath("search"),
+        queryParams,
+        streamConfig,
+        abortSignal,
+        isStreamingRequest,
+      },
+      {
+        cacheResponseForSeconds: cacheSearchResultsForSeconds,
+      },
+    );
+  }
+
+  protected endpointPath(operation?: string) {
+    return `${Collections.RESOURCEPATH}/${encodeURIComponent(this.collectionName)}${RESOURCEPATH}${
+      operation === undefined ? "" : "/" + operation
+    }`;
+  }
+
+  static get RESOURCEPATH() {
+    return RESOURCEPATH;
+  }
+}

package/src/Typesense/Stats.ts

@@ -0,0 +1,31 @@
+import ApiCall from "./ApiCall";
+
+const RESOURCEPATH = "/stats.json";
+
+export interface EndpointStats {
+  [endpoint: string]: number;
+}
+
+export interface StatsResponse {
+  delete_latency_ms?: number;
+  delete_requests_per_second?: number;
+  import_latency_ms?: number;
+  import_requests_per_second?: number;
+  latency_ms?: EndpointStats;
+  overloaded_requests_per_second?: number;
+  pending_write_batches?: number;
+  requests_per_second?: EndpointStats;
+  search_latency_ms?: number;
+  search_requests_per_second?: number;
+  total_requests_per_second?: number;
+  write_latency_ms?: number;
+  write_requests_per_second?: number;
+}
+
+export default class Metrics {
+  constructor(private apiCall: ApiCall) {}
+
+  async retrieve(): Promise<StatsResponse> {
+    return this.apiCall.get(RESOURCEPATH);
+  }
+}

package/src/Typesense/Stemming.ts

@@ -0,0 +1,38 @@
+import type ApiCall from "./ApiCall";
+import StemmingDictionaries from "./StemmingDictionaries";
+import StemmingDictionary from "./StemmingDictionary";
+
+const RESOURCEPATH = "/stemming";
+
+export default class Stemming {
+  private readonly _stemmingDictionaries: StemmingDictionaries;
+  private readonly individualStemmingDictionaries: Record<
+    string,
+    StemmingDictionary
+  > = {};
+
+  constructor(private readonly apiCall: ApiCall) {
+    this.apiCall = apiCall;
+    this._stemmingDictionaries = new StemmingDictionaries(this.apiCall);
+  }
+
+  dictionaries(): StemmingDictionaries;
+  dictionaries(id: string): StemmingDictionary;
+  dictionaries(id?: string): StemmingDictionaries | StemmingDictionary {
+    if (id === undefined) {
+      return this._stemmingDictionaries;
+    } else {
+      if (this.individualStemmingDictionaries[id] === undefined) {
+        this.individualStemmingDictionaries[id] = new StemmingDictionary(
+          id,
+          this.apiCall,
+        );
+      }
+      return this.individualStemmingDictionaries[id];
+    }
+  }
+
+  static get RESOURCEPATH() {
+    return RESOURCEPATH;
+  }
+}

package/src/Typesense/StemmingDictionaries.ts

@@ -0,0 +1,59 @@
+import ApiCall from "./ApiCall";
+import type { StemmingDictionaryCreateSchema } from "./StemmingDictionary";
+
+const RESOURCEPATH = "/stemming/dictionaries";
+
+export interface StemmingDictionariesRetrieveSchema {
+  dictionaries: string[];
+}
+
+export default class StemmingDictionaries {
+  constructor(private readonly apiCall: ApiCall) {
+    this.apiCall = apiCall;
+  }
+
+  async upsert(
+    id: string,
+    wordRootCombinations: StemmingDictionaryCreateSchema[] | string,
+  ): Promise<StemmingDictionaryCreateSchema[] | string> {
+    const wordRootCombinationsInJSONLFormat = Array.isArray(
+      wordRootCombinations,
+    )
+      ? wordRootCombinations.map((combo) => JSON.stringify(combo)).join("\n")
+      : wordRootCombinations;
+
+    const resultsInJSONLFormat = await this.apiCall.performRequest<string>(
+
+      "post",
+      this.endpointPath("import"),
+      {
+        queryParameters: {id},
+        bodyParameters: wordRootCombinationsInJSONLFormat,
+        additionalHeaders: {"Content-Type": "text/plain"},
+        skipConnectionTimeout: true,
+      }
+    );
+
+    return Array.isArray(wordRootCombinations)
+      ? resultsInJSONLFormat
+          .split("\n")
+          .map((line) => JSON.parse(line) as StemmingDictionaryCreateSchema)
+      : resultsInJSONLFormat;
+  }
+
+  async retrieve(): Promise<StemmingDictionariesRetrieveSchema> {
+    return this.apiCall.get<StemmingDictionariesRetrieveSchema>(
+      this.endpointPath(),
+    );
+  }
+
+  private endpointPath(operation?: string): string {
+    return operation === undefined
+      ? `${StemmingDictionaries.RESOURCEPATH}`
+      : `${StemmingDictionaries.RESOURCEPATH}/${encodeURIComponent(operation)}`;
+  }
+
+  static get RESOURCEPATH() {
+    return RESOURCEPATH;
+  }
+}

package/src/Typesense/StemmingDictionary.ts

@@ -0,0 +1,37 @@
+import ApiCall from "./ApiCall";
+import StemmingDictionaries from "./StemmingDictionaries";
+
+export interface StemmingDictionaryCreateSchema {
+  root: string;
+  word: string;
+}
+
+export interface StemmingDictionarySchema {
+  id: string;
+  words: StemmingDictionaryCreateSchema[];
+}
+
+export interface StemmingDictionaryDeleteSchema {
+  id: string;
+}
+
+export default class StemmingDictionary {
+  constructor(
+    private id: string,
+    private apiCall: ApiCall,
+  ) {}
+
+  async retrieve(): Promise<StemmingDictionarySchema> {
+    return this.apiCall.get<StemmingDictionarySchema>(this.endpointPath());
+  }
+
+  async delete(): Promise<StemmingDictionaryDeleteSchema> {
+    return this.apiCall.delete<StemmingDictionaryDeleteSchema>(
+      this.endpointPath(),
+    );
+  }
+
+  private endpointPath(): string {
+    return `${StemmingDictionaries.RESOURCEPATH}/${encodeURIComponent(this.id)}`;
+  }
+}

package/src/Typesense/Stopword.ts

@@ -0,0 +1,31 @@
+import ApiCall from "./ApiCall";
+import Stopwords from "./Stopwords";
+
+export interface StopwordSchema {
+  id: string;
+  stopwords: string[] | { id: string; stopwords: string[] };
+  locale?: string;
+}
+
+export interface StopwordDeleteSchema {
+  id: string;
+}
+
+export default class Stopword {
+  constructor(
+    private stopwordId: string,
+    private apiCall: ApiCall,
+  ) {}
+
+  async retrieve(): Promise<StopwordSchema> {
+    return this.apiCall.get<StopwordSchema>(this.endpointPath());
+  }
+
+  async delete(): Promise<StopwordDeleteSchema> {
+    return this.apiCall.delete<StopwordDeleteSchema>(this.endpointPath());
+  }
+
+  private endpointPath(): string {
+    return `${Stopwords.RESOURCEPATH}/${encodeURIComponent(this.stopwordId)}`;
+  }
+}

package/src/Typesense/Stopwords.ts

@@ -0,0 +1,41 @@
+import ApiCall from "./ApiCall";
+import { StopwordSchema } from "./Stopword";
+
+const RESOURCEPATH = "/stopwords";
+
+export interface StopwordCreateSchema {
+  stopwords: string[];
+  locale?: string;
+}
+
+export interface StopwordsRetrieveSchema {
+  stopwords: StopwordSchema[];
+}
+
+export default class Stopwords {
+  constructor(private apiCall: ApiCall) {}
+
+  async upsert(
+    stopwordId: string,
+    params: StopwordCreateSchema,
+  ): Promise<StopwordSchema> {
+    return this.apiCall.put<StopwordSchema>(
+      this.endpointPath(stopwordId),
+      params,
+    );
+  }
+
+  async retrieve(): Promise<StopwordsRetrieveSchema> {
+    return this.apiCall.get<StopwordsRetrieveSchema>(this.endpointPath());
+  }
+
+  private endpointPath(operation?: string): string {
+    return `${Stopwords.RESOURCEPATH}${
+      operation === undefined ? "" : "/" + encodeURIComponent(operation)
+    }`;
+  }
+
+  static get RESOURCEPATH(): string {
+    return RESOURCEPATH;
+  }
+}

package/src/Typesense/Synonym.ts

@@ -0,0 +1,42 @@
+import ApiCall from "./ApiCall";
+import Collections from "./Collections";
+import Synonyms, { SynonymCreateSchema } from "./Synonyms";
+
+export interface SynonymSchema extends SynonymCreateSchema {
+  id: string;
+}
+
+export interface SynonymDeleteSchema {
+  id: string;
+}
+
+/**
+ * @deprecated Deprecated starting with Typesense Server v30. Please migrate to `client.synonymSets` (new Synonym Sets APIs).
+ */
+export default class Synonym {
+  private static hasWarnedDeprecation = false;
+  constructor(
+    private collectionName: string,
+    private synonymId: string,
+    private apiCall: ApiCall
+  ) {}
+
+  async retrieve(): Promise<SynonymSchema> {
+    return this.apiCall.get<SynonymSchema>(this.endpointPath());
+  }
+
+  async delete(): Promise<SynonymDeleteSchema> {
+    return this.apiCall.delete<SynonymDeleteSchema>(this.endpointPath());
+  }
+
+  private endpointPath(): string {
+    if (!Synonym.hasWarnedDeprecation) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[typesense] 'synonym' APIs are deprecated starting with Typesense Server v30. Please migrate to synonym sets 'synonym_sets'.",
+      );
+      Synonym.hasWarnedDeprecation = true;
+    }
+    return `${Collections.RESOURCEPATH}/${encodeURIComponent(this.collectionName)}${Synonyms.RESOURCEPATH}/${encodeURIComponent(this.synonymId)}`;
+  }
+}