@dumanarge/xssrv-shared-lib

Shared infrastructure library for DumanArge IoT Platform NestJS microservices.

Provides production-ready modules for tracing, structured logging, health checks, transactional outbox pattern, multi-tenant isolation, audit trails, feature flags, and graceful shutdown.

Installation

npm install @dumanarge/xssrv-shared-lib

Peer Dependencies

This library uses peer dependencies to avoid version conflicts. Install the modules you need:

# Core (required)
npm install @nestjs/common @nestjs/core rxjs reflect-metadata

# Tracing (for OpenTelemetry support)
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/exporter-metrics-otlp-grpc \
  @opentelemetry/resources @opentelemetry/sdk-metrics

# Logging
npm install nestjs-pino pino pino-http

# Health checks
npm install @nestjs/terminus

# Outbox & Tenant isolation
npm install @prisma/client

# Feature flags
npm install @nestjs/config

# Redis health indicator
npm install ioredis

Modules

Tracing (OpenTelemetry)

Bootstrap tracing before your NestJS app starts:

// main.ts — must be the FIRST import
import '@dumanarge/xssrv-shared-lib/tracing';

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

Use the @Span() decorator for custom business logic tracing:

import { Span } from '@dumanarge/xssrv-shared-lib';

@Injectable()
export class DeviceService {
  @Span('device.provision')
  async provisionDevice(dto: CreateDeviceDto) {
    // Automatically traced with OpenTelemetry
  }
}

Environment variables:

| Variable | Default | Description | |---|---|---| | SERVICE_NAME | unknown-service | OTel service name | | SERVICE_VERSION | 1.0.0 | OTel service version | | OTEL_EXPORTER_OTLP_ENDPOINT | http://localhost:4317 | OTel Collector endpoint | | OTEL_DEBUG | false | Enable OTel debug logging |

Logging (Pino + OTel)

import { LoggingModule } from '@dumanarge/xssrv-shared-lib';

@Module({
  imports: [LoggingModule],
})
export class AppModule {}

Features: JSON structured logs, automatic traceId/spanId injection, request correlation via X-Request-Id, sensitive field redaction, health endpoint filtering.

Health Checks

import { HealthModule } from '@dumanarge/xssrv-shared-lib';

@Module({
  imports: [HealthModule],
})
export class AppModule {}

Exposes GET /health/live (liveness) and GET /health/ready (readiness) endpoints for Kubernetes probes.

Custom health indicators included: RedisHealthIndicator, RabbitMQHealthIndicator.

Multi-Tenant Isolation

import {
  TenantMiddleware,
  TenantGuard,
  TenantContext,
  createPrismaTenantMiddleware,
} from '@dumanarge/xssrv-shared-lib';

// In AppModule
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(TenantMiddleware).forRoutes('*');
  }
}

// In service — automatic tenant scoping for Prisma
prisma.$use(createPrismaTenantMiddleware(() => tenantContext.tenantId));

Outbox Pattern

Guaranteed event delivery via transactional outbox:

import { OutboxRepository, RabbitMQEventPublisher, OutboxWorker } from '@dumanarge/xssrv-shared-lib';

// Write event in the same DB transaction as business data
await prisma.$transaction(async (tx) => {
  await tx.tenant.create({ data: tenantData });
  await outboxRepo.createInTransaction(tx, {
    aggregateType: 'tenant',
    aggregateId: tenant.id,
    eventType: 'tenant.created',
    payload: tenantData,
  });
});

Audit Interceptor

Tamper-proof audit trail for all mutation operations (POST/PUT/PATCH/DELETE):

import { AuditInterceptor } from '@dumanarge/xssrv-shared-lib';

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

Feature Flags

Dynamic feature toggles via Consul KV with local cache fallback:

import { FeatureFlagService } from '@dumanarge/xssrv-shared-lib';

const isEnabled = await featureFlags.isEnabled('device_twin_enabled', tenantId);
const config = await featureFlags.getConfig('batch_signal_processing');

Graceful Shutdown

import { GracefulShutdownModule, enableGracefulShutdown } from '@dumanarge/xssrv-shared-lib';

// In AppModule
@Module({
  imports: [GracefulShutdownModule],
})
export class AppModule {}

// In main.ts
const app = await NestFactory.create(AppModule);
enableGracefulShutdown(app);

Sub-path Imports

You can import individual modules directly to minimize bundle:

import '@dumanarge/xssrv-shared-lib/tracing';
import { LoggingModule } from '@dumanarge/xssrv-shared-lib/logging';
import { HealthModule } from '@dumanarge/xssrv-shared-lib/health';
import { OutboxRepository } from '@dumanarge/xssrv-shared-lib/outbox';
import { TenantMiddleware } from '@dumanarge/xssrv-shared-lib/auth';
import { GracefulShutdownModule } from '@dumanarge/xssrv-shared-lib/config';

Requirements

• Node.js >= 20
• NestJS >= 11
• TypeScript >= 5.7

License

MIT