### Install Dependencies and Start Server with npm

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/test/support/testground/README.md

Use these commands to install project dependencies and start the local development server using npm.

```sh
npm install
npm start
```

--------------------------------

### Install Dependencies and Start Server with Yarn

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/test/support/testground/README.md

Use these commands to install project dependencies and start the local development server using Yarn.

```sh
yarn
yarn start
```

--------------------------------

### Install Dependencies and Run Development Servers

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Install project dependencies, start the Typesense server for development, and index test data. This is typically used during the development phase.

```shell
$ npm install
$ npm run typesenseServer
$ FORCE_REINDEX=true npm run indexTestData
```

--------------------------------

### Install Typesense Instantsearch Adapter with npm

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Install the adapter using npm. The @babel/runtime package is also required.

```shell
$ npm install --save typesense-instantsearch-adapter @babel/runtime
```

--------------------------------

### Install Typesense Instantsearch Adapter with yarn

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Install the adapter using yarn. The @babel/runtime package is also required.

```shell
$ yarn add typesense-instantsearch-adapter @babel/runtime
```

--------------------------------

### InstantSearch.js Integration with Typesense

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Configure and use the Typesense InstantSearch adapter with InstantSearch.js. Ensure your API key has search-only permissions and specify your Typesense node details. This example demonstrates basic search box and hits widget setup.

```javascript
import instantsearch from "instantsearch.js";
import { searchBox, hits } from "instantsearch.js/es/widgets";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

const search = instantsearch({
  searchClient,
  indexName: "products",
});
search.addWidgets([
  searchBox({
    container: "#searchbox",
  }),
  hits({
    container: "#hits",
    templates: {
      item: "
        <div class=\"hit-name\">
          {{#helpers.highlight}}{ \"attribute\": \"name\" }}{{\/helpers.highlight}}
        </div>
      ",
    },
  }),
]);

search.start();

```

--------------------------------

### Install np for Releasing

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Install the 'np' package globally, which is used for managing and publishing new releases of the npm package. This is a prerequisite for the release process.

```shell
$ npm install --global np
```

--------------------------------

### Angular InstantSearch Setup with Typesense

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Configure the Typesense InstantSearch adapter for an Angular application. Ensure your API key only allows search operations and adjust server node details as needed.

```javascript
// app.component.ts
import { Component } from "@angular/core";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
export class AppComponent {
  config = {
    indexName: "products",
    searchClient,
  };
}
```

--------------------------------

### Vue InstantSearch Setup with Typesense

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Configure the Typesense InstantSearch adapter for a Vue.js application. Ensure your API key only allows search operations and adjust server node details as needed.

```vue
<template>
  <ais-instant-search :search-client="searchClient" index-name="products">
    <ais-search-box />
    <ais-hits>
      <div slot="item" slot-scope="{ item }">
        <h2>{{ item.name }}</h2>
      </div>
    </ais-hits>
  </ais-instant-search>
</template>

<script>
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        port: "8108",
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

export default {
  data() {
    return {
      searchClient,
    };
  },
};
</script>
```

--------------------------------

### React InstantSearch Integration with Typesense

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Integrate the Typesense InstantSearch adapter with React InstantSearch. Similar to the JavaScript version, configure server details and API keys. This example shows the basic structure for a React application using InstantSearch components.

```jsx
import React from "react";
import ReactDOM from "react-dom";
import { SearchBox } from "react-instantsearch-dom";
import TypesenseInstantSearchAdapter from "typesense-instantsearch-adapter";

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "", // Optional. Example: If you have your typesense mounted in localhost:8108/typesense, path should be equal to '/typesense'
        protocol: "http",
      },
    ],
    cacheSearchResultsForSeconds: 2 * 60, // Cache search results from server. Defaults to 2 minutes. Set to 0 to disable caching.
  },
  // The following parameters are directly passed to Typesense's search API endpoint.
  //  So you can pass any parameters supported by the search endpoint below.
  //  query_by is required.
  additionalSearchParameters: {
    query_by: "name,description,categories",
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

const App = () => (
  <InstantSearch indexName="products" searchClient={searchClient}>
    <SearchBox />
    <Hits />
  </InstantSearch>
);

```

--------------------------------

### Link and Test the Adapter

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Link the local typesense-instantsearch-adapter to your project and run the testground to verify its functionality. This is part of the local development workflow.

```shell
$ npm link typesense-instantsearch-adapter
$ npm run testground
```

--------------------------------

