@tonysamperi/ts-mapi-core-nest

A comprehensive set of shared utilities and modules for NestJS projects, providing authentication, caching, logging, database connectivity, and API validation features.

📦 Installation

npm install @tonysamperi/ts-mapi-core-nest

or

yarn add @tonysamperi/ts-mapi-core-nest

🚀 Quick Start

Import the modules you need in your NestJS application:

import {
  SmpConfigModule,
  SmpFirestoreModule,
  SmpZodOpenApiModule,
  SmpSmtpModule,
  SmpOpenFeatureModule,
  SmpCronModule
} from '@tonysamperi/ts-mapi-core-nest';

@Module({
  imports: [
    SmpConfigModule.forRoot(),
    SmpFirestoreModule.forRoot(),
    SmpZodOpenApiModule.forRoot(),
    SmpSmtpModule,
    SmpOpenFeatureModule.forRoot(),
    SmpCronModule
  ],
})
export class AppModule {}

✨ Features

🔐 Authentication & Authorization

• Guards: JWT, Basic Auth, OIDC, Microsoft Auth
• Services: Abstract user services, OIDC authentication
• Decorators: Public routes, OIDC roles/groups/user, Basic Auth restricted/forbidden/users

🗄️ Database & Storage

• Firestore: Abstract services, caching, token management
• Knex: Database connections with SSH tunneling support
• Modules: Configurable database providers

🌐 API & Validation

• Zod Integration: Schema validation with OpenAPI/Swagger generation
• DTOs: Abstract Zod DTOs with automatic API documentation
• Pipes: Validation pipes for requests

📊 Caching & Performance

• Interceptors: Cache interceptors with Firestore strategy
• Decorators: Cacheable endpoints, skip serialization

📧 Email & SMTP

• SMTP Integration: Amazon SES support with configurable settings
• Services: Email sending capabilities
• Global Module: SmpSmtpService available throughout the application

🕒 Cron Jobs

• Discovery: Automatic discovery of cron jobs via decorators
• Management: Schedule and monitor background tasks

🚀 Config&Feature Management

• OpenFeature Integration: Feature flags and experimentation
• Services: Feature flag evaluation and management

📝 Logging & Monitoring

• Winston Logger: Custom transports, Datadog integration
• Interceptors: REST logging, global error logging
• Decorators: REST logging, global error logging
• Services: Configurable logger services

🛠️ Utilities

• Config: Environment-based configuration
• HTTP: Custom exceptions, error mapping
• Decorators: Skip REST logging, class serialization
• Providers: Cache strategies, proxy middleware

📚 API Reference

Modules

• SmpConfigModule - Environment configuration management
• SmpCronModule - Cron job discovery and management
• SmpFirestoreModule - Firestore integration with caching
• SmpOpenFeatureModule - Feature flags and experimentation
• SmpSmtpModule - SMTP email sending (requires SmpConfigModule), depends on nodemailer
• SmpZodOpenApiModule - Zod validation with OpenAPI documentation

Guards

• SmpJwtAuthGuard - JWT authentication
• SmpBasicAuthGuard - Basic authentication
• SmpOidcAuthGuard - OpenID Connect authentication
• SmpRequiredHeadersGuard - Required headers validation

Services

• SmpJwtUserService - JWT user management
• SmpBasicAuthUserService - Basic auth user management
• SmpMicrosoftAuthService - Microsoft authentication
• SmpDatadogWinstonLoggerService - Datadog logging
• SmpOpenFeatureService - Feature flag management
• SmpSmtpService - Email sending via SMTP
• SmpWinstonLoggerService - Winston logging service
• SmpCronSchedulerDiscoveryService - Cron job discovery service

Decorators

• @SmpBasicAuthRestrictedTo() / @SmpBasicAuthForbiddenTo() / @SmpBasicAuthUsers() / @SmpBasicAuthUsersForbid() - Basic Auth control
• @SmpCacheable() - Enable caching for endpoints
• @SmpCronJob() - Define a cron job
• @SmpGlobalErrorLogger() - Enable global error logging for an endpoint
• @SmpOidcRoles() / @SmpOidcGroups() / @SmpOidcUser() - OIDC info extraction
• @SmpPublic() - Mark routes as public
• @SmpSkipRestLogging() - Skip REST logging
• @SmpSkipClassSerializer() - Skip class serialization

Interceptors

• SmpCacheInterceptor - Caching interceptor
• SmpClassSerializerInterceptor - Class serialization
• SmpGlobalErrorLoggerInterceptor - Global error logging
• SmpRestLoggerInterceptor - REST request logging

Exceptions

• SmpHttpBadRequestException (400)
• SmpHttpUnauthorizedException (401)
• SmpHttpForbiddenException (403)
• SmpHttpNotFoundException (404)
• SmpHttpMethodNotAllowedException (405)
• SmpHttpConflictException (409)
• SmpHttpTooManyRequestsException (429)
• SmpHttpServerException (500)

Utilities

• SmpAbstractFirebaseRemoteConfigService - Base Firebase Remote Config service to retrieve server config
• SmpAbstractFirestoreService - Base Firestore service
• SmpAbstractFirestoreTokenService - Service to store tokens in Firestore
• smpBuildPaginationNextLink - Pagination link building
• smpDefaultEnvConfig - Default environment configuration
• smpEnvironmentVariablesSchema - Environment validation schema

📖 Documentation

• Zod OpenAPI Integration Guide - Detailed guide for using Zod with Swagger/OpenAPI
• Zod OpenFeature Integration Guide - Detailed guide for using OpenFeature
• Basic Auth Guide - Detailed guide for using Basic Authentication

📄 License

ISC

👤 Author

Tony Samperi

🛠️ Development

Install deps

We use Yarn Berry, so

• corepack enable (if you haven't already)
• npm i -g yarn (if you haven't already)
• yarn install

Try locally

• npm run build

Dependencies management

This tool is quite smart and will treat as external all dependencies listed in the peerDependencies of the package.json. To work with dependencies here, you'll always install your deps as devDependencies. This will allow you to decide if your dependency can be bundled or should be an external dependency.

Based on how vital is that dependency, you might decide to make the dependency optional. To do so you'll have to get inspired by the project structure: you'll see that some dependencies are managed in a way that are imported dynamically, therefore not requiring the specific dependency (e.g. rxjs) unless specifically imported. Things to consider: structure of the exports (if you export at the wrong level, files requiring certain deps might always be loaded, leading to a MISSING MODULE error), structure of the index.cts.

Remember to test this locally with a beta version (see below).

Release a beta version ⚠️

To release a beta version, just push a beta tag, e.g. 3.0.0-beta.0

Release a production version ⚠️

To release a production version you just need to push a tag

Exports need to end with .js, because of the NodeNext resolution

Automated checks through eslint and tests