@quanticjs/core 1.1.1 → 2.1.0

package/src/cqrs/behaviors/DistributedLockBehavior.ts

@@ -1,88 +0,0 @@
-import { Injectable, Logger, Optional, Inject } from '@nestjs/common';
-import { getDistributedLockMetadata } from '../decorators/DistributedLock.decorator';
-import { Result, ErrorType } from '../../result/Result';
-import { REDIS_CLIENT } from '../constants';
-import type { Redis } from 'ioredis';
-import { v4 as uuidv4 } from 'uuid';
-
-@Injectable()
-export class DistributedLockBehavior {
-  private readonly logger = new Logger(DistributedLockBehavior.name);
-
-  constructor(
-    @Optional() @Inject(REDIS_CLIENT) private readonly redis?: Redis,
-  ) {}
-
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    const metadata = getDistributedLockMetadata(command.constructor);
-
-    if (!metadata || !this.redis) {
-      return next();
-    }
-
-    const lockKey = `lock:${this.interpolateKey(metadata.key, command)}`;
-    const lockValue = uuidv4();
-    const acquired = await this.tryAcquire(
-      lockKey,
-      lockValue,
-      metadata.lockTtlSeconds!,
-      metadata.acquireTimeoutSeconds!,
-    );
-
-    if (!acquired) {
-      this.logger.warn(`Failed to acquire lock: ${lockKey}`);
-      return Result.failure<T>(ErrorType.Conflict, `Resource is locked: ${metadata.key}`);
-    }
-
-    try {
-      return await next();
-    } finally {
-      await this.release(lockKey, lockValue);
-    }
-  }
-
-  private async tryAcquire(
-    key: string,
-    value: string,
-    ttlSeconds: number,
-    timeoutSeconds: number,
-  ): Promise<boolean> {
-    const deadline = Date.now() + timeoutSeconds * 1000;
-    const retryDelay = 50;
-
-    while (Date.now() < deadline) {
-      const result = await this.redis!.set(key, value, 'EX', ttlSeconds, 'NX');
-      if (result === 'OK') return true;
-      await this.sleep(retryDelay);
-    }
-
-    return false;
-  }
-
-  private async release(key: string, value: string): Promise<void> {
-    // Lua script ensures only the owner releases the lock
-    const script = `
-      if redis.call("get", KEYS[1]) == ARGV[1] then
-        return redis.call("del", KEYS[1])
-      else
-        return 0
-      end
-    `;
-    try {
-      await this.redis!.eval(script, 1, key, value);
-    } catch {
-      this.logger.warn(`Failed to release lock: ${key}`);
-    }
-  }
-
-  private sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-
-  private interpolateKey(template: string, command: object): string {
-    return template.replace(/\{(\w+)\}/g, (_, prop) => {
-      const value = (command as Record<string, unknown>)[prop];
-      return value != null ? String(value) : '';
-    });
-  }
-}

package/src/cqrs/behaviors/FeatureFlagBehavior.ts

@@ -1,46 +0,0 @@
-import { Injectable, Optional, Logger } from '@nestjs/common';
-import { Unleash } from 'unleash-client';
-import { getFeatureFlagMetadata } from '../decorators/FeatureFlag.decorator';
-import { Result, ErrorType } from '../../result/Result';
-
-@Injectable()
-export class FeatureFlagBehavior {
-  private readonly logger = new Logger(FeatureFlagBehavior.name);
-
-  constructor(@Optional() private readonly unleash?: Unleash) {}
-
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    const metadata = getFeatureFlagMetadata(command.constructor);
-
-    if (!metadata) {
-      return next();
-    }
-
-    if (!this.unleash) {
-      this.logger.debug('Unleash not configured, skipping feature flag check');
-      return next();
-    }
-
-    const { flagName, fallback, defaultValue } = metadata;
-    const isEnabled = this.unleash.isEnabled(flagName);
-
-    if (isEnabled) {
-      return next();
-    }
-
-    this.logger.warn(`Feature flag "${flagName}" is disabled, applying fallback: ${fallback}`);
-
-    switch (fallback) {
-      case 'skip':
-        return Result.success(undefined as unknown as T);
-      case 'default':
-        return Result.success(defaultValue as T);
-      case 'throw':
-      default:
-        return Result.failure<T>(
-          ErrorType.Forbidden,
-          `Feature "${flagName}" is currently disabled`,
-        );
-    }
-  }
-}

