@quanticjs/core 1.1.1 → 2.0.0

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

@@ -1,114 +0,0 @@
-import { z } from 'zod';
-import { ValidationBehavior } from './ValidationBehavior';
-import { Result, ErrorType } from '../../result/Result';
-import { Validate } from '../decorators/Validate.decorator';
-import { ICommandValidator, validateCommand } from '../validation/ICommandValidator';
-
-// --- Validator classes ---
-
-class BlockUserValidator implements ICommandValidator<BlockUserCommand> {
-  private schema = z
-    .object({
-      blockerId: z.string().min(1, 'blockerId is required'),
-      blockedUserId: z.string().min(1, 'blockedUserId is required'),
-    })
-    .refine((d) => d.blockerId !== d.blockedUserId, {
-      message: 'Cannot block yourself',
-    });
-
-  validate(command: BlockUserCommand): Result<void> {
-    return validateCommand(this.schema, command);
-  }
-}
-
-class NameValidator implements ICommandValidator<ValidatedCommand> {
-  private schema = z.object({
-    name: z.string().min(5, 'Name must be at least 5 characters'),
-  });
-
-  validate(command: ValidatedCommand): Result<void> {
-    return validateCommand(this.schema, command);
-  }
-}
-
-// --- Commands ---
-
-@Validate(NameValidator)
-class ValidatedCommand {
-  name: string;
-  constructor(name: string) {
-    this.name = name;
-  }
-}
-
-@Validate(BlockUserValidator)
-class BlockUserCommand {
-  constructor(
-    public readonly blockerId: string,
-    public readonly blockedUserId: string,
-  ) {}
-}
-
-class UnvalidatedCommand {
-  name: string;
-  constructor(name: string) {
-    this.name = name;
-  }
-}
-
-describe('ValidationBehavior', () => {
-  let behavior: ValidationBehavior;
-  const next = jest.fn().mockResolvedValue(Result.success('ok'));
-
-  beforeEach(() => {
-    behavior = new ValidationBehavior();
-    next.mockClear();
-  });
-
-  it('should pass through when command has no @Validate decorator', async () => {
-    const result = await behavior.execute(new UnvalidatedCommand('hi'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('should pass through when validation succeeds', async () => {
-    const result = await behavior.execute(new ValidatedCommand('hello'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('should return validation error when validation fails', async () => {
-    const result = await behavior.execute(new ValidatedCommand('hi'), next);
-
-    expect(result.isSuccess).toBe(false);
-    expect(result.errorType).toBe(ErrorType.ValidationError);
-    expect(result.errorMessage).toContain('at least 5 characters');
-    expect(next).not.toHaveBeenCalled();
-  });
-
-  it('should support conditional validation with refine', async () => {
-    const result = await behavior.execute(new BlockUserCommand('user-1', 'user-1'), next);
-
-    expect(result.isSuccess).toBe(false);
-    expect(result.errorType).toBe(ErrorType.ValidationError);
-    expect(result.errorMessage).toContain('Cannot block yourself');
-    expect(next).not.toHaveBeenCalled();
-  });
-
-  it('should pass valid block user command', async () => {
-    const result = await behavior.execute(new BlockUserCommand('user-1', 'user-2'), next);
-
-    expect(result.isSuccess).toBe(true);
-    expect(next).toHaveBeenCalledTimes(1);
-  });
-
-  it('should report missing required fields', async () => {
-    const result = await behavior.execute(new BlockUserCommand('', 'user-2'), next);
-
-    expect(result.isSuccess).toBe(false);
-    expect(result.errorMessage).toContain('blockerId');
-    expect(next).not.toHaveBeenCalled();
-  });
-});

package/src/cqrs/behaviors/ValidationBehavior.ts

@@ -1,29 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { shouldValidate, getValidatorClass } from '../decorators/Validate.decorator';
-import { Result, ErrorType } from '../../result/Result';
-
-@Injectable()
-export class ValidationBehavior {
-  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
-    if (!shouldValidate(command.constructor)) {
-      return next();
-    }
-
-    const ValidatorClass = getValidatorClass(command.constructor);
-    if (!ValidatorClass) {
-      return next();
-    }
-
-    const validator = new ValidatorClass();
-    const validationResult = validator.validate(command);
-
-    if (!validationResult.isSuccess) {
-      return Result.failure<T>(
-        validationResult.errorType ?? ErrorType.ValidationError,
-        validationResult.errorMessage ?? 'Validation failed',
-      );
-    }
-
-    return next();
-  }
-}

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

@@ -1,97 +0,0 @@
-import { WorkflowBehavior } from './WorkflowBehavior';
-import { Workflow } from '../decorators/Workflow.decorator';
-import { Result } from '../../result/Result';
-import { WorkflowEngine, WorkflowStartResult } from '../interfaces/WorkflowEngine';
-
-const mockEngine: jest.Mocked<WorkflowEngine> = {
-  startProcess: jest.fn(),
-  signalProcess: jest.fn(),
-  abortProcess: jest.fn(),
-};
-
-@Workflow('onboarding-process')
-class DecoratedCommand {
-  constructor(public readonly userId: string) {}
-}
-
-@Workflow('guarded-process', { fallback: 'skip' })
-class SkipFallbackCommand {
-  constructor(public readonly id: string) {}
-}
-
-class PlainCommand {
-  constructor(public readonly id: string) {}
-}
-
-describe('WorkflowBehavior', () => {
-  let behavior: WorkflowBehavior;
-  let next: jest.Mock;
-
-  beforeEach(() => {
-    jest.clearAllMocks();
-    behavior = new WorkflowBehavior(mockEngine);
-    next = jest.fn().mockResolvedValue(Result.success({ done: true }));
-  });
-
-  it('passes through commands without @Workflow decorator', async () => {
-    const cmd = new PlainCommand('123');
-    const result = await behavior.execute(cmd, next);
-
-    expect(next).toHaveBeenCalled();
-    expect(result.isSuccess).toBe(true);
-    expect(mockEngine.startProcess).not.toHaveBeenCalled();
-  });
-
-  it('short-circuits decorated commands and starts a process', async () => {
-    const startResult: WorkflowStartResult = {
-      workflowInstanceId: 'wf-1',
-      processInstanceId: 'pi-1',
-      status: 'STARTED',
-    };
-    mockEngine.startProcess.mockResolvedValue(startResult);
-
-    const cmd = new DecoratedCommand('user-42');
-    const result = await behavior.execute(cmd, next);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(mockEngine.startProcess).toHaveBeenCalledWith(
-      'onboarding-process',
-      cmd,
-      { commandType: 'DecoratedCommand' },
-    );
-    expect(result.isSuccess).toBe(true);
-    expect(result.value).toEqual(startResult);
-  });
-
-  it('passes through when no WorkflowEngine is injected', async () => {
-    const behaviorNoEngine = new WorkflowBehavior(undefined);
-    const cmd = new DecoratedCommand('user-42');
-
-    const result = await behaviorNoEngine.execute(cmd, next);
-
-    expect(next).toHaveBeenCalled();
-    expect(result.isSuccess).toBe(true);
-  });
-
-  it('applies fallback throw on engine error', async () => {
-    mockEngine.startProcess.mockRejectedValue(new Error('connection refused'));
-
-    const cmd = new DecoratedCommand('user-42');
-    const result = await behavior.execute(cmd, next);
-
-    expect(next).not.toHaveBeenCalled();
-    expect(result.isSuccess).toBe(false);
-    expect(result.errorMessage).toContain('Workflow start failed');
-    expect(result.errorMessage).toContain('connection refused');
-  });
-
-  it('applies fallback skip on engine error (calls next)', async () => {
-    mockEngine.startProcess.mockRejectedValue(new Error('timeout'));
-
-    const cmd = new SkipFallbackCommand('123');
-    const result = await behavior.execute(cmd, next);
-
-    expect(next).toHaveBeenCalled();
-    expect(result.isSuccess).toBe(true);
-  });
-});

package/src/cqrs/behaviors/WorkflowBehavior.ts

@@ -1,62 +0,0 @@
-import { Injectable, Optional, Inject, Logger } from '@nestjs/common';
-import { getWorkflowMetadata } from '../decorators/Workflow.decorator';
-import { WORKFLOW_ENGINE, WorkflowEngine } from '../interfaces/WorkflowEngine';
-import { Result, ErrorType } from '../../result/Result';
-
-@Injectable()
-export class WorkflowBehavior {
-  private readonly logger = new Logger(WorkflowBehavior.name);
-
-  constructor(
-    @Optional() @Inject(WORKFLOW_ENGINE)
-    private readonly engine?: WorkflowEngine,
-  ) {}
-
-  async execute<T>(
-    command: object,
-    next: () => Promise<Result<T>>,
-  ): Promise<Result<T>> {
-    const metadata = getWorkflowMetadata(command.constructor);
-
-    if (!metadata) {
-      return next();
-    }
-
-    if (!this.engine) {
-      this.logger.debug('No WorkflowEngine provided, skipping workflow behavior');
-      return next();
-    }
-
-    try {
-      const result = await this.engine.startProcess(
-        metadata.processDefinitionId,
-        command,
-        { commandType: command.constructor.name },
-      );
-      return Result.success(result as unknown as T);
-    } catch (error: any) {
-      const fallback = metadata.fallback ?? 'throw';
-
-      this.logger.warn(
-        `Workflow start failed for "${metadata.processDefinitionId}", applying fallback: ${fallback}`,
-        error.message,
-      );
-
-      switch (fallback) {
-        case 'skip':
-          return next();
-        case 'queue':
-          return Result.failure<T>(
-            ErrorType.InternalError,
-            `Workflow queuing not available without companion package: ${error.message}`,
-          );
-        case 'throw':
-        default:
-          return Result.failure<T>(
-            ErrorType.InternalError,
-            `Workflow start failed: ${error.message}`,
-          );
-      }
-    }
-  }
-}

package/src/cqrs/constants.ts

@@ -1,2 +0,0 @@
-/** Injection token for the Redis client (ioredis) */
-export const REDIS_CLIENT = 'REDIS_CLIENT';

package/src/cqrs/decorators/Cache.decorator.ts

@@ -1,24 +0,0 @@
-import 'reflect-metadata';
-
-const CACHE_KEY = 'arex:cache';
-
-export interface CacheOptions {
-  /** Cache key template — use {propName} for interpolation, e.g. 'user:{id}' */
-  key: string;
-  /** TTL in seconds (default: 60) */
-  ttlSeconds?: number;
-}
-
-/**
- * @Cache('key:{prop}', { ttlSeconds: 60 }) — caches query results in Redis.
- * Reads from cache on hit; sets on miss with TTL.
- */
-export function Cache(key: string, options: Omit<CacheOptions, 'key'> = {}): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(CACHE_KEY, { key, ttlSeconds: 60, ...options }, target);
-  };
-}
-
-export function getCacheMetadata(target: object): CacheOptions | undefined {
-  return Reflect.getMetadata(CACHE_KEY, target);
-}

package/src/cqrs/decorators/DistributedLock.decorator.ts

@@ -1,34 +0,0 @@
-import 'reflect-metadata';
-
-const LOCK_KEY = 'arex:distributed-lock';
-
-export interface DistributedLockOptions {
-  /** Lock key template — use {propName} for interpolation */
-  key: string;
-  /** Max time to wait for lock acquisition in seconds (default: 5) */
-  acquireTimeoutSeconds?: number;
-  /** Lock auto-release time in seconds (default: 30) */
-  lockTtlSeconds?: number;
-}
-
-/**
- * @DistributedLock('key:{prop}') — acquires a Redis distributed lock before execution.
- * Throws ConflictException on timeout.
- */
-export function DistributedLock(
-  key: string,
-  options: Omit<DistributedLockOptions, 'key'> = {},
-): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(LOCK_KEY, {
-      key,
-      acquireTimeoutSeconds: 5,
-      lockTtlSeconds: 30,
-      ...options,
-    }, target);
-  };
-}
-
-export function getDistributedLockMetadata(target: object): DistributedLockOptions | undefined {
-  return Reflect.getMetadata(LOCK_KEY, target);
-}

package/src/cqrs/decorators/FeatureFlag.decorator.ts

@@ -1,23 +0,0 @@
-import 'reflect-metadata';
-
-const FEATURE_FLAG_KEY = 'arex:feature-flag';
-
-export interface FeatureFlagOptions {
-  fallback?: 'throw' | 'skip' | 'default';
-  defaultValue?: unknown;
-}
-
-export function FeatureFlag(
-  flagName: string,
-  options: FeatureFlagOptions = { fallback: 'throw' },
-): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(FEATURE_FLAG_KEY, { flagName, ...options }, target);
-  };
-}
-
-export function getFeatureFlagMetadata(
-  target: object,
-): { flagName: string } & FeatureFlagOptions | undefined {
-  return Reflect.getMetadata(FEATURE_FLAG_KEY, target);
-}

package/src/cqrs/decorators/InvalidateCache.decorator.spec.ts

@@ -1,20 +0,0 @@
-import { InvalidateCache, getInvalidateCacheMetadata } from './InvalidateCache.decorator';
-
-@InvalidateCache(['user:{userId}', 'users:list'])
-class DecoratedCommand {}
-
-class PlainCommand {}
-
-describe('InvalidateCache decorator', () => {
-  it('should store metadata on decorated class', () => {
-    const metadata = getInvalidateCacheMetadata(DecoratedCommand);
-
-    expect(metadata).toEqual({ keys: ['user:{userId}', 'users:list'] });
-  });
-
-  it('should return undefined for undecorated class', () => {
-    const metadata = getInvalidateCacheMetadata(PlainCommand);
-
-    expect(metadata).toBeUndefined();
-  });
-});

package/src/cqrs/decorators/InvalidateCache.decorator.ts

@@ -1,17 +0,0 @@
-import 'reflect-metadata';
-
-const INVALIDATE_CACHE_KEY = 'arex:invalidate-cache';
-
-export interface InvalidateCacheOptions {
-  keys: string[];
-}
-
-export function InvalidateCache(keys: string[]): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(INVALIDATE_CACHE_KEY, { keys }, target);
-  };
-}
-
-export function getInvalidateCacheMetadata(target: object): InvalidateCacheOptions | undefined {
-  return Reflect.getMetadata(INVALIDATE_CACHE_KEY, target);
-}

