@quanticjs/core 1.1.1

package/src/index.ts

@@ -0,0 +1,118 @@
+// Result
+export { Result, ErrorType } from './result/Result';
+
+// Entities
+export { BaseEntity } from './entities/BaseEntity';
+export { TenantBaseEntity } from './entities/TenantBaseEntity';
+
+// Middleware
+export { CorrelationIdMiddleware } from './middleware/CorrelationIdMiddleware';
+export { correlationStore } from './middleware/CorrelationStore';
+export type { CorrelationStoreData } from './middleware/CorrelationStore';
+export { TenantContextMiddleware, TenantContext } from './middleware/TenantContextMiddleware';
+export { tenantStore } from './middleware/TenantStore';
+export type { TenantStoreData } from './middleware/TenantStore';
+
+// Filters
+export { GlobalExceptionFilter } from './filters/GlobalExceptionFilter';
+
+// Interceptors
+export { ResultInterceptor } from './interceptors/ResultInterceptor';
+
+// Guards
+export { JwtAuthGuard, Public } from './guards/JwtAuthGuard';
+export { JwtStrategy, JwtPayload } from './guards/JwtStrategy';
+export { RolesGuard, Roles } from './guards/RolesGuard';
+
+// Subscribers
+export { TenantSubscriber } from './subscribers/TenantSubscriber';
+
+// Resilience
+export { createCircuitBreaker } from './resilience/CircuitBreakerFactory';
+export type { CircuitBreakerOptions } from './resilience/CircuitBreakerFactory';
+
+// Bootstrap
+export { bootstrapService } from './bootstrap/bootstrapService';
+export type { BootstrapOptions } from './bootstrap/bootstrapService';
+
+// Logging
+export { createPinoConfig } from './logging/pino-config';
+
+// CQRS Constants
+export { REDIS_CLIENT } from './cqrs/constants';
+
+// CQRS Decorators
+export { FeatureFlag, getFeatureFlagMetadata } from './cqrs/decorators/FeatureFlag.decorator';
+export type { FeatureFlagOptions } from './cqrs/decorators/FeatureFlag.decorator';
+export { Log, getLogMetadata } from './cqrs/decorators/Log.decorator';
+export type { LogOptions } from './cqrs/decorators/Log.decorator';
+export { Validate, shouldValidate, getValidatorClass } from './cqrs/decorators/Validate.decorator';
+
+// Validation
+export type { ICommandValidator } from './cqrs/validation/ICommandValidator';
+export { validateCommand } from './cqrs/validation/ICommandValidator';
+export { Cache, getCacheMetadata } from './cqrs/decorators/Cache.decorator';
+export type { CacheOptions } from './cqrs/decorators/Cache.decorator';
+export { InvalidateCache, getInvalidateCacheMetadata } from './cqrs/decorators/InvalidateCache.decorator';
+export type { InvalidateCacheOptions } from './cqrs/decorators/InvalidateCache.decorator';
+export { DistributedLock, getDistributedLockMetadata } from './cqrs/decorators/DistributedLock.decorator';
+export type { DistributedLockOptions } from './cqrs/decorators/DistributedLock.decorator';
+export { IsolatedTransaction, isIsolatedTransaction } from './cqrs/decorators/IsolatedTransaction.decorator';
+export { Workflow, getWorkflowMetadata } from './cqrs/decorators/Workflow.decorator';
+export type { WorkflowOptions } from './cqrs/decorators/Workflow.decorator';
+
+// Workflow Engine Interface
+export { WORKFLOW_ENGINE } from './cqrs/interfaces/WorkflowEngine';
+export type { WorkflowEngine, WorkflowStartResult } from './cqrs/interfaces/WorkflowEngine';
+
+// Transaction (UnitOfWork)
+export { TransactionContext } from './cqrs/transaction/TransactionContext';
+export { getTransactionalRepo } from './cqrs/transaction/getTransactionalRepo';
+
+// Metrics
+export { MetricsService } from './metrics/MetricsService';
+export { MetricsController } from './metrics/MetricsController';
+
+// CQRS Behaviors
+export { LogBehavior } from './cqrs/behaviors/LogBehavior';
+export { FeatureFlagBehavior } from './cqrs/behaviors/FeatureFlagBehavior';
+export { ValidationBehavior } from './cqrs/behaviors/ValidationBehavior';
+export { CacheBehavior } from './cqrs/behaviors/CacheBehavior';
+export { InvalidateCacheBehavior } from './cqrs/behaviors/InvalidateCacheBehavior';
+export { DistributedLockBehavior } from './cqrs/behaviors/DistributedLockBehavior';
+export { TransactionalBehavior } from './cqrs/behaviors/TransactionalBehavior';
+export { PerformanceBehavior } from './cqrs/behaviors/PerformanceBehavior';
+export { WorkflowBehavior } from './cqrs/behaviors/WorkflowBehavior';
+
+// CQRS Pipeline
+export { QuanticCommandBus } from './cqrs/pipeline/QuanticCommandBus';
+export { QuanticQueryBus } from './cqrs/pipeline/QuanticQueryBus';
+export { type BehaviorFn } from './cqrs/pipeline/runPipeline';
+
+// Redis
+export { RedisModule } from './redis/redis.module';
+export type { RedisModuleOptions } from './redis/redis.module';
+
+// Events
+export { DomainEvent } from './events/DomainEvent';
+export type { DomainEventPayload } from './events/DomainEvent';
+export { OutboxEvent, OutboxEventStatus } from './events/OutboxEvent.entity';
+export { RedisStreamPublisher } from './events/RedisStreamPublisher';
+export { RedisStreamConsumer } from './events/RedisStreamConsumer';
+export { OutboxPublisherService } from './events/OutboxPublisherService';
+
+// Unleash
+export { UnleashModule } from './unleash/unleash.module';
+export type { UnleashModuleOptions } from './unleash/unleash.module';
+
+// Lifecycle
+export { GracefulShutdownService } from './lifecycle/GracefulShutdownService';
+
+// QuanticModule
+export { QuanticModule, SharedKernelModule } from './shared-kernel.module';
+export type { QuanticModuleOptions, SharedKernelModuleOptions } from './shared-kernel.module';
+
+// Testing mock helpers (safe for prod — no @nestjs/testing dependency)
+export { createMockRepository, createMockRedisClient } from './testing/mocks';
+
+