### Initialize Typesense Instantsearch Adapter

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Initializes the Typesense Instantsearch adapter with server configuration including API key and node details.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  additionalSearchParameters,
});
```

--------------------------------

### Include Typesense Instantsearch Adapter via Script Tag

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Include the adapter directly in your HTML using a script tag from a CDN. It's recommended to pin the version to avoid unexpected updates.

```html
<script src="https://cdn.jsdelivr.net/npm/typesense-instantsearch-adapter@2/dist/typesense-instantsearch-adapter.min.js"></script>

<!-- You might want to pin the version of the adapter used if you don't want to always receive the latest minor version -->
```

--------------------------------

### Run Unit Tests

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Execute the project's unit tests to ensure code quality and identify regressions. This is a standard step in the development and CI/CD process.

```shell
$ npm test
```

--------------------------------

### Release New Version with np

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Use the 'np' command to initiate the release process for a new version of the package. Follow the interactive prompts to complete the release.

```shell
$ np
```

--------------------------------

### Configure Non-Exact Filtering with filter_by Options

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Instantiate the adapter with `filterByOptions` to enable non-exact word-level filtering (e.g., `field:value`) instead of exact matching (`field:=value`). This is useful for fields like 'brand' or 'category'.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  filterByOptions: {
    brand: { exactMatch: false }, // <========== Add this to do non-exact word-level filtering
    category: { exactMatch: false },
  },
  collectionSpecificFilterByOptions: {
    collection1: {
      brand: { exactMatch: false },
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override filterByOptions for that particular collection.
  additionalSearchParameters,
});
```

--------------------------------

### Configure Instantsearch for Vector Search

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Sets up Instantsearch to perform semantic or hybrid search by utilizing the 'typesenseVectorQuery' parameter. This is useful for nearest neighbor vector searches.

```javascript
const searchClient = typesenseInstantsearchAdapter.searchClient;
search = instantsearch({
  searchClient,
  indexName: INDEX_NAME,
  routing: true,
  async searchFunction(helper) {
    // This fetches 200 (nearest neighbor) results for semantic / hybrid search

    let query = helper.getQuery().query;
    const page = helper.getPage(); // Retrieve the current page

    if (query !== "" && ["semantic", "hybrid"].includes($("#search-type-select").val())) {
      console.log(helper.getQuery().query);
      helper
        .setQueryParameter(
          "typesenseVectorQuery", // <=== Special parameter that only works in typesense-instantsearch-adapter@2.7.0-3 and above
          `embedding:([], k:200)`,
        )
        .setPage(page)
        .search();
      console.log(helper.getQuery().query);
    } else {
      helper.setQueryParameter("typesenseVectorQuery", null).setPage(page).search();
    }
  },
});
```

--------------------------------

### Configure Custom Facet By Options

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Use `facetByOptions` to pass custom parameters like server-side sorting to the `facet_by` parameter. Available from typesense-instantsearch-adapter 2.8.0-1.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  facetByOptions: {
    brand: "(sort_by: _alpha:asc)",
    category: "(sort_by: _alpha:desc)",
  }, // <======= Add any facet_by parameter as a key value pair. Don't forget the surrounding parentheses in the value.
  collectionSpecificFacetByOptions: {
    collection1: {
      brand: "(sort_by: _alpha:desc)",
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override facetByOptions for that particular collection.
  additionalSearchParameters,
});
```

--------------------------------

### SortBy Widget Configuration

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Configure the `sortBy` widget for InstantSearch with Typesense. The `value` attribute follows the pattern `<index_name>[/sort/<sort_by>]` to specify sorting parameters.

```javascript
search.addWidgets([
  sortBy({
    container: "#sort-by",
    items: [
      { label: "Default", value: "products" },
      { label: "Price (asc)", value: "products/sort/price:asc" },
      { label: "Price (desc)", value: "products/sort/price:desc" },
    ],
  }),
]);
```

--------------------------------

### Configure Dynamic Widgets with Facet Ordering

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Use `renderingContent` to control the order of facets displayed by `dynamicWidgets`. This requires Typesense Server v0.25.0.rc12 or later.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  renderingContent: {
    // <<===== Add this, only if you want to control the order of the widgets displayed by dynamicWidgets
    facetOrdering: {
      facets: {
        order: ["size", "brand"], // <<===== Change this as needed
      },
    },
  },
  additionalSearchParameters,
});
```

--------------------------------