package/src/cqrs/decorators/IsolatedTransaction.decorator.ts

@@ -1,24 +0,0 @@
-import 'reflect-metadata';
-
-const ISOLATED_TRANSACTION_KEY = 'arex:isolated-transaction';
-
-/**
- * @IsolatedTransaction() — forces a command to run in its own dedicated transaction,
- * even when an outer transaction scope already exists.
- *
- * Use for operations that must commit independently of the parent flow:
- * - Audit logging (must persist even if the business operation rolls back)
- * - Notifications / side-effects that should not be lost on rollback
- *
- * By default all commands share the ambient transaction (UnitOfWork pattern).
- * This decorator opts out of that behavior.
- */
-export function IsolatedTransaction(): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(ISOLATED_TRANSACTION_KEY, true, target);
-  };
-}
-
-export function isIsolatedTransaction(target: object): boolean {
-  return Reflect.getMetadata(ISOLATED_TRANSACTION_KEY, target) === true;
-}

package/src/cqrs/decorators/Log.decorator.ts

@@ -1,22 +0,0 @@
-import 'reflect-metadata';
-
-const LOG_KEY = 'arex:log';
-
-export interface LogOptions {
-  /** Whether to log the command/query payload (default: true) */
-  logPayload?: boolean;
-}
-
-/**
- * @Log() — marks a command/query for automatic entry/exit logging.
- * Applied globally by QuanticCommandBus/QuanticQueryBus when no explicit decorator is present.
- */
-export function Log(options: LogOptions = {}): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(LOG_KEY, { logPayload: true, ...options }, target);
-  };
-}
-
-export function getLogMetadata(target: object): LogOptions | undefined {
-  return Reflect.getMetadata(LOG_KEY, target);
-}

