@depup/typesense 3.0.3-depup.0

package/src/Typesense/SynonymSet.ts

@@ -0,0 +1,57 @@
+import ApiCall from "./ApiCall";
+import SynonymSets from "./SynonymSets";
+import type { SynonymSetCreateSchema, SynonymSetSchema } from "./SynonymSets";
+import SynonymSetItems from "./SynonymSetItems";
+import SynonymSetItem from "./SynonymSetItem";
+
+export interface SynonymSetDeleteSchema {
+  name: string;
+}
+
+export type SynonymSetRetrieveSchema = SynonymSetCreateSchema;
+
+export default class SynonymSet {
+  private readonly _items: SynonymSetItems;
+  private individualItems: Record<string, SynonymSetItem> = {};
+  constructor(
+    private synonymSetName: string,
+    private apiCall: ApiCall,
+  ) {
+    this._items = new SynonymSetItems(this.synonymSetName, apiCall);
+  }
+
+  async upsert(
+    params: SynonymSetCreateSchema,
+  ): Promise<SynonymSetCreateSchema> {
+    return this.apiCall.put<SynonymSetSchema>(this.endpointPath(), params);
+  }
+
+  async retrieve(): Promise<SynonymSetRetrieveSchema> {
+    return this.apiCall.get<SynonymSetRetrieveSchema>(this.endpointPath());
+  }
+
+  async delete(): Promise<SynonymSetDeleteSchema> {
+    return this.apiCall.delete<SynonymSetDeleteSchema>(this.endpointPath());
+  }
+
+  items(): SynonymSetItems;
+  items(itemId: string): SynonymSetItem;
+  items(itemId?: string): SynonymSetItems | SynonymSetItem {
+    if (itemId === undefined) {
+      return this._items;
+    } else {
+      if (this.individualItems[itemId] === undefined) {
+        this.individualItems[itemId] = new SynonymSetItem(
+          this.synonymSetName,
+          itemId,
+          this.apiCall,
+        );
+      }
+      return this.individualItems[itemId];
+    }
+  }
+
+  private endpointPath(): string {
+    return `${SynonymSets.RESOURCEPATH}/${encodeURIComponent(this.synonymSetName)}`;
+  }
+}

package/src/Typesense/SynonymSetItem.ts

@@ -0,0 +1,28 @@
+import ApiCall from "./ApiCall";
+import SynonymSets, { SynonymItemSchema } from "./SynonymSets";
+
+export interface SynonymSetItemDeleteSchema {
+  id: string;
+}
+
+export default class SynonymSetItem {
+  constructor(
+    private synonymSetName: string,
+    private itemId: string,
+    private apiCall: ApiCall,
+  ) {}
+
+  async retrieve(): Promise<SynonymItemSchema> {
+    return this.apiCall.get<SynonymItemSchema>(this.endpointPath());
+  }
+
+  async delete(): Promise<SynonymSetItemDeleteSchema> {
+    return this.apiCall.delete<SynonymSetItemDeleteSchema>(this.endpointPath());
+  }
+
+  private endpointPath(): string {
+    return `${SynonymSets.RESOURCEPATH}/${encodeURIComponent(this.synonymSetName)}/items/${encodeURIComponent(this.itemId)}`;
+  }
+}
+
+

package/src/Typesense/SynonymSetItems.ts

@@ -0,0 +1,31 @@
+import ApiCall from "./ApiCall";
+import SynonymSets, { SynonymItemSchema } from "./SynonymSets";
+
+export default class SynonymSetItems {
+  constructor(
+    private synonymSetName: string,
+    private apiCall: ApiCall,
+  ) {}
+
+  async upsert(
+    itemId: string,
+    params: Omit<SynonymItemSchema, "id">,
+  ): Promise<SynonymItemSchema> {
+    return this.apiCall.put<SynonymItemSchema>(
+      this.endpointPath(itemId),
+      params,
+    );
+  }
+
+  async retrieve(): Promise<SynonymItemSchema[]> {
+    return this.apiCall.get<SynonymItemSchema[]>(this.endpointPath());
+  }
+
+  private endpointPath(operation?: string): string {
+    return `${SynonymSets.RESOURCEPATH}/${encodeURIComponent(this.synonymSetName)}/items${
+      operation === undefined ? "" : "/" + encodeURIComponent(operation)
+    }`;
+  }
+}
+
+

package/src/Typesense/SynonymSets.ts