package/src/interceptors/ResultInterceptor.ts

@@ -0,0 +1,93 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Logger,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+import { Observable, switchMap, catchError, of, EMPTY } from 'rxjs';
+import { Result, ErrorType } from '../result/Result';
+import { correlationStore } from '../middleware/CorrelationStore';
+
+const ERROR_TYPE_TO_STATUS: Record<string, number> = {
+  [ErrorType.NotFound]: 404,
+  [ErrorType.Forbidden]: 403,
+  [ErrorType.Unauthorized]: 401,
+  [ErrorType.Conflict]: 409,
+  [ErrorType.ValidationError]: 400,
+  [ErrorType.UnprocessableEntity]: 422,
+  [ErrorType.InternalError]: 500,
+};
+
+const ERROR_TYPE_TO_TITLE: Record<string, string> = {
+  [ErrorType.NotFound]: 'Not Found',
+  [ErrorType.Forbidden]: 'Forbidden',
+  [ErrorType.Unauthorized]: 'Unauthorized',
+  [ErrorType.Conflict]: 'Conflict',
+  [ErrorType.ValidationError]: 'Validation Error',
+  [ErrorType.UnprocessableEntity]: 'Unprocessable Entity',
+  [ErrorType.InternalError]: 'Internal Server Error',
+};
+
+@Injectable()
+export class ResultInterceptor implements NestInterceptor {
+  private readonly logger = new Logger(ResultInterceptor.name);
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    return next.handle().pipe(
+      switchMap((data) => {
+        if (data instanceof Result && !data.isSuccess) {
+          this.sendResultError(context, data);
+          return EMPTY;
+        }
+        return of(data);
+      }),
+      catchError((error) => {
+        if (error instanceof Result) {
+          this.sendResultError(context, error);
+          return EMPTY;
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.logger.error({
+          msg: 'Unhandled exception before CQRS pipeline',
+          error: err.message,
+          stack: err.stack,
+        });
+        this.sendResultError(context, Result.failure(ErrorType.InternalError, err.message));
+        return EMPTY;
+      }),
+    );
+  }
+
+  private sendResultError(context: ExecutionContext, result: Result<unknown>): void {
+    const request = context.switchToHttp().getRequest<Request>();
+    const response = context.switchToHttp().getResponse<Response>();
+    const correlationId = correlationStore.getStore()?.correlationId;
+    const status = ERROR_TYPE_TO_STATUS[result.errorType!] ?? 500;
+    const title = ERROR_TYPE_TO_TITLE[result.errorType!] ?? 'Unknown Error';
+
+    if (correlationId) {
+      response.setHeader('X-Correlation-ID', correlationId);
+    }
+
+    this.logger.warn({
+      msg: `${status} ${result.errorType}`,
+      correlationId,
+      status,
+      detail: result.errorMessage,
+    });
+
+    response
+      .status(status)
+      .setHeader('Content-Type', 'application/problem+json')
+      .json({
+        type: `https://arex.dev/errors/${result.errorType}`,
+        title,
+        status,
+        detail: result.errorMessage,
+        instance: request.originalUrl,
+        correlationId,
+      });
+  }
+}

