typesense-js Documentation

Typesense provides several ecosystem integrations:

• GatsbyJS: Use gatsby-plugin-typesense to automatically push site data to Typesense during builds.
• Firebase: Use the Firestore Typesense Search extension to automatically sync Firestore data to Typesense.
• UI Components: For building search interfaces, use Typesense-InstantSearch.js, which provides ready-to-use UI components built on top of typesense-js.

For direct browser usage without a build step, you can include the minified JS file using a <script> tag. You can host it locally from your dist folder or use jsDelivr.

Local file:

<script src="dist/typesense.min.js"></script>

jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/typesense@3/dist/typesense.min.js"></script>

To use the Typesense client in a Node.js or server-side environment, install the typesense package. It is also recommended to install @babel/runtime as a direct peer dependency to avoid duplicate instances in your bundle.

npm install --save typesense
npm install --save @babel/runtime

The library separates concerns into two main client types:

• Client: Used for management operations such as creating/deleting collections, managing documents, configuring synonyms, curation sets, and analytics rules.
• SearchClient: Optimized for performing search queries and multi-search operations.

When working with streaming responses (e.g., for AI-generated content or large datasets), you can provide a StreamConfig to handle data chunks, errors, and completion events.

• onChunk: Triggered for every piece of data received.
• onError: Triggered if the stream encounters an error.
• onComplete: Triggered when the stream finishes successfully (includes the full SearchResponse).

interface MyStreamConfig extends StreamConfig<MyDocumentSchema> {
  onChunk?: (data: { conversation_id: string; message: string }) => void;
  onError?: (error: Error) => void;
  onComplete?: (data: SearchResponse<MyDocumentSchema>) => void;
}

Typesense supports multi-search requests, which can return results in two modes based on the union parameter:

1. Standard Multi-Search: Returns an object with a results array where each index corresponds to the input search request. The response shape is { results: { [Index in keyof T]: SearchResponse<T[Index]> } & { length: T['length'] } }.
2. Union Multi-Search: When union: true is used, the results are merged into a single response. The response shape is UnionSearchResponse<T>, which includes union_request_params to track individual request metadata.

Typesense supports performing multiple searches in a single request using the MultiSearch API. This is useful for reducing network overhead when querying different collections or using different parameters simultaneously.

There are two modes for MultiSearch:

1. Standard MultiSearch: Returns an object containing a results array, where each element corresponds to the search result of the respective request.
2. Union MultiSearch: When union: true is passed, it returns a UnionSearchResponse, which aggregates results into a single response structure.

Use MultiSearchRequestsSchema to define the array of searches to be executed.

Initialize a new Typesense.Client by providing connection details and an API key. You can also set a global connectionTimeoutSeconds to apply a timeout to all requests made by that client instance.

Security Note: When using the client in a browser, never use your master API key. Instead, use an API key that is restricted to search-only operations.

const client = new Typesense.Client({
  nodes: [{ host: "localhost", port: "8108", protocol: "http" }],
  apiKey: "xyz",
  connectionTimeoutSeconds: 30, // 30 second timeout for all requests
});

You can control individual request lifecycles using the standard Web AbortController API. This allows you to cancel specific requests or implement per-request timeouts without affecting the global client configuration.

Note: The .import() operation does not support abort signals or timeout configurations.

// Search with 5-second timeout
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const results = await client.collections("books").documents().search(
  {
    q: "*",
    query_by: "title",
  },
  { abortSignal: controller.signal },
);

// Collections with 2-second timeout
const collectionsController = new AbortController();
setTimeout(() => collectionsController.abort(), 2000);

const collections = await client.collections().retrieve({
  abortSignal: collectionsController.signal,
});