@venturialstd/core

Core shared modules and settings for Venturial applications built with NestJS.

Installation

npm install @venturialstd/core

Description

This package provides reusable core functionality for Venturial applications, including:

• Shared Module: Common infrastructure and utilities
• Settings Module: Centralized application settings management with encryption support

Modules

SharedModule

The SharedModule provides common functionality including:

• Cache Management: Redis-backed caching with Keyv
• Configuration: Application configuration with validation
• Database: TypeORM integration
• Logging: Structured logging with Winston
• Exception Handling: Global exception filters
• Request Context: Request tracking and middleware
• ACL: Access control lists and authorization

SettingsModule

The SettingsModule provides application settings management:

• Settings entity with TypeORM
• Settings service for CRUD operations
• Admin controller for managing settings
• Support for multiple setting types (e.g. STRING, BOOLEAN, SELECT, SECRET)
• Built-in encryption for sensitive values

Usage

Basic Setup (Without Custom Entities)

import { Module } from "@nestjs/common";
import { SharedModule, SettingsModule } from "@venturialstd/core";

@Module({
  imports: [SharedModule.forRoot(), SettingsModule],
})
export class AppModule {}

With Custom Entities (Option 1: Entity Classes)

Pass your application's entity classes:

import { Module } from "@nestjs/common";
import { SharedModule } from "@venturialstd/core";
import { User } from "./user/entities/user.entity";
import { Post } from "./post/entities/post.entity";
import { Comment } from "./comment/entities/comment.entity";

@Module({
  imports: [
    SharedModule.forRoot({
      entities: [User, Post, Comment], // Explicit entity classes
    }),
  ],
})
export class AppModule {}

With Custom Entities (Option 2: Glob Patterns)

Pass glob patterns to auto-discover entities from your app:

import { Module } from "@nestjs/common";
import { SharedModule } from "@venturialstd/core";

@Module({
  imports: [
    SharedModule.forRoot({
      entities: [
        __dirname + "/**/*.entity{.ts,.js}", // Auto-discover from your app
      ],
    }),
  ],
})
export class AppModule {}

Mixed Approach (Entity Classes + Glob Patterns)

You can combine both approaches:

import { Module } from "@nestjs/common";
import { SharedModule } from "@venturialstd/core";
import { User } from "./user/entities/user.entity";

@Module({
  imports: [
    SharedModule.forRoot({
      entities: [
        User, // Explicit import
        __dirname + "/modules/**/*.entity{.ts,.js}", // Plus auto-discovery
      ],
    }),
  ],
})
export class AppModule {}

Note: The SharedModule automatically includes its own entities (like Settings), so you only need to pass your application's custom entities. SettingsModule, ], }) export class AppModule {}

### Settings Encryption

The SettingsModule includes built-in support for secure encryption and decryption of sensitive configuration values, such as API keys, tokens, and credentials.

Encryption is automatically applied to settings of type SECRET.
Sensitive values are handled by the SettingsEncryptionService, which uses AES-256-GCM to ensure confidentiality and integrity.

Characteristics:

- Algorithm: AES-256-GCM
- Key derivation: scrypt
- Random IV per encryption
- Authenticated encryption (auth tag validation)
- Transparent encryption and decryption via SettingsService

### Environment Variables
```bash
SETTINGS_ENCRYPTION_KEY=your-secret-key
SETTINGS_ENCRYPTION_SALT=your-secret-salt

Recommendations:

• Use at least 16 characters for both values
• Store them securely (vault, secrets manager, CI/CD)
• Changing these values will invalidate previously encrypted settings

Using Individual Components

// Import specific utilities
import { CacheService, AppLoggerService } from "@venturialstd/core";

// Import ACL components
import { AclService, ActorConstant, ActionConstant } from "@venturialstd/core";

// Import DTOs
import { BaseApiResponse, PaginationParamsDto } from "@venturialstd/core";

Exports

Modules

• SharedModule
• SettingsModule

Services

• CacheService
• AppLoggerService
• SettingsService
• SettingsEncryptionService
• AclService

DTOs

• BaseApiResponse
• PaginationParamsDto
• RequestContextDto
• EmptyDto

Utilities

• User utilities
• Phone utilities
• Request context utilities

Decorators

• @ReqContext() - Request context decorator

Filters & Interceptors

• AllExceptionsFilter
• LoggingInterceptor

Constants

• ACL constants (Actor, Action, Rule)
• Cache constants
• Common constants
• CRUD constants

Configuration

The package expects the following environment variables:

# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=your_password

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=your_database
DB_USER=your_user
DB_PASSWORD=your_password

Peer Dependencies

This package requires the following peer dependencies:

• @dataui/crud ^5.3.4
• @dataui/crud-request ^5.3.4
• @dataui/crud-typeorm ^5.3.4
• @nestjs/common ^11.0.0
• @nestjs/core ^11.0.0
• @nestjs/typeorm ^11.0.0
• @nestjs/config ^4.0.0
• @nestjs/cache-manager ^3.0.0
• typeorm ^0.3.20
• class-validator ^0.14.1
• class-transformer ^0.5.1
• rxjs ^7.8.1

Development

# Build the package
npm run build

# The compiled output will be in the dist/ directory

License

MIT

Contributors

• Venturial Team