package/src/cqrs/decorators/Validate.decorator.ts

@@ -1,39 +0,0 @@
-import 'reflect-metadata';
-import type { ICommandValidator } from '../validation/ICommandValidator';
-
-const VALIDATE_KEY = 'arex:validate';
-const VALIDATOR_CLASS_KEY = 'arex:validator-class';
-
-type ValidatorClass = new () => ICommandValidator;
-
-/**
- * @Validate(ValidatorClass) — links a command/query to its Zod-based validator.
- *
- * The ValidationBehavior instantiates the validator and calls validate()
- * before the handler runs. Returns Result.validationError() on failure.
- *
- * Usage:
- * ```typescript
- * @Validate(BlockUserValidator)
- * export class BlockUserCommand {
- *   constructor(
- *     public readonly blockerId: string,
- *     public readonly blockedUserId: string,
- *   ) {}
- * }
- * ```
- */
-export function Validate(validatorClass: ValidatorClass): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(VALIDATE_KEY, true, target);
-    Reflect.defineMetadata(VALIDATOR_CLASS_KEY, validatorClass, target);
-  };
-}
-
-export function shouldValidate(target: object): boolean {
-  return Reflect.getMetadata(VALIDATE_KEY, target) === true;
-}
-
-export function getValidatorClass(target: object): ValidatorClass | undefined {
-  return Reflect.getMetadata(VALIDATOR_CLASS_KEY, target);
-}

