@bothive/helpers
Version:
Collection of helper functions mainly used inside bothive-core project
282 lines (209 loc) • 6.17 kB
Markdown
<p align="center">
<img src="https://storage.googleapis.com/bothive_assets_8a0s1s3e/branding/logo.svg" alt="logo" width="333px" >
</p>
# Overview
Bundle of [TypeScript](https://www.typescriptlang.org/) helper functions created for internal use by the [Bothive](https://www.bothive.be/company/about) team.
#### Helpers:
- `arrayHelpers`
- `dateHelpers`
- `errorHelpers`
- `generatorHelpers`
- `stringHelpers`
- `timeoutHelpers`
- `loggingHelpers`
- `elasticAliasHelper`
---
## Getting Started
Install:
```bash
npm i -E @bothive/helpers
```
Example:
```js
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](https://github.com/sindresorhus/np)
```bash
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.
```bash
npm run test
```
Check the coverage of all the tests.
```bash
npm run coverage
```
Run tests continuously until one fails.
```bash
npm run test:run
```
## Helpers explanation
<details>
<summary>ElasticAliasHelper</summary>
### 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:
```js
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
```JSON
"axios": "0.27.2"
```
#### Functions
##### getInstance
```js
/**
* 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
```js
/**
* 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
```js
/**
* 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
```js
/**
* Searches documents by a document Id
* @param {[string]} id Document Id
*/
// Params:
{ id: string }
```
##### countByQuery
```js
/**
* Counts documents by a query
* @param {[any]} query
*/
// Params:
{ query: any }
```
##### searchByQuery
```js
/**
* 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
```js
/**
* 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
```js
/**
* 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
```js
/**
* Deletes documents by a query
* @param {[any]} query
*/
// Params:
{ query: any }
```
##### insertBulk
```js
/**
* Executes the _bulk route
* @param {[string]} bulkPayload NdJson formatted string
*/
// Params:
{ bulkPayload: string }
```
##### create
```js
/**
* 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 }
```
</details>