@@ -0,0 +1,30 @@
+import ApiCall from "./ApiCall";
+
+export interface SynonymItemSchema {
+  id: string;
+  synonyms: string[];
+  root?: string;
+  locale?: string;
+  symbols_to_index?: string[];
+}
+
+export interface SynonymSetCreateSchema {
+  items: SynonymItemSchema[];
+}
+
+export interface SynonymSetSchema extends SynonymSetCreateSchema {
+  name: string;
+}
+
+export interface SynonymSetsRetrieveSchema {
+  synonym_sets: SynonymSetSchema[];
+}
+
+export default class SynonymSets {
+  constructor(private apiCall: ApiCall) {}
+  static readonly RESOURCEPATH = "/synonym_sets";
+
+  async retrieve(): Promise<SynonymSetSchema[]> {
+    return this.apiCall.get<SynonymSetSchema[]>(SynonymSets.RESOURCEPATH);
+  }
+}

package/src/Typesense/Synonyms.ts

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

package/src/Typesense/Types.ts

@@ -0,0 +1,355 @@
+import type { AxiosRequestConfig } from "axios";
+import type { BaseStreamConfig, StreamConfig } from "./Configuration";
+import type {
+  DocumentSchema,
+  SearchParamsWithPreset,
+  SearchOptions,
+  SearchResponse,
+  DocumentWriteParameters,
+  DeleteQuery,
+  DeleteResponse,
+  ImportResponse,
+  DocumentsExportParameters,
+} from "./Documents";
+
+export type DropTokensMode = "right_to_left" | "left_to_right" | "both_sides:3";
+
+export type OperationMode = "off" | "always" | "fallback";
+
+export type CommaSeparated<
+  T extends string,
+  ToExtend,
+  OriginalString extends string = T,
+  Previous extends string[] = [],
+> = T extends `${infer Start},${infer Rest}`
+  ? TrimString<Start> extends ToExtend
+    ? CommaSeparated<
+        Rest,
+        ToExtend,
+        OriginalString,
+        [...Previous, TrimString<Start>]
+      >
+    : {
+        error: "Invalid operation mode";
+        value: TrimString<Start>;
+      }
+  : TrimString<T> extends ToExtend
+    ? OriginalString
+    : {
+        error: "Invalid operation mode";
+        value: TrimString<T>;
+      };
+
+export type MessageChunk = {
+  message: string;
+  conversation_id: string;
+};
+
+export type UnionArrayKeys<T> = {
+  [K in keyof T]: T[K] extends undefined
+    ? never
+    : NonNullable<T[K]> extends infer R
+      ? R extends R[]
+        ? never
+        : R extends (infer U)[] | infer U
+          ? U[] extends R
+            ? K
+            : never
+          : never
+      : never;
+}[keyof T] &
+  keyof T;
+
+export type UnionArraySearchParams<T extends DocumentSchema = DocumentSchema> =
+  UnionArrayKeys<T>;
+
+export type ArraybleParams<T extends DocumentSchema = DocumentSchema> = {
+  readonly [K in UnionArraySearchParams<T>]: string;
+};
+
+export type ExtractBaseTypes<T> = {
+  [K in keyof T]: K extends UnionArrayKeys<T>
+    ? T[K] extends (infer U)[] | infer U
+      ? U
+      : T[K]
+    : T[K];
+};
+
+export const arrayableParams: ArraybleParams = {
+  query_by: "query_by",
+  query_by_weights: "query_by_weights",
+  facet_by: "facet_by",
+  group_by: "group_by",
+  include_fields: "include_fields",
+  exclude_fields: "exclude_fields",
+  highlight_fields: "highlight_fields",
+  highlight_full_fields: "highlight_full_fields",
+  pinned_hits: "pinned_hits",
+  hidden_hits: "hidden_hits",
+  infix: "infix",
+  override_tags: "override_tags",
+  num_typos: "num_typos",
+  prefix: "prefix",
+  synonym_sets: "synonym_sets",
+  sort_by: "sort_by",
+};
+
+export interface SearchParams<
+  TDoc extends DocumentSchema,
+  Infix extends string = string,
+> {
+  // From https://typesense.org/docs/latest/api/documents.html#arguments
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- Can't use `object` here, it needs to intersect with `{}`
+  q?: "*" | (string & {});
+  query_by?: string | string[];
+  query_by_weights?: string | number[];
+  prefix?: string | boolean | boolean[]; // default: true
+  filter_by?: string;
+  max_filter_by_candidates?: number; // default: 4
+  enable_synonyms?: boolean; // default: true
+  enable_analytics?: boolean; // default: true
+  filter_curated_hits?: boolean; // default: false
+  enable_lazy_filter?: boolean; // default: false
+  sort_by?: string | string[]; // default: text match desc
+  facet_by?: string | string[];
+  max_facet_values?: number;
+  facet_sample_threshold?: number;
+  facet_sample_percent?: number;
+  facet_query?: string;
+  facet_query_num_typos?: number;
+  facet_return_parent?: string;
+  facet_strategy?: "exhaustive" | "top_values" | "automatic";
+  page?: number; // default: 1
+  per_page?: number; // default: 10, max 250
+  group_by?: string | string[];
+  group_limit?: number; // default:
+  group_missing_values?: boolean;
+  include_fields?: string | string[];
+  exclude_fields?: string | string[];
+  highlight_fields?: string | string[]; // default: all queried fields
+  highlight_full_fields?: string | string[]; // default: all fields
+  highlight_affix_num_tokens?: number; // default: 4
+  highlight_start_tag?: string; // default: <mark>
+  highlight_end_tag?: string; // default: </mark>
+  enable_highlight_v1?: boolean;
+  snippet_threshold?: number; // default: 30
+  nl_query?: boolean;
+  nl_model_id?: string;
+  nl_query_debug?: boolean;
+  nl_query_prompt_cache_ttl?: number;
+  num_typos?: string | number | number[]; // default: 2
+  min_len_1typo?: number;
+  min_len_2typo?: number;
+  split_join_tokens?: OperationMode;
+  exhaustive_search?: boolean;
+  drop_tokens_threshold?: number; // default: 10
+  drop_tokens_mode?: DropTokensMode;
+  typo_tokens_threshold?: number; // default: 100
+  pinned_hits?: string | string[];
+  synonym_sets?: string[] | string;
+  hidden_hits?: string | string[];
+  limit_hits?: number; // default: no limit
+  pre_segmented_query?: boolean;
+  enable_overrides?: boolean;
+  override_tags?: string | string[];
+  prioritize_exact_match?: boolean; // default: true
+  prioritize_token_position?: boolean;
+  prioritize_num_matching_fields?: boolean;
+  search_cutoff_ms?: number;
+  use_cache?: boolean;
+  max_candidates?: number;
+  infix?:
+    | CommaSeparated<Infix, OperationMode>
+    | OperationMode[]
+    | OperationMode;
+  preset?: string;
+  text_match_type?: "max_score" | "max_weight" | "sum_score";
+  vector_query?: string;
+  "x-typesense-api-key"?: string;
+  "x-typesense-user-id"?: string;
+  offset?: number;
+  limit?: number;
+  stopwords?: string;
+  conversation?: boolean;
+  validate_field_names?: boolean;
+  conversation_stream?: boolean;
+  conversation_model_id?: string;
+  conversation_id?: string;
+  voice_query?: string;
+  streamConfig?: StreamConfig<TDoc>;
+}
+
+export interface SearchResponseRequestParams {
+  collection_name?: string;
+  q?: string;
+  page?: number;
+  per_page?: number;
+  first_q?: string;
+  voice_query?: {
+    transcribed_query?: string;
+  };
+}
+
+export interface SearchableDocuments<
+  T extends DocumentSchema = DocumentSchema,
+  Infix extends string = string,
+> {
+  search(
+    searchParameters: SearchParams<T, Infix> | SearchParamsWithPreset<T, Infix>,
+    options: SearchOptions,
+  ): Promise<SearchResponse<T>>;
+  clearCache(): void;
+}
+
+export interface WriteableDocuments<T> {
+  create(document: T, options: DocumentWriteParameters): Promise<T>;
+  upsert(document: T, options: DocumentWriteParameters): Promise<T>;
+  update(document: T, options: DocumentWriteParameters): Promise<T>;
+  delete(query: DeleteQuery): Promise<DeleteResponse>;
+  import(
+    documents: T[] | string,
+    options: DocumentWriteParameters,
+  ): Promise<string | ImportResponse[]>;
+  export(options: DocumentsExportParameters): Promise<string>;
+}
+
+export interface MultiSearchUnionStreamConfig<T extends DocumentSchema>
+  extends BaseStreamConfig {
+  onComplete?: (data: UnionSearchResponse<T>) => void;
+}
+
+export interface MultiSearchResultsStreamConfig<T extends DocumentSchema[]>
+  extends BaseStreamConfig {
+  onComplete?: (data: {
+    results: { [Index in keyof T]: SearchResponse<T[Index]> } & {
+      length: T["length"];
+    };
+  }) => void;
+}
+export interface RequestParams<T extends DocumentSchema[]> {
+  path: string;
+  queryParams?: Record<string, unknown>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  streamConfig?:
+    | StreamConfig<T[number]>
+    | MultiSearchResultsStreamConfig<T>
+    | MultiSearchUnionStreamConfig<T[number]>;
+  abortSignal?: AbortSignal | null;
+  responseType?: AxiosRequestConfig["responseType"] | undefined;
+  isStreamingRequest: boolean | undefined;
+}
+
+export interface MultiSearchRequestsWithUnionSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> extends SearchesMultiSearchesRequestSchema<T, Infix> {
+  union: true;
+}
+
+export interface MultiSearchRequestsWithoutUnionSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> extends SearchesMultiSearchesRequestSchema<T, Infix> {
+  union?: false | undefined;
+}
+
+export type MultiSearchRequestsSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> =
+  | MultiSearchRequestsWithUnionSchema<T, Infix>
+  | MultiSearchRequestsWithoutUnionSchema<T, Infix>;
+
+export interface UnionSearchResponse<T extends DocumentSchema>
+  extends Omit<SearchResponse<T>, "request_params"> {
+  union_request_params: SearchResponseRequestParams[];
+}
+
+export type MultiSearchResponse<
+  T extends DocumentSchema[],
+  Infix extends string,
+  R extends MultiSearchRequestsSchema<
+    T[number],
+    Infix
+  > = MultiSearchRequestsSchema<T[number], Infix>,
+> =
+  R extends MultiSearchRequestsWithUnionSchema<T[number], Infix>
+    ? UnionSearchResponse<T[number]>
+    : {
+        results: { [Index in keyof T]: SearchResponse<T[Index]> } & {
+          length: T["length"];
+        };
+      };
+
+export interface MultiSearchUnionStreamConfig<T extends DocumentSchema>
+  extends BaseStreamConfig {
+  onComplete?: (data: UnionSearchResponse<T>) => void;
+}
+
+export interface MultiSearchResultsStreamConfig<T extends DocumentSchema[]>
+  extends BaseStreamConfig {
+  onComplete?: (data: {
+    results: { [Index in keyof T]: SearchResponse<T[Index]> } & {
+      length: T["length"];
+    };
+  }) => void;
+}
+
+interface SearchesMultiSearchesRequestSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> {
+  searches: (
+    | MultiSearchRequestSchema<T, Infix>
+    | MultiSearchRequestWithPresetSchema<T, Infix>
+  )[];
+}
+
+interface BaseMultiSearchRequestSchema {
+  collection?: string;
+  rerank_hybrid_matches?: boolean;
+  "x-typesense-api-key"?: string;
+}
+
+type CommonMultiSearchParametersBase<
+  T extends DocumentSchema,
+  Infix extends string,
+> = Partial<
+  BaseMultiSearchRequestSchema & Omit<SearchParams<T, Infix>, "streamConfig">
+>;
+
+export type MultiSearchRequestSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> = BaseMultiSearchRequestSchema & Omit<SearchParams<T, Infix>, "streamConfig">;
+
+export type MultiSearchRequestWithPresetSchema<
+  T extends DocumentSchema,
+  Infix extends string,
+> = BaseMultiSearchRequestSchema &
+  Omit<SearchParamsWithPreset<T, Infix>, "streamConfig">;
+
+export type MultiSearchUnionParameters<
+  T extends DocumentSchema,
+  Infix extends string,
+> = CommonMultiSearchParametersBase<T, Infix> & {
+  streamConfig?: MultiSearchUnionStreamConfig<T>;
+  use_cache?: boolean;
+};
+
+export type MultiSearchResultsParameters<
+  T extends DocumentSchema[],
+  Infix extends string,
+> = CommonMultiSearchParametersBase<T[number], Infix> & {
+  streamConfig?: MultiSearchResultsStreamConfig<T>;
+  use_cache?: boolean;
+};
+
+type Whitespace = " " | "\n" | "\t";
+
+type TrimString<S extends string> = S extends `${Whitespace}${infer S}`
+  ? TrimString<S>
+  : S extends `${infer S}${Whitespace}`
+    ? TrimString<S>
+    : S;