package/src/lifecycle/GracefulShutdownService.ts

@@ -0,0 +1,77 @@
+import { Injectable, Logger, OnModuleDestroy, Optional, Inject } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { REDIS_CLIENT } from '../cqrs/constants';
+import type { Redis } from 'ioredis';
+
+const SHUTDOWN_TIMEOUT_MS = 30_000;
+
+/**
+ * GracefulShutdownService ensures clean resource teardown on SIGTERM/SIGINT.
+ *
+ * Shutdown order:
+ * 1. Wait for in-flight work (subclasses can override `drainWork`)
+ * 2. Close database connections
+ * 3. Quit Redis
+ */
+@Injectable()
+export class GracefulShutdownService implements OnModuleDestroy {
+  private readonly logger = new Logger(GracefulShutdownService.name);
+
+  constructor(
+    @Optional() private readonly dataSource?: DataSource,
+    @Optional() @Inject(REDIS_CLIENT) private readonly redis?: Redis,
+  ) {}
+
+  async onModuleDestroy(): Promise<void> {
+    this.logger.log('Graceful shutdown initiated...');
+
+    // 1. Drain in-flight work with timeout
+    try {
+      await this.withTimeout(this.drainWork(), SHUTDOWN_TIMEOUT_MS, 'Work drain');
+    } catch (err) {
+      this.logger.warn(`Work drain timeout or error: ${(err as Error).message}`);
+    }
+
+    // 2. Close database connections
+    if (this.dataSource?.isInitialized) {
+      try {
+        await this.dataSource.destroy();
+        this.logger.log('Database connections closed');
+      } catch (err) {
+        this.logger.warn(`Database close error: ${(err as Error).message}`);
+      }
+    }
+
+    // 3. Quit Redis
+    if (this.redis) {
+      try {
+        await this.redis.quit();
+        this.logger.log('Redis connection closed');
+      } catch (err) {
+        this.logger.warn(`Redis quit error: ${(err as Error).message}`);
+      }
+    }
+
+    this.logger.log('Graceful shutdown complete');
+  }
+
+  /**
+   * Override in service-specific subclasses to drain Bull queues,
+   * close Socket.IO servers, etc.
+   */
+  protected async drainWork(): Promise<void> {
+    // Base implementation — no-op
+  }
+
+  private withTimeout(promise: Promise<void>, ms: number, label: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`${label} timed out after ${ms}ms`));
+      }, ms);
+
+      promise
+        .then(() => { clearTimeout(timer); resolve(); })
+        .catch((err) => { clearTimeout(timer); reject(err); });
+    });
+  }
+}

