@eqxjs/stub

A comprehensive framework stub and bootstrapping library for NestJS applications that integrates multiple EQXJS ecosystem modules and provides essential application infrastructure components.

Installation

npm install @eqxjs/stub

Description

This module serves as the main entry point for the EQXJS framework. It consolidates and re-exports various modules from the EQXJS ecosystem while providing additional framework-specific functionality including:

• Framework module integration and bootstrapping
• Application interceptors for HTTP and REST communications
• Graceful shutdown handling
• Health check utilities
• Domain service context management
• Validation schemas and decorators
• Utility services for framework operations

Re-exported EQXJS Modules

The stub integrates the following EQXJS ecosystem modules:

• @eqxjs/commander - Command handling and configuration management
• @eqxjs/decorator - Custom decorators for application enhancement
• @eqxjs/transporter-http - HTTP transport layer
• @eqxjs/logger - Comprehensive logging capabilities
• @eqxjs/pipes - Data transformation pipes
• @eqxjs/utils - Utility functions and services
• @eqxjs/exception - Exception handling framework
• @eqxjs/security - Security utilities and validation

Usage

Basic Framework Setup

import { Module } from '@nestjs/common';
import { FrameworkModule } from '@eqxjs/stub';

@Module({
  imports: [
    FrameworkModule.register({
      configPath: './config',
      zone: 'development'
    })
  ]
})
export class AppModule {}

Application Bootstrap with Framework

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { GracefulShutdownService } from '@eqxjs/stub';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // Get graceful shutdown service
  const gracefulShutdown = app.get(GracefulShutdownService);
  
  // Setup graceful shutdown
  gracefulShutdown.setup(app);
  
  await app.listen(3000);
  console.log('Application is running on: http://localhost:3000');
}

bootstrap();

Using Framework Decorators

import { Controller, Get } from '@nestjs/common';
import { EntryPoint, DisableConsumerLogging, ConsumerMasking, SetMessageMode } from '@eqxjs/stub';

@Controller('api')
export class ApiController {
  
  @EntryPoint('USER_SERVICE')
  @DisableConsumerLogging()
  @Get('users')
  getUsers() {
    return this.userService.findAll();
  }

  @EntryPoint('USER_CREATE')
  @ConsumerMasking(['password', 'ssn'])
  @SetMessageMode('sync')
  @Post('users')
  createUser(@Body() userData: CreateUserDto) {
    return this.userService.create(userData);
  }
}

Using Framework Interceptors

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { AppInterceptor, HttpInterceptor, RestInterceptor } from '@eqxjs/stub';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: AppInterceptor,
    },
    {
      provide: APP_INTERCEPTOR,
      useClass: HttpInterceptor,
    },
    {
      provide: APP_INTERCEPTOR,
      useClass: RestInterceptor,
    },
  ],
})
export class AppModule {}

API Reference

Classes

FrameworkModule

Main framework module that provides integrated configuration and bootstrapping capabilities.

Methods:

static register(options: FrameworkOptionDto): DynamicModule

Registers the framework module with the provided configuration options.

Parameters:

• options: FrameworkOptionDto - Configuration options for the framework
  • configPath: string - Path to configuration files directory
  • zone: string - Environment zone (development, staging, production)

Returns: DynamicModule - Configured dynamic module with all integrated services

Features:

• Loads YAML configuration based on zone
• Sets global targetDomain from configuration
• Integrates all EQXJS ecosystem modules
• Provides framework utilities and graceful shutdown services

Example:

@Module({
  imports: [
    FrameworkModule.register({
      configPath: './config',
      zone: process.env.NODE_ENV || 'development'
    })
  ]
})
export class AppModule {}

GracefulShutdownService

Service for handling graceful application shutdown.

Methods:

• setup(app: INestApplication) - Sets up graceful shutdown for the application
• shutdown() - Initiates graceful shutdown sequence

Example:

const gracefulShutdown = app.get(GracefulShutdownService);
gracefulShutdown.setup(app);

// Application will handle SIGTERM and SIGINT gracefully

FrameworkUtilService

Utility service providing framework-specific helper functions and operations.

Interceptors

AppInterceptor

Global application interceptor for request/response handling and logging.

HttpInterceptor

Interceptor specifically designed for HTTP client communications.

LegacyHttpInterceptor

Interceptor for handling legacy HTTP communications.

RestInterceptor

Interceptor for RESTful API request/response processing.

Decorators

@EntryPoint(serviceName: string)

Decorator to mark method as an entry point for service operations.

Parameters:

