@nice-digital/search-client

Client for using NICE search in Node and browsers

• @nice-digital/search-client
  • Stack
  • Local development
    • Install Node
    • Build TypeScript
    • Watch mode
    • Linking
    • Tests
  • Usage
    • Install Node
    • Install TypeScript 4.5+
    • Install search client
    • Import and initialise
    • Main search methods
    • TypeScript
    • Browser usage
    • Error handling

Stack

• TypeScript for static type checking
• qs for querystring parsing and serialization
• Axios as a HTTP client for network requests
  • with axios-case-converter for lower-casing JSON response property names
• Jest for unit tests
  • with ts-jest for TypeScript transpilation
  • and axios-mock-adapter.

Local development

Install Node

Use the version of Node that's pinned for Volta in package.json (see volta.node). The easiest way is using Volta, a JavaScript tool manager: cd into the cloned repo and Volta will automatically use the correct version of Node. If you're not using Volta then download and install the correct Node LTS version.

Build TypeScript

Run npm run ts to compile the TypeScript src files into the lib, es and types folders - these are what project import when the package is installed from npm.

Watch mode

Run npm run ts:es:watch to compile the TypeScript src files into the es folder in watch mode. This watches for changes and recompiles on save. This is useful for both real time type-checking and linking into a search project for real-world testing:

Linking

Linking search client into an actual project is great for development. It allows testing of integration with a real project, rather than just running unit tests.

First run npm link in this repository. Then, in your project that's consuming the search client (e.g. Next-Web), run npm link @nice-digital/search-client. Under the hood this sets up a symlink to this repo. Once the projects are linked, run npm run ts:es:watch as above to watch for changes.

Tests

Run npm test to run Jest tests. Or run npm run test:coverage to generate coverage into the coverage folder. Or run npm run test:watch to run tests and watch for changes.

Usage

Install Node

Install Node 14+ LTS in your project that's going to consume the search client.

Install TypeScript 4.5+

If you're using TypeScript, make sure it's version 4.5 or above.

Version 2 of @nice-digital/search-client uses import { type SomeName } from ... style imports (part of TypeScript 4.5), which requires the consuming project to also be using TypeScript 4.5+.

Version 1 had regular import type { SomeName } from ... style imports so works with TypeScript <4.5.

Install search client

Install the @nice-digital/search-client from npm:

npm i @nice-digital/search-client -s

Note the -s switch which installs the package as a dependency rather than a dev dependency.

Import and initialise

Import initialise:

import { initialise, search } from "@nice-digital/search-client";

Then call initialise with the Single Search API base URL and the index. For example to use the local search endpoint and the nice index:

import { initialise } from "@nice-digital/search-client";

// Note: you need to `initialise` before you can `search`
initialise({ baseURL: "https://localhost:44328/api", index: "nice" });

Find the dev, test, alpha, beta and live Single Search Endpoint base url from ops.

Main search methods

Now that the search client is initialised with a baseURL and index, you can call methods to retrieve data from ElasticSearch via the Single Search Endpoint. Import and call one of search, download, typeAhead or getDocument (see the example below).

Note: the main search methods each return a Promise that resolves with the data returned from the Single Search Endpoint. This means you'll need to await the methods inside an async function (or use then e.g. search("/search?q=test").then((data) => { /* do something with data */ })). Note: it has to be inside an async function becase Top-Level Await is still a draft proposal.

As an example, with NextJS you'd call search from within getServerSideProps:

import { initialise, search } from "@nice-digital/search-client";

export async function getServerSideProps(context) {
    initialise({ baseURL: "https://localhost:44328/api", index: "nice" });
    
    const searchResults = await search(context.resolvedUrl);

    return {
        props: {
            searchResults
        },
    }
}

TypeScript

The @nice-digital/search-client package is written in TypeScript and ships with TypeScript definitions. This means you can import the type defs for advanced use-cases:

import { SearchResults, Document } from "@nice-digital/search-client";

Browser usage

The @nice-digital/search-client package:

• uses axios under the hood, with supports both the browser and node.js
• and is transpiled to ES5 before publishing to npm.

These 2 things mean the library will work both server-side (e.g. via getServerSideProps in NextJS) or on the client for direct Single Search Endpoint communication. It will also work with webpack (or other bundlers) without extra config because it's published as ES5.

Finally, we also publish both:

• a CommonJS module output to the lib folder (referenced via main in package.json)
• an ES6 module output to the es folder (referenced via module in package.json).

Webpack supports the module property (see this guide), which will load the ES6 modules, which in turn supports tree-shaking which in turn results in smaller bundles including only code that is actually used.

Error handling

The @nice-digital/search-client package handles any errors e.g. network problems, server errrors or timeouts. This means methods like search shouldn't throw, instead they'll return an object like:

{
    "errorMessage": "Error: timeout of 3000ms exceeded",
    "failed": true,
}

There are unit tests for error states.