package/src/cqrs/decorators/Workflow.decorator.ts

@@ -1,22 +0,0 @@
-import 'reflect-metadata';
-
-const WORKFLOW_KEY = 'arex:workflow';
-
-export interface WorkflowOptions {
-  fallback?: 'throw' | 'skip' | 'queue';
-}
-
-export function Workflow(
-  processDefinitionId: string,
-  options?: WorkflowOptions,
-): ClassDecorator {
-  return (target: object) => {
-    Reflect.defineMetadata(WORKFLOW_KEY, { processDefinitionId, ...options }, target);
-  };
-}
-
-export function getWorkflowMetadata(
-  target: object,
-): { processDefinitionId: string } & WorkflowOptions | undefined {
-  return Reflect.getMetadata(WORKFLOW_KEY, target);
-}

package/src/cqrs/interfaces/WorkflowEngine.ts

@@ -1,19 +0,0 @@
-export const WORKFLOW_ENGINE = Symbol('WORKFLOW_ENGINE');
-
-export interface WorkflowStartResult {
-  workflowInstanceId: string;
-  processInstanceId: string;
-  status: 'STARTED';
-}
-
-export interface WorkflowEngine {
-  startProcess(
-    processDefinitionId: string,
-    command: object,
-    metadata: { commandType: string; correlationId?: string },
-  ): Promise<WorkflowStartResult>;
-
-  signalProcess(processInstanceId: string, signal: string, data?: unknown): Promise<void>;
-
-  abortProcess(processInstanceId: string): Promise<void>;
-}

