@onivoro/server-common

A comprehensive collection of common server utilities, DTOs, decorators, pipes, and functions for building robust NestJS applications. This library provides foundational components used across enterprise-scale server applications.

Installation

1npm install @onivoro/server-common

Features

• NestJS Module: Ready-to-import server common module
• Error Handling: Advanced error filters for TypeORM and general exceptions
• API Decorators: OpenAPI documentation decorators and response formatters
• DTOs: Common data transfer objects for typical API operations
• Validation Pipes: Custom pipes for data parsing and validation
• Utility Functions: Helper functions for API creation, encoding, file operations, and more
• Environment Management: Environment variable handling and configuration
• Application Bootstrap: Functions for creating and configuring API applications

Quick Start

Import the Module

1import { ServerCommonModule } from '@onivoro/server-common';
2
3@Module({
4  imports: [ServerCommonModule],
5  // ...
6})
7export class AppModule {}

Using API Configuration

1import { createApiApp, configureApiApp } from '@onivoro/server-common';
2
3async function bootstrap() {
4  const app = await createApiApp(AppModule);
5  await configureApiApp(app, {
6    port: 3000,
7    title: 'My API',
8    version: '1.0.0'
9  });
10}

Environment Configuration

1import { EnvironmentClass } from '@onivoro/server-common';
2
3@EnvironmentClass()
4export class AppConfig {
5  @EnvironmentVariable('DATABASE_URL')
6  databaseUrl: string;
7
8  @EnvironmentVariable('PORT', '3000')
9  port: number;
10}

Configuration

The library provides several configuration utilities:

Environment Variables

1import { loadDotEnvForKey } from '@onivoro/server-common';
2
3// Load environment variables for a specific key
4loadDotEnvForKey('development');

Version Management

1import { getPackageVersion, VERSION_PROVIDER_TOKEN } from '@onivoro/server-common';
2
3// Get version from package.json
4const version = getPackageVersion();
5
6// Use as provider
7@Module({
8  providers: [
9    {
10      provide: VERSION_PROVIDER_TOKEN,
11      useValue: getPackageVersion()
12    }
13  ]
14})
15export class AppModule {}

Usage Examples

Error Handling

1import { ErrorFilter, TypeormErrorFilter } from '@onivoro/server-common';
2
3@UseFilters(new ErrorFilter(), new TypeormErrorFilter())
4@Controller('api')
5export class ApiController {
6  // Your controller methods
7}

API Documentation Decorators

1import { 
2  DefaultApiController, 
3  ApiResponsePaged, 
4  ApiQueryPagedParams 
5} from '@onivoro/server-common';
6
7@DefaultApiController('users')
8export class UsersController {
9  @Get()
10  @ApiQueryPagedParams()
11  @ApiResponsePaged(UserDto)
12  async findAll(@QueryPagedParams() params: PageParams) {
13    // Implementation
14  }
15}

Common DTOs

1import { 
2  PagedResponseDto, 
3  SuccessDto, 
4  HealthDto,
5  EmailDto 
6} from '@onivoro/server-common';
7
8@Get('health')
9async getHealth(): Promise<HealthDto> {
10  return { status: 'ok', timestamp: new Date() };
11}
12
13@Post('send-email')
14async sendEmail(@Body() emailDto: EmailDto): Promise<SuccessDto> {
15  // Send email logic
16  return { success: true };
17}

Validation Pipes

1import { 
2  ParseDateOptionalPipe, 
3  ParseUuidOptionalPipe,
4  ZodValidationPipe 
5} from '@onivoro/server-common';
6
7@Get('events')
8async getEvents(
9  @Query('date', ParseDateOptionalPipe) date?: Date,
10  @Query('userId', ParseUuidOptionalPipe) userId?: string
11) {
12  // Implementation
13}

Utility Functions

1import { 
2  generateUniqueCode,
3  getRandomString,
4  encode,
5  decode,
6  shell,
7  tryCatch
8} from '@onivoro/server-common';
9
10// Generate unique codes
11const code = generateUniqueCode(8);
12
13// Random string generation
14const randomStr = getRandomString(16);
15
16// Encoding/decoding
17const encoded = encode('sensitive data');
18const decoded = decode(encoded);
19
20// Shell command execution
21const result = await shell('ls -la');
22
23// Safe function execution
24const [error, result] = await tryCatch(async () => {
25  return await someAsyncOperation();
26});

File Operations

1import { 
2  readFileAsJson,
3  saveFileAsJson,
4  parsePackageJson 
5} from '@onivoro/server-common';
6
7// Read JSON file
8const config = await readFileAsJson('./config.json');
9
10// Save JSON file
11await saveFileAsJson('./output.json', { data: 'example' });
12
13// Parse package.json
14const packageInfo = parsePackageJson('./package.json');

Application Metadata

1import { generateAppMetadata } from '@onivoro/server-common';
2
3const metadata = generateAppMetadata({
4  name: 'My API',
5  version: '1.0.0',
6  description: 'Example API'
7});

API Reference

Core Functions

• createApiApp(module): Create NestJS application
• configureApiApp(app, options): Configure API with OpenAPI, CORS, etc.
• moduleFactory(module, options): Create dynamic modules
• initOpenapi(app, config): Initialize OpenAPI documentation

Utility Functions

• encode(data): Encode sensitive data
• decode(data): Decode sensitive data
• generateUniqueCode(length): Generate unique alphanumeric codes
• getRandomString(length): Generate random strings
• shell(command): Execute shell commands
• tryCatch(fn): Safe async function execution

File Operations

• readFileAsJson(path): Read and parse JSON files
• saveFileAsJson(path, data): Save data as JSON file
• parsePackageJson(path): Parse package.json files

Environment

• loadDotEnvForKey(key): Load environment variables
• getPackageVersion(): Get current package version
• isPortInUse(port): Check if port is available

Memory and Performance

• getMemoryStats(): Get Node.js memory statistics

DTOs

Common DTOs

• SuccessDto: Standard success response
• HealthDto: Health check response
• EmailDto: Email data transfer object
• PagedResponseDto: Paginated response wrapper
• LookupDto: Key-value lookup objects

Request DTOs

• BodyDto: Generic request body
• UserIdDto: User ID parameter
• ValueDto/ValuesDto: Generic value containers

Decorators

API Documentation

• @DefaultApiController: Standard API controller decorator
• @ApiResponsePaged: Paginated response documentation
• @ApiQueryPagedParams: Paginated query parameters
• @ApiBodyUnspecified: Unspecified request body
• @ApiResponseUnspecified: Unspecified response

Environment

• @EnvironmentClass: Mark classes for environment variable injection

Query Parameters

• @QueryPagedParams: Extract pagination parameters

Error Handling

The library provides comprehensive error handling:

• ErrorFilter: General application error filter
• TypeormErrorFilter: Database-specific error handling
• Structured Error Responses: Consistent error response format

Best Practices

1. Use Type Safety: Leverage TypeScript for all DTOs and interfaces
2. Environment Configuration: Use @EnvironmentClass for configuration
3. Error Handling: Apply error filters at the controller level
4. API Documentation: Use provided decorators for OpenAPI documentation
5. Validation: Use custom pipes for input validation
6. Pagination: Use provided pagination utilities for list endpoints

License

This library is licensed under the MIT License. See the LICENSE file in this package for details.