package/src/logging/pino-config.ts

@@ -0,0 +1,80 @@
+function canResolvePinoSeq(): boolean {
+  try {
+    require.resolve('pino-seq');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildTransport(logLevel: string) {
+  const seqUrl = process.env['SEQ_URL'];
+  const useSeq = seqUrl && canResolvePinoSeq();
+
+  if (process.env['NODE_ENV'] === 'production' && useSeq) {
+    return {
+      target: 'pino-seq',
+      options: { serverUrl: seqUrl, logOtherAs: 'Verbose' },
+    };
+  }
+
+  const targets: any[] = [
+    { target: 'pino/file', options: { destination: 1 }, level: logLevel },
+  ];
+
+  if (useSeq) {
+    targets.push({
+      target: 'pino-seq',
+      options: { serverUrl: seqUrl, logOtherAs: 'Verbose' },
+      level: logLevel,
+    });
+  }
+
+  return { targets };
+}
+
+export function createPinoConfig(serviceName: string) {
+  const logLevel = process.env['LOG_LEVEL'] || 'info';
+
+  return {
+    pinoHttp: {
+      level: logLevel,
+      transport: buildTransport(logLevel),
+      serializers: {
+        req(req: any) {
+          return {
+            id: req.id,
+            method: req.method,
+            url: req.url,
+            correlationId: req.raw?.correlationId || req.headers?.['x-correlation-id'],
+          };
+        },
+        res(res: any) {
+          return {
+            statusCode: res.statusCode,
+          };
+        },
+        email(value: string) {
+          if (!value || typeof value !== 'string') return value;
+          const [local, domain] = value.split('@');
+          if (!domain) return value;
+          return `${local[0]}***@${domain}`;
+        },
+        token(_value: string) {
+          return '[REDACTED]';
+        },
+        brd(value: string) {
+          if (!value || typeof value !== 'string') return value;
+          return value.length > 50 ? `${value.substring(0, 50)}...` : value;
+        },
+      },
+      customProps(req: any) {
+        return {
+          correlationId:
+            req.correlationId || req.headers?.['x-correlation-id'],
+          service: serviceName,
+        };
+      },
+    },
+  };
+}

package/src/metrics/MetricsController.ts

@@ -0,0 +1,17 @@
+import { Controller, Get, Res } from '@nestjs/common';
+import { Response } from 'express';
+import { Public } from '../guards/JwtAuthGuard';
+import { MetricsService } from './MetricsService';
+
+@Public()
+@Controller()
+export class MetricsController {
+  constructor(private readonly metrics: MetricsService) {}
+
+  @Get('metrics')
+  async getMetrics(@Res() res: Response) {
+    const metricsOutput = await this.metrics.getMetrics();
+    res.set('Content-Type', this.metrics.getContentType());
+    res.end(metricsOutput);
+  }
+}

package/src/metrics/MetricsService.ts

@@ -0,0 +1,55 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from 'prom-client';
+
+@Injectable()
+export class MetricsService implements OnModuleInit {
+  readonly registry = new Registry();
+
+  readonly buildTotal = new Counter({
+    name: 'arex_build_total',
+    help: 'Total number of builds',
+    labelNames: ['status', 'tech_stack'] as const,
+    registers: [this.registry],
+  });
+
+  readonly stageDuration = new Histogram({
+    name: 'arex_stage_duration_seconds',
+    help: 'Duration of pipeline stages in seconds',
+    labelNames: ['stage_type', 'status'] as const,
+    buckets: [0.5, 1, 2, 5, 10, 30, 60, 120, 300],
+    registers: [this.registry],
+  });
+
+  readonly promptCacheHits = new Counter({
+    name: 'arex_prompt_cache_hits_total',
+    help: 'Total prompt cache hits',
+    registers: [this.registry],
+  });
+
+  readonly queueDepth = new Gauge({
+    name: 'arex_queue_depth',
+    help: 'Current depth of Bull job queue',
+    labelNames: ['queue'] as const,
+    registers: [this.registry],
+  });
+
+  readonly handlerDuration = new Histogram({
+    name: 'arex_handler_duration_seconds',
+    help: 'Duration of command/query handlers in seconds',
+    labelNames: ['handler', 'result'] as const,
+    buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2, 5],
+    registers: [this.registry],
+  });
+
+  onModuleInit() {
+    collectDefaultMetrics({ register: this.registry });
+  }
+
+  async getMetrics(): Promise<string> {
+    return this.registry.metrics();
+  }
+
+  getContentType(): string {
+    return this.registry.contentType;
+  }
+}

package/src/middleware/CorrelationIdMiddleware.ts

@@ -0,0 +1,27 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { v4 as uuidv4 } from 'uuid';
+import { correlationStore } from './CorrelationStore';
+
+const CORRELATION_ID_HEADER = 'X-Correlation-ID';
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  use(req: any, res: any, next: () => void): void {
+    const correlationId =
+      (req.headers[CORRELATION_ID_HEADER.toLowerCase()] as string) || uuidv4();
+
+    req.correlationId = correlationId;
+    req.headers[CORRELATION_ID_HEADER.toLowerCase()] = correlationId;
+    res.setHeader(CORRELATION_ID_HEADER, correlationId);
+
+    const storeData = {
+      correlationId,
+      userId: req.user?.keycloakId,
+      organizationId: req.user?.organizationId,
+    };
+
+    correlationStore.run(storeData, () => {
+      next();
+    });
+  }
+}

package/src/middleware/CorrelationStore.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+export interface CorrelationStoreData {
+  correlationId: string;
+  userId?: string;
+  organizationId?: string;
+}
+
+/**
+ * Request-scoped async local storage for correlation context.
+ * Set by CorrelationIdMiddleware, read by LogBehavior and error filters.
+ */
+export const correlationStore = new AsyncLocalStorage<CorrelationStoreData>();

package/src/middleware/TenantContextMiddleware.ts

@@ -0,0 +1,21 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { tenantStore } from './TenantStore';
+
+export interface TenantContext {
+  organizationId: string | null;
+}
+
+@Injectable()
+export class TenantContextMiddleware implements NestMiddleware {
+  use(req: any, _res: any, next: () => void): void {
+    // Extract org_id from JWT payload (set by JwtAuthGuard)
+    const orgId = req.user?.organizationId || req.headers['x-tenant-id'] || null;
+    req.tenantId = orgId;
+    req.tenantContext = { organizationId: orgId } as TenantContext;
+
+    // Store in AsyncLocalStorage so TenantSubscriber can access it
+    tenantStore.run({ organizationId: orgId }, () => {
+      next();
+    });
+  }
+}

package/src/middleware/TenantStore.ts

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+export interface TenantStoreData {
+  organizationId: string | null;
+}
+
+/**
+ * Request-scoped async local storage for tenant context.
+ * Set by TenantContextMiddleware, read by TenantSubscriber.
+ */
+export const tenantStore = new AsyncLocalStorage<TenantStoreData>();

package/src/redis/redis.module.ts

@@ -0,0 +1,41 @@
+import { DynamicModule, Global, Logger, Module } from '@nestjs/common';
+import Redis from 'ioredis';
+import { REDIS_CLIENT } from '../cqrs/constants';
+
+export interface RedisModuleOptions {
+  url?: string;
+}
+
+@Global()
+@Module({})
+export class RedisModule {
+  private static readonly logger = new Logger('RedisModule');
+
+  static forRoot(options: RedisModuleOptions = {}): DynamicModule {
+    const redisProvider = {
+      provide: REDIS_CLIENT,
+      useFactory: () => {
+        const url = options.url || process.env.REDIS_URL || 'redis://localhost:6379';
+        const client = new Redis(url, {
+          maxRetriesPerRequest: 3,
+          retryStrategy(times: number) {
+            const delay = Math.min(times * 200, 5000);
+            RedisModule.logger.warn(`Redis reconnecting (attempt ${times}, delay ${delay}ms)`);
+            return delay;
+          },
+        });
+
+        client.on('connect', () => RedisModule.logger.log('Redis connected'));
+        client.on('error', (err) => RedisModule.logger.error('Redis error', err.message));
+
+        return client;
+      },
+    };
+
+    return {
+      module: RedisModule,
+      providers: [redisProvider],
+      exports: [REDIS_CLIENT],
+    };
+  }
+}

package/src/resilience/CircuitBreakerFactory.ts

@@ -0,0 +1,33 @@
+import { circuitBreaker, ConsecutiveBreaker, handleAll, retry, wrap, ExponentialBackoff } from 'cockatiel';
+
+export interface CircuitBreakerOptions {
+  halfOpenAfterMs?: number;
+  consecutiveFailures?: number;
+  maxRetries?: number;
+}
+
+/**
+ * Creates a resilience policy combining retry + circuit breaker.
+ * Usage:
+ *   const policy = createCircuitBreaker({ consecutiveFailures: 5 });
+ *   const result = await policy.execute(() => httpCall());
+ */
+export function createCircuitBreaker(options: CircuitBreakerOptions = {}) {
+  const {
+    halfOpenAfterMs = 30_000,
+    consecutiveFailures = 5,
+    maxRetries = 2,
+  } = options;
+
+  const retryPolicy = retry(handleAll, {
+    maxAttempts: maxRetries,
+    backoff: new ExponentialBackoff(),
+  });
+
+  const breaker = circuitBreaker(handleAll, {
+    halfOpenAfter: halfOpenAfterMs,
+    breaker: new ConsecutiveBreaker(consecutiveFailures),
+  });
+
+  return wrap(retryPolicy, breaker);
+}

package/src/result/Result.ts

@@ -0,0 +1,66 @@
+export enum ErrorType {
+  NotFound = 'NOT_FOUND',
+  Forbidden = 'FORBIDDEN',
+  Conflict = 'CONFLICT',
+  ValidationError = 'VALIDATION_ERROR',
+  InternalError = 'INTERNAL_ERROR',
+  Unauthorized = 'UNAUTHORIZED',
+  UnprocessableEntity = 'UNPROCESSABLE_ENTITY',
+}
+
+export class Result<T> {
+  private constructor(
+    public readonly isSuccess: boolean,
+    public readonly value?: T,
+    public readonly errorType?: ErrorType,
+    public readonly errorMessage?: string,
+  ) {}
+
+  static success<T>(value: T): Result<T> {
+    return new Result<T>(true, value);
+  }
+
+  static failure<T>(errorType: ErrorType, message: string): Result<T> {
+    return new Result<T>(false, undefined, errorType, message);
+  }
+
+  static notFound<T>(message: string): Result<T> {
+    return Result.failure<T>(ErrorType.NotFound, message);
+  }
+
+  static forbidden<T>(message: string): Result<T> {
+    return Result.failure<T>(ErrorType.Forbidden, message);
+  }
+
+  static conflict<T>(message: string): Result<T> {
+    return Result.failure<T>(ErrorType.Conflict, message);
+  }
+
+  static validationError<T>(message: string): Result<T> {
+    return Result.failure<T>(ErrorType.ValidationError, message);
+  }
+
+  static unauthorized<T>(message: string): Result<T> {
+    return Result.failure<T>(ErrorType.Unauthorized, message);
+  }
+
+  static unprocessableEntity<T>(message: string): Result<T> {
+    return Result.failure<T>(ErrorType.UnprocessableEntity, message);
+  }
+
+  unwrap(): T {
+    if (!this.isSuccess || this.value === undefined) {
+      throw new Error(
+        `Cannot unwrap failed Result: ${this.errorType} - ${this.errorMessage}`,
+      );
+    }
+    return this.value;
+  }
+
+  map<U>(fn: (value: T) => U): Result<U> {
+    if (this.isSuccess && this.value !== undefined) {
+      return Result.success(fn(this.value));
+    }
+    return Result.failure<U>(this.errorType!, this.errorMessage!);
+  }
+}