Overview

Bundle of TypeScript helper functions created for internal use by the Bothive team.

Helpers:

• arrayHelpers
• dateHelpers
• errorHelpers
• generatorHelpers
• stringHelpers
• timeoutHelpers
• loggingHelpers
• elasticAliasHelper

Getting Started

Install:

npm i -E @bothive/helpers

Example:

import { stringHelpers } from "@bothive/helpers";

stringHelpers.firstToUppercase("hello"); //"Hello"

Making Changes

When making changes follow these steps.

• Clone/fork repository
• npm ci
• Checkout development branch
• Make changes
• Test changes (see Package Testing below)
• Open pull request to master branch
• Wait for PR approval!
• Publish package with np

npm run release

Package Testing

We should always test the package locally without having to publish it to the registry first and produce unnecessary version bumps:

• Build the package locally with npm run build.
• Install it inside the target project with npm i /path/to/package

Unit Testing

The codebase can be unit tested with following commands. Run all tests.

npm run test

Check the coverage of all the tests.

npm run coverage

Run tests continuously until one fails.

npm run test:run

Helpers explanation

ElasticAliasHelper

Description

This helper exports a singleton helper class to interact with the Elastic REST API (https://www.elastic.co/guide/en/cloud/current/ec-restful-api.html). It's made specifically to use with aliases, not indices*. This way you can use the most important requests on alias level with this package. Just initiate an instance with the API Key and API configuration to interact with Elasticsearch.

* 
It's possible to interact with indices using the post and postNdJson functions. 
But all other functions are made to interact with aliases.

Example:

import { ElasticAliasHelper } from "@bothive/helpers";

const apiKey = "apiKey";
const apiConfig = {
		count: `<elasticsearch_host>/search-inbox-:env/_count`,
		search: `<elasticsearch_host>/search-inbox-:env/_search`,
		create: `<elasticsearch_host>/write-inbox-:env/_doc/:id`,
		update: (index: string) => `<elasticsearch_host>/${index}/_update/:id`,
		updateQuery: `<elasticsearch_host>/search-inbox-:env/_update_by_query`,
		deleteQuery: `<elasticsearch_host>/search-inbox-:env/_delete_by_query`,
		createBulk: `<elasticsearch_host>/_bulk`,
	}

const helper = ElasticAliasHelper.getInstance({
	apiKey,
	apiConfig
});

export default helper;

Dependencies

"axios": "0.27.2"

Functions

getInstance

/**
* Creates or returns a single instance of the ElasticAliasHelper class. (Singleton pattern)
* @param  {[string]} apiKey Elasticsearch API KEY
* @param  {[string]} apiConfig Configuration of the diffrent routes to the ElasticCloud API
*/

// Params: 
{ apiKey: string; apiConfig: any }

post

/**
* HTTP POST specific for the ElasticCloud API
* @param  {[string]} url URL for ElasticCloud
* @param  {[string]} apiKey Elasticsearch API KEY
* @param  {[any]} payload Object with the payload for the request
*/

// Params: 
{ url: string; apiKey: string; payload: any }

postNdJson

/**
* HTTP POST for NdJson formatted payload specific for the ElasticCloud API
* @param  {[string]} url URL for ElasticCloud
* @param  {[string]} apiKey Elasticsearch API KEY
* @param  {[string]} payload NdJson formatted string
*/

// Params: 
{ url: string; apiKey: string; payload: string }

searchDocumentById

/**
* Searches documents by a document Id
* @param  {[string]} id Document Id
*/

// Params: 
{ id: string }

countByQuery

/**
* Counts documents by a query
* @param  {[any]} query
*/

// Params: 
{ query: any }

searchByQuery

/**
* Searches documents by a query
* @param  {[any]} query Query to find documents
* @param  {[number]} size Defines the number of hits to return. Defaults to 10
* @param  {[number]} from Starting document offset. Needs to be non-negative and defaults to 0
* @param  {[any]} sort A comma-separated list of <field>:<direction> pairs
* @param  {[any]} aggs Aggregations to run
*/

// Params: 
{ query: any; size?: number; from?: number; sort?: any; aggs?: any }

updateDocumentWithUpsert

/**
* Updates a document or creates it if does not exists
* @param  {[string]} id Document Id
* @param  {[any]} payload Object with the payload for the request
* @param  {[string]} index Index where the document is stored
* @param  {[string]} routing Routing values ("?routing=" not included! function handles this logic)
*/

// Params: 
{ id: string; payload: any; index?: string; routing?: string }

updateByQuery

/**
* Updates documents by a query
* @param  {[any]} query
* @param  {[any]} script
* @param  {[boolean]} refresh Use the refresh API to explicitly make all operations
* performed on one or more indices since the last refresh available for search.
* If the request targets a data stream, it refreshes the stream’s backing indices (default false)
*/

// Params: 
{ query: any; script: any; refresh?: boolean }

deleteByQuery

/**
* Deletes documents by a query
* @param  {[any]} query
*/

// Params: 
{ query: any }

insertBulk

/**
* Executes the _bulk route
* @param  {[string]} bulkPayload NdJson formatted string
*/

// Params: 
{ bulkPayload: string }

create

/**
* Creates a document
* @param  {[string]} id Document Id
* @param  {[any]} payload Object with the payload for the request
* @param  {[string]} routing Routing values ("?routing=" not included! function handles this logic)
*/

// Params: 
{ id: string; payload: any; routing?: string }