ES Kit is a "pick and mix" library that simplifies writing Elasticsearch code
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.
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.
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
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": []
}
]
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 parameters passing query, script, and sort options to the native client as you would normally:
const res = client.updateByQuery({ index: 'contacts', query, script, sort })Then paginate, extract or build docs without writing lots of call-specific code:
return $.paginate(res, options)Install via NPM:
npm i @davestewart/es-kit
Then, start writing code:
If you're new to Elastic, get up to speed:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent