Este guia detalha como utilizar o Typesense InstantSearch Adapter para desenvolver interfaces de busca ricas e dinâmicas, combinando o poder do servidor de busca Typesense com a flexibilidade da biblioteca InstantSearch.js. O adaptador facilita a integração, permitindo que desenvolvedores criem experiências de busca eficientes em aplicações web.

Início Rápido com Node.js

Para começar, certifique-se de que o Node.js e o npm (ou yarn) estejam instalados em seu ambiente de desenvolvimento.

Instalação das Dependências

Utilize o npm para instalar o Typesense InstantSearch Adapter, o runtime do Babel e o InstantSearch.js:

npm install --save typesense-instantsearch-adapter @babel/runtime
npm install --save instantsearch.js

Alternativamente, se preferir o yarn:

yarn add typesense-instantsearch-adapter @babel/runtime
yarn add instantsearch.js

Configurando a Instância de Busca

No seu arquivo JavaScript, configure o adaptador Typesense com as informações do seu servidor e inicialize a instância do InstantSearch.js:

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

// Objeto de configuração para o adaptador Typesense
const configuracaoTypesense = {
  server: {
    apiKey: 'SUA_CHAVE_API_TYPESENSE', // Substitua pela sua chave de API Typesense
    nodes: [
      {
        host: 'localhost',
        port: '8108',
        protocol: 'http',
      },
    ],
    // Habilita o cache de resultados por 120 segundos para melhorar a performance
    cacheSearchResultsForSeconds: 120,
  },
  // Parâmetros de busca adicionais enviados ao Typesense
  additionalSearchParameters: {
    query_by: 'nome,descricao,categorias', // Define os campos nos quais a busca será realizada
  },
};

const adaptadorDeBusca = new TypesenseInstantSearchAdapter(configuracaoTypesense);
const clienteDeBusca = adaptadorDeBusca.searchClient;

// Inicializa a instância do InstantSearch.js
const instanciaBusca = instantsearch({
  searchClient: clienteDeBusca,
  indexName: 'produtos', // Nome do índice configurado no seu servidor Typesense
});

// Adiciona os widgets de interface de busca
instanciaBusca.addWidgets([
  searchBox({ container: '#caixa-busca' }), // Widget de caixa de texto para entrada de busca
  hits({
    container: '#resultados-busca', // Contêiner para exibir os resultados da busca
    templates: {
      item: `
        <div class="item-produto">
          <h3>{{#helpers.highlight}}{ "attribute": "nome" }{{/helpers.highlight}}</h3>
          <p>{{#helpers.highlight}}{ "attribute": "descricao" }{{/helpers.highlight}}</p>
        </div>
      `,
    },
  }),
]);

// Inicia o processo de busca, renderizando os widgets
instanciaBusca.start();

Certifique-se de que seu arquivo HTML contenha os elementos correspondentes aos contêineres dos widgets, conforme o exemplo abaixo:

<input id="caixa-busca" type="search" placeholder="Pesquisar produtos..." />
<div id="resultados-busca"></div>

Integração com Frameworks

Utilizando React

Para projetos React, a biblioteca react-instantsearch-dom simplifica a construção de componentes de busca. Primeiro, instale a biblioteca:

npm install --save react-instantsearch-dom

Em seguida, use o adaptador em seu componente React para configurar a busca:

import React from 'react';
import ReactDOM from 'react-dom';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch-dom';
import TypesenseInstantSearchAdapter from 'typesense-instantsearch-adapter';

// Reutiliza uma configuração similar para o Typesense
const configuracaoTypesenseParaReact = {
  server: {
    apiKey: 'SUA_CHAVE_API_TYPESENSE', // Sua chave de API Typesense
    nodes: [
      {
        host: 'localhost',
        port: '8108',
        protocol: 'http',
      },
    ],
  },
  additionalSearchParameters: {
    query_by: 'nome,descricao', // Campos de busca para este contexto
  },
};

const adaptadorReact = new TypesenseInstantSearchAdapter(configuracaoTypesenseParaReact);

const ComponenteDeBusca = () => (
  <InstantSearch
    indexName="produtos" // Nome do índice Typesense
    searchClient={adaptadorReact.searchClient}
  >
    <SearchBox placeholder="Buscar itens..." /> {/* Componente de caixa de busca */}
    <Hits /> {/* Componente para exibir os resultados */}
  </InstantSearch>
);

ReactDOM.render(<ComponenteDeBusca />, document.getElementById('root'));

Otimização de Performance

O Typesense InstantSearch Adapter incorpora um mecanismo de cache para os resultados de busca. Para ativá-lo, defina a propriedade cacheSearchResultsForSeconds na configuração do objeto server do Typesense, especificando a duração desejada do cache em segundos. Essa otimização pode significativamente reduzir a carga no servidor e acelerar a recuperação de resultados para requisições repetidas.

Ecossistema de Busca

O Typesense InstantSearch Adapter se integra perfeitamente a um ecossistema robusto de ferramentas e bibliotecas dedicdaas à construção de interfaces de busca:

• InstantSearch.js: Uma biblioteca de UI agnóstica a frameworks, projetada para construir experiências de busca dinâmicas e ricas.
• React InstantSearch: Um conjunto de componentes React que facilitam a integração da funcionalidade InstantSearch.js em aplicações React.
• Vue InstantSearch: Uma biblioteca similar que oferece componentes Vue para uma integração simplificada do InstantSearch.js.
• Angular InstantSearch: Componentes dedicados para desenvolvedores Angular que desejam integrar o InstantSearch.js em suas aplicações.