• serviceName: string - Name of the service or operation

Example:

@EntryPoint('USER_MANAGEMENT')
@Get('users')
getUsers() {
  // Method implementation
}

@DisableConsumerLogging()

Decorator to disable consumer logging for specific methods.

Example:

@DisableConsumerLogging()
@Get('sensitive-data')
getSensitiveData() {
  // Logging disabled for this endpoint
}

@ConsumerMasking(fields: string[])

Decorator to mask specific fields in consumer logs.

Parameters:

• fields: string[] - Array of field names to mask

Example:

@ConsumerMasking(['password', 'creditCard', 'ssn'])
@Post('users')
createUser(@Body() userData: CreateUserDto) {
  // Specified fields will be masked in logs
}

@SetMessageMode(mode: string)

Decorator to set message processing mode.

Parameters:

• mode: string - Message mode ('sync', 'async', etc.)

Example:

@SetMessageMode('async')
@Post('process')
processData(@Body() data: any) {
  // Method will be processed asynchronously
}

DTOs and Interfaces

FrameworkOptionDto

Configuration options for framework initialization.

interface FrameworkOptionDto {
  configPath: string;  // Path to configuration directory
  zone: string;        // Environment zone identifier
}

EntrypointOptionDto

Options for configuring entry point behavior.

ValidatorsSchemaDto

Schema definitions for data validation.

DomainServiceContext

Context management for domain services.

GracefulShutdownInterface

Interface defining graceful shutdown contract.

Utilities

Health Utilities

Health check utilities for application monitoring.

import { healthUtil } from '@eqxjs/stub';

// Check application health
const healthStatus = await healthUtil.checkHealth();

Database Utilities

Database connection and management utilities.

import { dbUtil } from '@eqxjs/stub';

// Database operations
const connection = await dbUtil.getConnection();

Validation

Joi Schema Validators

Pre-configured Joi validation schemas for common data types.

import { joiSchema } from '@eqxjs/stub';

// Use predefined schemas
const { error, value } = joiSchema.userSchema.validate(userData);

Configuration

The framework expects YAML configuration files in the specified configPath with the naming convention: {zone}.config.yaml

Example Configuration Structure

# development.config.yaml
app:
  name: "MyApplication"
  version: "1.0.0"
  component-name: "my-service"
  port: 3000

log:
  level: "debug"
  detail:
    level: "trace"
    enable-file-logging: true

security:
  enabled: true
  cors:
    enabled: true

database:
  host: "localhost"
  port: 5432
  name: "mydb"

Features

Integrated Ecosystem

• Seamless integration of all EQXJS modules
• Unified configuration management
• Consistent logging and monitoring across modules

Application Lifecycle Management

• Graceful startup and shutdown handling
• Health monitoring and status reporting
• Resource cleanup and connection management

Developer Experience

• Rich decorator support for method enhancement
• Comprehensive interceptor pipeline
• Type-safe configuration and validation

Enterprise Features

• Advanced logging with masking capabilities
• Security utilities and validation
• HTTP transport layer with retry logic
• Command pattern implementation
• Exception handling framework

Advanced Usage

Custom Interceptor Configuration

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { AppInterceptor } from '@eqxjs/stub';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useFactory: () => new AppInterceptor({
        enableLogging: true,
        logLevel: 'debug',
        includeHeaders: false
      }),
    },
  ],
})
export class CustomInterceptorModule {}

Domain Service Context

import { Injectable } from '@nestjs/common';
import { DomainServiceContext } from '@eqxjs/stub';

@Injectable()
export class MyDomainService {
  constructor(private context: DomainServiceContext) {}

  async processData(data: any) {
    // Use domain context for processing
    return this.context.execute('PROCESS_DATA', data);
  }
}

Graceful Shutdown with Custom Cleanup

import { Injectable, OnModuleDestroy } from '@nestjs/common';
import { GracefulShutdownService } from '@eqxjs/stub';

@Injectable()
export class MyService implements OnModuleDestroy {
  constructor(private gracefulShutdown: GracefulShutdownService) {
    // Register custom cleanup
    this.gracefulShutdown.addCleanupTask(async () => {
      // Custom cleanup logic
      await this.closeConnections();
    });
  }

  async onModuleDestroy() {
    // Module-specific cleanup
  }
}

Dependencies

This framework integrates multiple EQXJS modules and requires:

• All EQXJS ecosystem modules (commander, decorator, logger, etc.)
• @nestjs/common and @nestjs/core
• js-yaml for configuration parsing
• joi for validation schemas

License

ISC