@codemask-labs/nestjs-elasticsearch

v2.8.0

Published

a month ago

Schema based Elasticsearch, NestJS module with utilities, type-safe queries and aggregations builders.

Downloads

1,346

0High
0Medium
0Low

nestjs typescript typesafe nestjs-elasticsearch elasticsearch codemask

NestJS Elasticsearch Module

Welcome to Nestjs Elasticsearch module based on @nestjs/elasticsearch package.

The current version (2.x) is fully compatible with Elasticsearch 8. For projects using Elasticsearch 7, use the previous version (1.x).

Motive

This package originates from our experience with using Elasticsearch in production environments, which leaded to maintenance issues when extensively used aggregations, searches and filters (especially aggregations).

The main issues we encountered and which our package fixes are:

Current Elasticsearch NestJS Module does not provide autocompletion for queries.
Elasticsearch response forgets about types of aggregations.
Since Elasticsearch indexes can be schema-less we got no proper feedback about what fields we should expect on the index.
Writing utility methods for all filters and aggregations queries caused a lot of boilerplate code in each project.

Features

:rocket: Quick Setup - Get up and running in minutes using our easy-to-understand API.
:nerd_face: :computer: Developer Experience - Designed with developers in mind, package prioritizes ease of use and efficiency throughout the development process.
:white_check_mark: Full TypeScript Support - Enjoy the benefits of code autocompletion and types for both request and response objects. ⁤⁤Unlike the original Elasticsearch library, this package provides full type definitions in order to provide better development experience and minimize runtime errors. ⁤
:hammer_and_wrench: Utility Methods - Say goodbye to repetitive boilerplate code. The package offers set of utility methods for most common Elasticsearch filtering, sorting, pagination and aggregations use cases.
:bookmark_tabs: Schema definitions - Schema definitions are integrated into the package, with each schema mapping to an Elasticsearch index to provide a clear data model. These definitions are used to register indexes in the module scope and inject them into a service, similar to the approach in the TypeORM NestJS module, ensuring that only fields available for a given index are used when building request objects.

Installation

You can install package using yarn or npm:

$ yarn add @codemask-labs/nestjs-elasticsearch

$ npm i @codemask-labs/nestjs-elasticsearch

Getting started

Once the package is installed, you can start with importing the ElasticsearchModule into the AppModule.

import { ElasticsearchModule } from '@codemask-labs/nestjs-elasticsearch'

@Module({
    imports: [
        ElasticsearchModule.register({
            node: 'http://localhost:9200'
        })
    ]
})
class AppModule {}

The register() method supports all the configuration properties available in ClientOptions from the @elastic/elasticsearch package.

Registering the index

You can define index schema with @RegisterIndex() decorator.

import { RegisterIndex } from '@codemask-labs/nestjs-elasticsearch'

@RegisterIndex('examples')
export class ExampleDocument {
    readonly id: string
    readonly exampleField: string
    readonly exampleNumericField: number
}

Add index to a module

The ElasticsearchModule provides the forFeature() method to configure the module and define which indexes should be registered in the current scope.

import { ElasticsearchModule } from '@codemask-labs/nestjs-elasticsearch'
import { ExampleDocument } from './example.document'

@Module({
    imports: [ElasticsearchModule.forFeature([ExampleDocument])],
    providers: [ExampleService]
})
export class ExampleModule {}

Inject index in a service

With module configuration in place, we can inject the ExampleDocument into the ExampleService using the @InjectIndex() decorator:

import { Injectable } from '@nestjs/common'
import { Index } from '@codemask-labs/nestjs-elasticsearch'
import { ExampleDocument } from './example.document'

@Injectable()
export class ExampleService {
    @InjectIndex(ExampleDocument)
    private readonly exampleIndex: Index<ExampleDocument>

    getExampleDocuments() {
        return this.exampleIndex.search()
    }
}

Now you can start creating request to Elasticsearch.

Usage

Once you finish the Getting Started guide, you can start building Elasticsearch request objects.

You can put request object directly in the search() method

import { getBoolQuery, getTermQuery, Order } from '@codemask-labs/nestjs-elasticsearch'

getExampleDocuments() {
    return this.exampleIndex.search({
        size: 10,
        query: getBoolQuery({
            must: [
                getTermQuery('exampleField.keyword', 'Some value'),
                getRangeQuery('exampleNumericField', {
                    gte: 1,
                    lte: 10
                })
            ]
        }),
        sort: {
            'exampleField.keyword': {
                order: Order.ASC
            }
        }
    })
}

or use getSearchRequest() method if you want to move request creation to some other place, but still laverage full type support and autocompletion.

import { getBoolQuery, getTermQuery, getSearchRequest, Order } from '@codemask-labs/nestjs-elasticsearch'
import { ExampleDocument } from './example.document'

const searchRequestBody = getSearchRequest(ExampleDocument, {
    size: 10,
    query: getBoolQuery({
        must: [
            getTermQuery('exampleField.keyword', 'Some value'),
            getRangeQuery('exampleNumericField', {
                gte: 1,
                lte: 10
            })
        ]
    }),
    sort: {
        'exampleField.keyword': {
            order: Order.ASC
        }
    }
})

Queries

As for now the package provides utils for the following filter queries:

Aggregations

As for now the package provides utils for the following aggregation queries:

License

MIT