### Configure Multi-Index Search Parameters

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Set common search parameters and override them per collection for multi-index search. Ensure your API key only allows search operations.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd", // Be sure to use an API key that only allows search operations
    nodes: [{ host: "localhost", path: "/", port: "8108", protocol: "http" }],
  },
  // Search parameters that are common to all collections/indices go here:
  additionalSearchParameters: {
    numTypos: 3,
  },
  // Search parameters that need to be *overridden* on a per-collection-basis go here:
  collectionSpecificSearchParameters: {
    products: {
      query_by: "name,description,categories",
    },
    brands: {
      query_by: "name",
    },
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;
```

--------------------------------

### Enable Server-Side Caching

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Enables server-side caching by setting 'useServerSideSearchCache: true' in the adapter's server configuration. This adds '?use_cache=true' to search requests.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "...",
    nearestNode: {...},
    nodes: [...],
    useServerSideSearchCache: true // <<< Add this to send use_cache as a query parameter instead of post body parameter
  },
  additionalSearchParameters: {...}
});
```

--------------------------------

### Configure Client-Side Cache TTL

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Configures the Time-To-Live (TTL) for the adapter's client-side caching. This prevents unnecessary network calls by setting a duration in seconds.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "...",
    nearestNode: {...},
    nodes: [...],
    cacheSearchResultsForSeconds: 2 * 60 // <<< Add this to configure the TTL for client-side cache in the browser
  },
  additionalSearchParameters: {...}
});
```

--------------------------------

### Enable Union Search

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Enable union search to merge results from multiple search queries into a single ordered set. This requires typesense-instantsearch-adapter v2.10.0+ and Typesense Server v28.0+.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  union: true, // <======= Enable union search
  collectionSpecificSearchParameters: {
    products: {
      query_by: "name,description,categories",
    },
    brands: {
      query_by: "name",
    },
  },
});
```

--------------------------------

### Configure Geo-location Field

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Specify a custom field name for geo-location data if it's not the default '_geoloc'. This allows InstantSearch to correctly access latitude and longitude values.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  geoLocationField: "lat_lng_field", // <<======
  additionalSearchParameters,
});
```

--------------------------------

### Preserve Grouped Hits

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Set `flattenGroupedHits: false` to prevent the adapter from flattening results across all groups into a single list. This preserves group structure, placing the primary hit and grouped hits in a `_grouped_hits` key.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  flattenGroupedHits: false, // <=======
  additionalSearchParameters,
});
```

--------------------------------

### Handle Special Characters in Facetable Field Values

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Specify fields with colons in their values using `facetableFieldsWithSpecialCharacters` to aid parsing. Available from typesense-instantsearch-adapter 2.7.0-2.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  facetableFieldsWithSpecialCharacters: ["brand"], // <======= Add string fields that have colons in their values here, to aid in parsing
  additionalSearchParameters,
});
```

--------------------------------

### Disable Overrides for Specific Sort Orders

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Configure `sortByOptions` to disable curation rules or overrides when a specific Typesense `sort_by` string is generated by the sortBy widget. Use `collectionSpecificSortByOptions` for collection-specific configurations.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  sortByOptions: {
    "field1:desc,field2:desc": { enable_overrides: false }, // <========== Add this to disable sorting when this particular Typesense `sort_by` string is generated by the sortBy widget
  },
  collectionSpecificSortByOptions: {
    collection2: {
      "field1:desc,field2:desc": { enable_overrides: false },
    },
  }, // <======= Use this parameter if multiple collections share the same field names, and you want to use different options for each field. This will override sortByOptions for that particular collection.
  additionalSearchParameters,
});
```

--------------------------------

### Flip Negative Refinement Operator

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Set `flipNegativeRefinementOperator: true` to change how negative refinements are encoded. By default, excluded values use `field:![a,b]`, but with this option, they are expanded for OR behavior like `(field:!a || field:!b)`.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  flipNegativeRefinementOperator: true,
  additionalSearchParameters,
});
```

--------------------------------

### Handle Special Characters in Numeric Facet Field Names

Source: https://github.com/typesense/typesense-instantsearch-adapter/blob/master/README.md

Specify numeric field names with special characters like '>', '<', or '=' using `facetableFieldsWithSpecialCharacters` to aid parsing. Available from typesense-instantsearch-adapter 2.7.0-2.

```javascript
const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [
      {
        host: "localhost",
        port: "8108",
        path: "/",
        protocol: "http",
      },
    ],
  },
  facetableFieldsWithSpecialCharacters: ["price>discount"], // // <======= Add numeric fields that have >, < or = in their names, to aid in parsing
  additionalSearchParameters,
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.