@davestewart/es-kit

ES Kit

ES Kit is a "pick and mix" library that simplifies writing Elasticsearch code

Abstract

Elasticsearch's JavaScript Client provides a powerful way to call Elasticsearch APIs but its inherent flexibility can be an issue:

• complex request and response formats can lead to verbose, duplicate or fragile application code
• if you're new to the API, documentation or terminology, it's difficult to know what code to write

To address this, ES Kit provides a constrained "kit of parts" in the form of reusable, atomic helper functions which fit together to reliably abstract the API lifecycle, making it quick, easy (and reasonably obvious how) to write clean, trial-and-error-free client code.

Who is this library for?

Whilst primarily aimed at simplifing Elasticsearch for new users, ES Kit aims to be useful for any user:

• New users: use the query functions and Api to get up and running quickly
• Improving users: use the docs, query functions and helpers to learn how Elasticsearch fits together
• Experienced users: customise the core helpers to build requests and parse responses in less overall code

New users: check the Elasticsearch 101 document for a valuable primer on how ES works differently to how you might expect and the Elasticsearch tips document on how to work with Elastic vs against it.

The kit

ES Kit comprises the following components:

Type	Purpose	Code example
Queries	Build Elastic queries using simple functions	_multiMatch('*', 'cat')
Helpers	Abstract key parts of the Elastic API lifecycle	$paginate(res)
Scripts	Build Elastic scripts from JavaScript functions	_removeFromArray('listIds', 24)
Api	Simplified interaction with Elasticsearch's APIs	Api.search('contacts', params)

Each of the helpers, functions or classes aims to be simple, atomic and transparent; rather than a complex or overly-abstracted monolithic framework, these small self-contained units let you go all-in on abstraction or pick and mix what suits your development style or project.

If a helper doesn't fit your use case:

• write that bit of code yourself, and quickly move on
• extend the Helpers with your new code and use it again

Code examples

Quick and easy

Use the query builder functions and Api class to handle configuration, loading, parsing, pagination and error handling in a single line:

return Api.search('contacts', _.should([
  _.prefix('name', 'ke')
  _.match('lists', 'sales'),
  _.multiMatch('*', 'san diego'),
]), { size: 20, from: 100 })

New users: check the Elastic tips document to understand which queries to use and when

Additionally, unlike Elasticsearch's APIs, ES Kit's Api returns simplified, consistent response data across all Search and Document API requests, making it super-easy to get started without spending time worrying if you're doing it right or reinventing the wheel:

[
  {
    "_id" : "ZRWBNH0Bk8QNffIJQWQp",
    "name" : "Kelly Hill",
    "notes": "Works in the San Diego area"
    "lists": [
    	"sales"
    ]
  },
  {
    "_id" : "lCloSH0Bs3kx_70FRmtW",
    "name" : "Kevin James",
    "office": "San Diego"
    "lists": []
  }
]

Fully customised

ES Kit is designed to be used as a kit of parts; there are helper functions to handle each stage of the request / response lifecycle.

You can create scripts on the fly or pick from ES Kit's library (making Painless relatively pain-free!):

const script = $.script(function (ctx, params) { ... }, { lists: 'sales' })

You can build request options passing query, script, and sort options to the native client as you would normally:

const res = client.updateByQuery({ index: 'contacts', query, script, sort })

Or parse response data without writing lots of call-specific code:

return $.paginate(res, options)

Next steps

Install via NPM:

npm i @davestewart/es-kit

Then, start writing code:

• ES Kit Documentation

If you're new to Elastic, get up to speed:

• Elastic Reference