@andreafspeziale/nestjs-search NPM

Installation

npm

npm install @andreafspeziale/nestjs-search

yarn

yarn add @andreafspeziale/nestjs-search

pnpm

pnpm add @andreafspeziale/nestjs-search

Peer Dependencies

@nestjs/common and reflect-metadata are required peer dependencies which I'm pretty sure 99% of NestJS applications out there have already installed.

I managed to setup @aws-sdk/credential-providers as optional using dynamic imports and throwing an error if you try to use the ServiceAccount connection method without installing it.

In addition to the module and the injectable client you can import and use the following features as soon as you add the related peer dependency:

exporting an OSHealthIndicator for your server which requires @nestjs/terminus
environment variables parsers/validators (eventually using and requiring zod)

Check the next chapters for more info of the above mentioned features.

Required

@nestjs/common
reflect-metadata

Optional

@aws-sdk/credential-providers
@nestjs/terminus
zod

How to use?

Module

The module is Global by default.

OSModule.forRoot(options)

src/core/core.module.ts

import { Module } from '@nestjs/common';
import {
  ConnectionMethod,
  OSModule,
  OS_HOST,
} from '@andreafspeziale/nestjs-search';

@Module({
  imports: [
    OSModule.forRoot({
      host: OS_HOST,
      connectionMethod: ConnectionMethod.Local,
    }),
  ],
  ....
})
export class CoreModule {}

OSModule.forRootAsync(options)

src/core/core.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { OSModule } from '@andreafspeziale/nestjs-search';
import { Config } from './config';

@Module({
  imports: [
    ConfigModule.forRoot({
      ....
    }),
    OSModule.forRootAsync({
      useFactory: (cs: ConfigService<Config, true>) => cs.get<Config['os']>('os'),
      inject: [ConfigService],
    }),
  ],
  ....
})
export class CoreModule {}

Based on your connection needs a config object must be provided:

export interface OSConfig<
  T extends Local | Proxy | ServiceAccount | Credentials =
    | Local
    | Proxy
    | ServiceAccount
    | Credentials,
> {
  os: OSModuleOptions<T>;
}

You can customize your consumer needs leveraging generics:

src/config/config.interfaces.ts

import {
  Local,
  OSConfig,
  ServiceAccount,
} from '@andreafspeziale/nestjs-search';

....
// Your config supporting only "Local" and "ServiceAccount" connection methods
export type Config = OSConfig<Local | ServiceAccount> & ....;

Decorators

use the client and create your own service

InjectOSModuleOptions() and InjectOS()

src/samples/samples.service.ts

import { Injectable } from '@nestjs/common';
import { InjectOS, InjectOSModuleOptions, OSModuleOptions, OSTypes } from '@andreafspeziale/nestjs-search';

@Injectable()
export class SamplesService {
  constructor(
    @InjectOSModuleOptions() private readonly osModuleOptions: OSModuleOptions, // Showcase purposes
    @InjectOS() private readonly osClient: OSTypes.Client
  ) {}

  ....
}

Health

NestJS 11 slightly changed custom heath indicators. OSHealthIndicator and OldOSHealthIndicator are at your disposal

I usually expose an /healthz controller from my microservices in order to check third parties connection.

nestjs-search exposes from a separate path an health indicator which expects @nestjs/terminus to be installed in your project.

HealthModule

src/health/health.module.ts

import { OSHealthIndicator } from '@andreafspeziale/nestjs-search/dist/health';
import { Module } from '@nestjs/common';
import { TerminusModule } from '@nestjs/terminus';
import { HealthController } from './health.controller';

@Module({
  imports: [TerminusModule],
  controllers: [HealthController],
  providers: [OSHealthIndicator],
})
export class HealthModule {}

HealthController

src/health/health.controller.ts

import { Controller, Get } from '@nestjs/common';
import { OSHealthIndicator } from '@andreafspeziale/nestjs-search/dist/health';
import {
  HealthCheckService,
  HealthCheckResult,
} from '@nestjs/terminus';

@Controller('healthz')
export class HealthController {
  constructor(
    private readonly health: HealthCheckService,
    private openSearchHealthIndicator: OSHealthIndicator,
  ) {}

  @Get()
  check(): Promise<HealthCheckResult> {
    return this.health.check([
      () => this.openSearchHealthIndicator.isHealthy('opensearch'),
    ]);
  }
}

Environment variables management

As mentioned above I usually init my NestJS DynamicModules injecting the ConfigService exposed by the ConfigModule (@nestjs/config package). This is where I parse my environment variables using a library of my choice (I've been mostly experimenting with joi, class-transformer/class-validator and zod).

You can still implement your favorite parsing/validation flow but it's worth to mention that nestjs-search exposes some related and convenient features from distinct paths in order to avoid to force you install packages you'll never going to use.

So let's pretend you are goingo to parse your environment variables using the nestjs-search zod related features, I expect zod to be already installed in you project.