package/src/Typesense/Utils.ts

@@ -0,0 +1,80 @@
+import { DocumentSchema } from "./Documents";
+import { arrayableParams } from "./Types";
+import type { UnionArrayKeys, ExtractBaseTypes, SearchParams } from "./Types";
+
+function hasNoArrayValues<
+  TDoc extends DocumentSchema,
+  T extends SearchParams<TDoc, Infix>,
+  const Infix extends string,
+>(params: T | ExtractBaseTypes<T>): params is ExtractBaseTypes<T> {
+  return Object.keys(arrayableParams)
+    .filter((key) => params[key] !== undefined)
+    .every((key) => isNonArrayValue(params[key]));
+}
+
+export function normalizeArrayableParams<
+  TDoc extends DocumentSchema,
+  T extends SearchParams<TDoc, Infix>,
+  const Infix extends string,
+>(params: T): Prettify<ExtractBaseTypes<T>> {
+  const result = { ...params };
+
+  const transformedValues = Object.keys(arrayableParams)
+    .filter((key) => Array.isArray(result[key]))
+    .map((key) => {
+      result[key] = result[key].join(",");
+      return key;
+    });
+
+  if (!transformedValues.length && hasNoArrayValues<TDoc, T, Infix>(result)) {
+    return result;
+  }
+
+  if (!hasNoArrayValues<TDoc, T, Infix>(result)) {
+    throw new Error(
+      `Failed to normalize arrayable params: ${JSON.stringify(result)}`,
+    );
+  }
+
+  return result;
+}
+
+function isNonArrayValue<
+  TDoc extends DocumentSchema,
+  T extends SearchParams<TDoc, Infix>,
+  const Infix extends string,
+  K extends UnionArrayKeys<T>,
+>(value: T[K] | ExtractBaseTypes<T>[K]): value is ExtractBaseTypes<T>[K] {
+  return !Array.isArray(value);
+}
+
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+} & {};
+
+interface ErrorWithMessage extends Error {
+  message: string;
+}
+
+function isErrorWithMessage(error: unknown): error is ErrorWithMessage {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof (error as Record<string, unknown>).message === "string"
+  );
+}
+
+export function toErrorWithMessage(couldBeError: unknown): ErrorWithMessage {
+  if (isErrorWithMessage(couldBeError)) return couldBeError;
+
+  try {
+    if (typeof couldBeError === "string") {
+      return new Error(couldBeError);
+    }
+    return new Error(JSON.stringify(couldBeError));
+  } catch {
+    return new Error(String(couldBeError));
+  }
+}