package/src/cqrs/behaviors/InvalidateCacheBehavior.spec.ts

@@ -1,89 +0,0 @@
-import { InvalidateCacheBehavior } from './InvalidateCacheBehavior';
-import { Result, ErrorType } from '../../result/Result';
-import { InvalidateCache } from '../decorators/InvalidateCache.decorator';
-
-@InvalidateCache(['user:{userId}', 'users:list'])
-class UpdateUserCommand {
-  constructor(
-    public readonly userId: string,
-    public readonly name: string,
-  ) {}
-}
-
-@InvalidateCache([])
-class EmptyKeysCommand {}
-
-class PlainCommand {
-  constructor(public readonly id: string) {}
-}
-
-describe('InvalidateCacheBehavior', () => {
-  let redis: { del: jest.Mock };
-  let behavior: InvalidateCacheBehavior;
-  const next = jest.fn();
-
-  beforeEach(() => {
-    redis = {
-      del: jest.fn().mockResolvedValue(1),
-    };
-    behavior = new InvalidateCacheBehavior(redis as any);
-    next.mockReset().mockResolvedValue(Result.success({ updated: true }));
-  });
-
-  it('should skip when command has no @InvalidateCache decorator', async () => {
-    const result = await behavior.execute(new PlainCommand('1'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-    expect(redis.del).not.toHaveBeenCalled();
-  });
-
-  it('should skip when Redis is unavailable', async () => {
-    const noRedisBehavior = new InvalidateCacheBehavior(undefined);
-    const result = await noRedisBehavior.execute(new UpdateUserCommand('123', 'Alice'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('should invalidate cache on successful result', async () => {
-    const result = await behavior.execute(new UpdateUserCommand('123', 'Alice'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-    expect(redis.del).toHaveBeenCalledWith('user:123', 'users:list');
-  });
-
-  it('should skip invalidation on failure result', async () => {
-    next.mockResolvedValue(Result.failure(ErrorType.InternalError, 'something broke'));
-
-    const result = await behavior.execute(new UpdateUserCommand('123', 'Alice'), next);
-
-    expect(result.isSuccess).toBe(false);
-    expect(redis.del).not.toHaveBeenCalled();
-  });
-
-  it('should interpolate key templates with command properties', async () => {
-    const result = await behavior.execute(new UpdateUserCommand('456', 'Bob'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(redis.del).toHaveBeenCalledWith('user:456', 'users:list');
-  });
-
-  it('should return successful result even when redis.del() throws', async () => {
-    redis.del.mockRejectedValue(new Error('Connection lost'));
-
-    const result = await behavior.execute(new UpdateUserCommand('123', 'Alice'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(result.value).toEqual({ updated: true });
-  });
-
-  it('should skip redis.del() when keys array is empty', async () => {
-    const result = await behavior.execute(new EmptyKeysCommand(), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-    expect(redis.del).not.toHaveBeenCalled();
-  });
-});

package/src/cqrs/behaviors/InvalidateCacheBehavior.ts

@@ -1,50 +0,0 @@
-import { Injectable, Logger, Optional, Inject } from '@nestjs/common';
-import { getInvalidateCacheMetadata } from '../decorators/InvalidateCache.decorator';
-import { Result } from '../../result/Result';
-import { REDIS_CLIENT } from '../constants';
-import type { Redis } from 'ioredis';
-
-@Injectable()
-export class InvalidateCacheBehavior {
-  private readonly logger = new Logger(InvalidateCacheBehavior.name);
-
-  constructor(
-    @Optional() @Inject(REDIS_CLIENT) private readonly redis?: Redis,
-  ) {}
-
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    const metadata = getInvalidateCacheMetadata(command.constructor);
-
-    if (!metadata || !this.redis) {
-      return next();
-    }
-
-    const result = await next();
-
-    if (!result.isSuccess) {
-      return result;
-    }
-
-    const resolvedKeys = metadata.keys.map((key) => this.interpolateKey(key, command));
-
-    if (resolvedKeys.length === 0) {
-      return result;
-    }
-
-    try {
-      await this.redis.del(...resolvedKeys);
-      this.logger.debug(`Cache invalidated: ${resolvedKeys.join(', ')}`);
-    } catch {
-      this.logger.warn(`Cache invalidation failed for keys: ${resolvedKeys.join(', ')}`);
-    }
-
-    return result;
-  }
-
-  private interpolateKey(template: string, command: object): string {
-    return template.replace(/\{(\w+)\}/g, (_, prop) => {
-      const value = (command as Record<string, unknown>)[prop];
-      return value != null ? String(value) : '';
-    });
-  }
-}

package/src/cqrs/behaviors/LogBehavior.spec.ts

@@ -1,55 +0,0 @@
-import { LogBehavior } from './LogBehavior';
-import { Result } from '../../result/Result';
-
-describe('LogBehavior', () => {
-  let behavior: LogBehavior;
-
-  beforeEach(() => {
-    behavior = new LogBehavior();
-  });
-
-  it('should pass through successful results', async () => {
-    const next = jest.fn().mockResolvedValue(Result.success({ id: '1' }));
-    const command = new (class TestCommand { buildId = 'b1'; })();
-
-    const result = await behavior.execute(command, next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('should pass through failed results', async () => {
-    const next = jest.fn().mockResolvedValue(Result.notFound('not found'));
-
-    const result = await behavior.execute({}, next);
-
-    expect(result.isSuccess).toBe(false);
-  });
-
-  it('should catch exceptions and return Result.failure', async () => {
-    const next = jest.fn().mockRejectedValue(new Error('boom'));
-
-    const result = await behavior.execute({}, next);
-
-    expect(result.isSuccess).toBe(false);
-    expect(result.errorMessage).toBe('boom');
-  });
-
-  it('should mask PII fields in payload', async () => {
-    const next = jest.fn().mockResolvedValue(Result.success('ok'));
-    const command = {
-      email: 'john@example.com',
-      accessToken: 'secret-token',
-      brdText: 'A'.repeat(100),
-      name: 'visible',
-    };
-
-    // The behavior masks internally for logging. We verify it doesn't affect the original.
-    await behavior.execute(command, next);
-
-    // Original command should be unmodified
-    expect(command.email).toBe('john@example.com');
-    expect(command.accessToken).toBe('secret-token');
-    expect(command.brdText).toBe('A'.repeat(100));
-  });
-});

package/src/cqrs/behaviors/LogBehavior.ts

@@ -1,121 +0,0 @@
-import { Injectable, Logger } from '@nestjs/common';
-import { Result, ErrorType } from '../../result/Result';
-import { correlationStore } from '../../middleware/CorrelationStore';
-
-const PII_FIELDS = new Set(['email', 'githubAccessToken', 'accessToken', 'token', 'secretKey', 'password']);
-const MAX_STRING_LENGTH = 200;
-const MAX_ARRAY_LENGTH = 5;
-const MAX_DEPTH = 2;
-
-@Injectable()
-export class LogBehavior {
-  private readonly logger = new Logger('PipelineBehavior');
-
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    const commandName = command.constructor.name;
-    const startTime = Date.now();
-    const ctx = correlationStore.getStore();
-
-    const logContext = {
-      command: commandName,
-      correlationId: ctx?.correlationId,
-      userId: ctx?.userId,
-      orgId: ctx?.organizationId,
-      ...(this.extractBuildId(command)),
-      payload: this.maskPayload(command),
-    };
-
-    try {
-      const result = await next();
-      const durationMs = Date.now() - startTime;
-
-      if (result.isSuccess) {
-        this.logger.log({
-          msg: `${commandName} completed`,
-          ...logContext,
-          durationMs,
-          result: 'success',
-        });
-      } else {
-        this.logger.warn({
-          msg: `${commandName} completed`,
-          ...logContext,
-          durationMs,
-          result: 'failure',
-          errorType: result.errorType ?? 'Unknown',
-          errorMessage: result.errorMessage,
-        });
-      }
-
-      return result;
-    } catch (error) {
-      const durationMs = Date.now() - startTime;
-      const err = error instanceof Error ? error : new Error(String(error));
-      this.logger.error({
-        msg: `${commandName} failed`,
-        ...logContext,
-        durationMs,
-        result: 'exception',
-        error: err.message,
-        stack: err.stack,
-      });
-      return Result.failure(ErrorType.InternalError, err.message);
-    }
-  }
-
-  private maskPayload(command: object): Record<string, unknown> {
-    const excludeFields = this.getExcludeFields(command);
-    return this.sanitize(command, 0, excludeFields) as Record<string, unknown>;
-  }
-
-  private getExcludeFields(command: object): Set<string> {
-    const ctor = command.constructor as { logExclude?: string[] };
-    return new Set(ctor.logExclude ?? []);
-  }
-
-  private sanitize(value: unknown, depth: number, excludeFields?: Set<string>): unknown {
-    if (value === null || value === undefined) return value;
-
-    if (typeof value === 'string') {
-      return value.length > MAX_STRING_LENGTH
-        ? `${value.substring(0, MAX_STRING_LENGTH)}... (${value.length} chars)`
-        : value;
-    }
-
-    if (typeof value !== 'object') return value;
-
-    if (depth >= MAX_DEPTH) return '[nested]';
-
-    if (Array.isArray(value)) {
-      if (value.length > MAX_ARRAY_LENGTH) {
-        return [
-          ...value.slice(0, MAX_ARRAY_LENGTH).map((v) => this.sanitize(v, depth + 1)),
-          `... +${value.length - MAX_ARRAY_LENGTH} more`,
-        ];
-      }
-      return value.map((v) => this.sanitize(v, depth + 1));
-    }
-
-    const masked: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
-      if (excludeFields?.has(key)) {
-        masked[key] = '[excluded]';
-      } else if (PII_FIELDS.has(key)) {
-        if (key === 'email' && typeof val === 'string') {
-          const [local, domain] = val.split('@');
-          masked[key] = domain ? `${local?.[0]}***@${domain}` : '[REDACTED]';
-        } else {
-          masked[key] = '[REDACTED]';
-        }
-      } else {
-        masked[key] = this.sanitize(val, depth + 1);
-      }
-    }
-    return masked;
-  }
-
-  private extractBuildId(command: object): { buildId?: string } {
-    const buildId = (command as Record<string, unknown>)['buildId'];
-    return typeof buildId === 'string' ? { buildId } : {};
-  }
-}

package/src/cqrs/behaviors/PerformanceBehavior.spec.ts

@@ -1,48 +0,0 @@
-import { PerformanceBehavior } from './PerformanceBehavior';
-import { Result } from '../../result/Result';
-
-describe('PerformanceBehavior', () => {
-  it('should pass through results and record metrics', async () => {
-    const observe = jest.fn();
-    const metrics = {
-      handlerDuration: {
-        labels: jest.fn().mockReturnValue({ observe }),
-      },
-    };
-    const behavior = new PerformanceBehavior(metrics as any);
-    const next = jest.fn().mockResolvedValue(Result.success('ok'));
-
-    class TestCommand {}
-    const result = await behavior.execute(new TestCommand(), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(metrics.handlerDuration.labels).toHaveBeenCalledWith('TestCommand', 'success');
-    expect(observe).toHaveBeenCalled();
-  });
-
-  it('should record failure label for failed results', async () => {
-    const observe = jest.fn();
-    const metrics = {
-      handlerDuration: {
-        labels: jest.fn().mockReturnValue({ observe }),
-      },
-    };
-    const behavior = new PerformanceBehavior(metrics as any);
-    const next = jest.fn().mockResolvedValue(Result.notFound('nope'));
-
-    class FailCommand {}
-    await behavior.execute(new FailCommand(), next);
-
-    expect(metrics.handlerDuration.labels).toHaveBeenCalledWith('FailCommand', 'failure');
-  });
-
-  it('should work without metrics service', async () => {
-    const behavior = new PerformanceBehavior(undefined);
-    const next = jest.fn().mockResolvedValue(Result.success('ok'));
-
-    class NoMetrics {}
-    const result = await behavior.execute(new NoMetrics(), next);
-
-    expect(result.isSuccess).toBe(true);
-  });
-});

package/src/cqrs/behaviors/PerformanceBehavior.ts

@@ -1,43 +0,0 @@
-import { Injectable, Logger, Optional } from '@nestjs/common';
-import { Result } from '../../result/Result';
-import { MetricsService } from '../../metrics/MetricsService';
-
-const SLOW_THRESHOLD_MS = 500;
-
-/**
- * PerformanceBehavior logs a warning when a handler exceeds 500ms
- * and records handler duration in Prometheus histogram.
- */
-@Injectable()
-export class PerformanceBehavior {
-  private readonly logger = new Logger('PerformanceBehavior');
-
-  constructor(@Optional() private readonly metrics?: MetricsService) {}
-
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    const handlerName = command.constructor.name;
-    const startTime = Date.now();
-
-    const result = await next();
-
-    const durationMs = Date.now() - startTime;
-    const durationSec = durationMs / 1000;
-    const resultLabel = result.isSuccess ? 'success' : 'failure';
-
-    // Record metrics
-    this.metrics?.handlerDuration
-      .labels(handlerName, resultLabel)
-      .observe(durationSec);
-
-    // Warn on slow handlers
-    if (durationMs > SLOW_THRESHOLD_MS) {
-      this.logger.warn({
-        msg: `Slow handler detected: ${handlerName} took ${durationMs}ms`,
-        handler: handlerName,
-        durationMs,
-      });
-    }
-
-    return result;
-  }
-}

package/src/cqrs/behaviors/TransactionalBehavior.ts

@@ -1,64 +0,0 @@
-import { Injectable, Logger, Optional } from '@nestjs/common';
-import { DataSource } from 'typeorm';
-import { Result, ErrorType } from '../../result/Result';
-import { TransactionContext } from '../transaction/TransactionContext';
-import { isIsolatedTransaction } from '../decorators/IsolatedTransaction.decorator';
-
-/**
- * TransactionalBehavior — UnitOfWork pattern via AsyncLocalStorage.
- *
- * Every command is transactional by default (no decorator needed):
- * - If no ambient transaction exists → CREATE one, own commit/rollback
- * - If an ambient transaction exists → JOIN it (pass through, outer scope owns lifecycle)
- * - If command is @IsolatedTransaction() → always CREATE a new one, even if context exists
- *
- * Queries skip this behavior entirely (separate pipeline chain in QuanticQueryBus).
- */
-@Injectable()
-export class TransactionalBehavior {
-  private readonly logger = new Logger(TransactionalBehavior.name);
-
-  constructor(@Optional() private readonly dataSource?: DataSource) {}
-
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    if (!this.dataSource) {
-      return next();
-    }
-
-    const existing = TransactionContext.get();
-    const isolated = isIsolatedTransaction(command.constructor);
-
-    // JOIN — ambient transaction exists and command does not demand isolation
-    if (existing && !isolated) {
-      return next();
-    }
-
-    // CREATE — we are the outermost scope (or isolated); we own the lifecycle
-    const queryRunner = this.dataSource.createQueryRunner();
-    await queryRunner.connect();
-    await queryRunner.startTransaction();
-
-    try {
-      const result = await TransactionContext.run(queryRunner, () => next());
-
-      if (result.isSuccess) {
-        await queryRunner.commitTransaction();
-      } else {
-        await queryRunner.rollbackTransaction();
-        this.logger.warn(
-          `Transaction rolled back for ${command.constructor.name}: ${result.errorMessage}`,
-        );
-      }
-
-      return result;
-    } catch (error) {
-      await queryRunner.rollbackTransaction();
-      return Result.failure<T>(
-        ErrorType.InternalError,
-        `Transaction failed for ${command.constructor.name}: ${(error as Error).message}`,
-      );
-    } finally {
-      await queryRunner.release();
-    }
-  }
-}