package/src/cqrs/pipeline/QuanticCommandBus.ts

@@ -1,69 +0,0 @@
-import { Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
-import { CommandBus } from '@nestjs/cqrs';
-import { Result } from '../../result/Result';
-import { LogBehavior } from '../behaviors/LogBehavior';
-import { FeatureFlagBehavior } from '../behaviors/FeatureFlagBehavior';
-import { ValidationBehavior } from '../behaviors/ValidationBehavior';
-import { CacheBehavior } from '../behaviors/CacheBehavior';
-import { DistributedLockBehavior } from '../behaviors/DistributedLockBehavior';
-import { TransactionalBehavior } from '../behaviors/TransactionalBehavior';
-import { PerformanceBehavior } from '../behaviors/PerformanceBehavior';
-import { WorkflowBehavior } from '../behaviors/WorkflowBehavior';
-import { InvalidateCacheBehavior } from '../behaviors/InvalidateCacheBehavior';
-import { BehaviorFn, runPipeline } from './runPipeline';
-
-/**
- * QuanticCommandBus — wraps the @nestjs/cqrs CommandBus with a behavior pipeline.
- *
- * Pipeline order:
- *   InvalidateCache → Log → Performance → FeatureFlag → Validate → Workflow → Cache → DistributedLock → Transactional → Handler
- *
- * Controllers inject the standard CommandBus from @nestjs/cqrs.
- * This class patches its execute() in onModuleInit so the pipeline is transparent.
- */
-@Injectable()
-export class QuanticCommandBus implements OnModuleInit {
-  private readonly logger = new Logger(QuanticCommandBus.name);
-  private behaviors: BehaviorFn[] = [];
-  private originalExecute!: CommandBus['execute'];
-
-  constructor(
-    private readonly commandBus: CommandBus,
-    private readonly logBehavior: LogBehavior,
-    private readonly performanceBehavior: PerformanceBehavior,
-    @Optional() @Inject(FeatureFlagBehavior) private readonly featureFlagBehavior: FeatureFlagBehavior | undefined,
-    private readonly validationBehavior: ValidationBehavior,
-    @Optional() @Inject(WorkflowBehavior) private readonly workflowBehavior: WorkflowBehavior | undefined,
-    private readonly cacheBehavior: CacheBehavior,
-    private readonly distributedLockBehavior: DistributedLockBehavior,
-    private readonly transactionalBehavior: TransactionalBehavior,
-    private readonly invalidateCacheBehavior: InvalidateCacheBehavior,
-  ) {}
-
-  onModuleInit() {
-    const optional = (behavior: { execute: BehaviorFn } | undefined): BehaviorFn[] =>
-      behavior ? [(cmd, next) => behavior.execute(cmd, next)] : [];
-
-    this.behaviors = [
-      (cmd, next) => this.invalidateCacheBehavior.execute(cmd, next),
-      (cmd, next) => this.logBehavior.execute(cmd, next),
-      (cmd, next) => this.performanceBehavior.execute(cmd, next),
-      ...optional(this.featureFlagBehavior),
-      (cmd, next) => this.validationBehavior.execute(cmd, next),
-      ...optional(this.workflowBehavior),
-      (cmd, next) => this.cacheBehavior.execute(cmd, next),
-      (cmd, next) => this.distributedLockBehavior.execute(cmd, next),
-      (cmd, next) => this.transactionalBehavior.execute(cmd, next),
-    ];
-
-    this.originalExecute = this.commandBus.execute.bind(this.commandBus);
-
-    const self = this;
-    this.commandBus.execute = <T>(command: object): Promise<T> => {
-      const handler = () => self.originalExecute(command) as Promise<Result<T>>;
-      return runPipeline(command, handler, self.behaviors) as Promise<T>;
-    };
-
-    this.logger.log(`Command pipeline initialized — ${this.behaviors.length} behaviors`);
-  }
-}