package/src/Typesense.ts

@@ -0,0 +1,43 @@
+import Client from "./Typesense/Client";
+import SearchClient from "./Typesense/SearchClient";
+import * as Errors from "./Typesense/Errors";
+
+export { Client, SearchClient, Errors };
+export default { Client, SearchClient, Errors };
+
+export type * from "./Typesense/Aliases";
+export type * from "./Typesense/AnalyticsRulesV1";
+export type * from "./Typesense/AnalyticsRuleV1";
+export type * from "./Typesense/AnalyticsEvent";
+export type * from "./Typesense/AnalyticsRule";
+export type * from "./Typesense/AnalyticsRules";
+export type * from "./Typesense/Collection";
+export type * from "./Typesense/Collections";
+export type * from "./Typesense/Configuration";
+export type * from "./Typesense/Conversations";
+export type * from "./Typesense/Conversation";
+export type * from "./Typesense/ConversationModel";
+export type * from "./Typesense/Debug";
+export type * from "./Typesense/Documents";
+export type * from "./Typesense/Health";
+export type * from "./Typesense/Key";
+export type * from "./Typesense/Keys";
+export type * from "./Typesense/Metrics";
+export type * from "./Typesense/MultiSearch";
+export type * from "./Typesense/Override";
+export type * from "./Typesense/Overrides";
+export type * from "./Typesense/Preset";
+export type * from "./Typesense/Presets";
+export type * from "./Typesense/Stats";
+export type * from "./Typesense/Stopword";
+export type * from "./Typesense/Stopwords";
+export type * from "./Typesense/Synonym";
+export type * from "./Typesense/Synonyms";
+export type * from "./Typesense/SynonymSet";
+export type * from "./Typesense/SynonymSets";
+export type * from "./Typesense/SynonymSetItem";
+export type * from "./Typesense/SynonymSetItems";
+export type * from "./Typesense/CurationSet";
+export type * from "./Typesense/CurationSets";
+export type * from "./Typesense/CurationSetItem";
+export type * from "./Typesense/CurationSetItems";