@quanticjs/core 1.1.1 → 2.1.0

package/src/cqrs/pipeline/QuanticQueryBus.ts

@@ -1,56 +0,0 @@
-import { Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
-import { QueryBus } 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 { PerformanceBehavior } from '../behaviors/PerformanceBehavior';
-import { BehaviorFn, runPipeline } from './runPipeline';
-
-/**
- * QuanticQueryBus — wraps the @nestjs/cqrs QueryBus with a behavior pipeline.
- *
- * Pipeline order:
- *   Log → Performance → FeatureFlag → Validate → Cache → Handler
- *
- * Queries skip Workflow, DistributedLock, and Transactional — they are read-only.
- */
-@Injectable()
-export class QuanticQueryBus implements OnModuleInit {
-  private readonly logger = new Logger(QuanticQueryBus.name);
-  private behaviors: BehaviorFn[] = [];
-  private originalExecute!: QueryBus['execute'];
-
-  constructor(
-    private readonly queryBus: QueryBus,
-    private readonly logBehavior: LogBehavior,
-    private readonly performanceBehavior: PerformanceBehavior,
-    @Optional() @Inject(FeatureFlagBehavior) private readonly featureFlagBehavior: FeatureFlagBehavior | undefined,
-    private readonly validationBehavior: ValidationBehavior,
-    private readonly cacheBehavior: CacheBehavior,
-  ) {}
-
-  onModuleInit() {
-    const optional = (behavior: { execute: BehaviorFn } | undefined): BehaviorFn[] =>
-      behavior ? [(cmd, next) => behavior.execute(cmd, next)] : [];
-
-    this.behaviors = [
-      (cmd, next) => this.logBehavior.execute(cmd, next),
-      (cmd, next) => this.performanceBehavior.execute(cmd, next),
-      ...optional(this.featureFlagBehavior),
-      (cmd, next) => this.validationBehavior.execute(cmd, next),
-      (cmd, next) => this.cacheBehavior.execute(cmd, next),
-    ];
-
-    this.originalExecute = this.queryBus.execute.bind(this.queryBus);
-
-    const self = this;
-    this.queryBus.execute = <T>(query: object): Promise<T> => {
-      const handler = () => self.originalExecute(query) as Promise<Result<T>>;
-      return runPipeline(query, handler, self.behaviors) as Promise<T>;
-    };
-
-    this.logger.log(`Query pipeline initialized — ${this.behaviors.length} behaviors`);
-  }
-}

package/src/cqrs/pipeline/runPipeline.ts

@@ -1,22 +0,0 @@
-import { Result } from '../../result/Result';
-
-export type BehaviorFn = <T>(
-  command: object,
-  next: () => Promise<Result<T>>,
-) => Promise<Result<T>>;
-
-export function runPipeline<T>(
-  command: object,
-  handler: () => Promise<Result<T>>,
-  behaviors: BehaviorFn[],
-): Promise<Result<T>> {
-  let next = handler;
-
-  for (let i = behaviors.length - 1; i >= 0; i--) {
-    const behavior = behaviors[i]!;
-    const currentNext = next;
-    next = () => behavior(command, currentNext);
-  }
-
-  return next();
-}

package/src/cqrs/transaction/TransactionContext.ts

@@ -1,26 +0,0 @@
-import { AsyncLocalStorage } from 'async_hooks';
-import type { QueryRunner } from 'typeorm';
-
-/**
- * Ambient transaction context using AsyncLocalStorage.
- *
- * Node.js is single-threaded — each async chain (HTTP request, Bull job,
- * event consumer) gets its own isolated storage. Two concurrent requests
- * never share a QueryRunner.
- *
- * The TransactionalBehavior creates the context for the outermost command;
- * nested commands join automatically.
- */
-export class TransactionContext {
-  private static readonly storage = new AsyncLocalStorage<QueryRunner>();
-
-  /** Returns the active QueryRunner for this async scope, or undefined. */
-  static get(): QueryRunner | undefined {
-    return this.storage.getStore();
-  }
-
-  /** Runs `fn` with `queryRunner` as the ambient transaction for all nested calls. */
-  static run<T>(queryRunner: QueryRunner, fn: () => Promise<T>): Promise<T> {
-    return this.storage.run(queryRunner, fn);
-  }
-}

package/src/cqrs/transaction/getTransactionalRepo.ts

@@ -1,23 +0,0 @@
-import type { Repository, ObjectLiteral, EntityTarget } from 'typeorm';
-import { TransactionContext } from './TransactionContext';
-
-/**
- * Returns a repository bound to the ambient transaction's QueryRunner,
- * or the original repository if no transaction context exists.
- *
- * Usage in command handlers:
- * ```typescript
- * async execute(cmd: CreateUserCommand): Promise<Result<UserDto>> {
- *   const repo = getTransactionalRepo(this.userRepo);
- *   const user = repo.create({ email: cmd.email });
- *   await repo.save(user);
- *   return Result.success(toDto(user));
- * }
- * ```
- */
-export function getTransactionalRepo<T extends ObjectLiteral>(
-  repo: Repository<T>,
-): Repository<T> {
-  const qr = TransactionContext.get();
-  return qr ? qr.manager.getRepository(repo.target as EntityTarget<T>) : repo;
-}

package/src/cqrs/validation/ICommandValidator.ts

@@ -1,55 +0,0 @@
-import { Result } from '../../result/Result';
-
-/**
- * Interface for Zod-based command/query validators.
- *
- * Each command that needs validation gets a separate validator class
- * with a Zod schema. The `@Validate(ValidatorClass)` decorator links
- * the command to its validator.
- *
- * Usage:
- * ```typescript
- * export class BlockUserValidator implements ICommandValidator<BlockUserCommand> {
- *   schema = z.object({
- *     blockerId: z.string().uuid(),
- *     blockedUserId: z.string().uuid(),
- *   }).refine(d => d.blockerId !== d.blockedUserId, 'Cannot block yourself');
- *
- *   validate(command: BlockUserCommand): Result<void> {
- *     return validateCommand(this.schema, command);
- *   }
- * }
- * ```
- */
-export interface ICommandValidator<T = any> {
-  validate(command: T): Result<void>;
-}
-
-/**
- * A schema that can safeParse — matches Zod's ZodType without importing it.
- * This avoids Zod v3/v4 compatibility issues across packages.
- */
-interface SafeParseable {
-  safeParse(data: unknown): { success: true } | { success: false; error: { issues: Array<{ path: PropertyKey[]; message: string }> } };
-}
-
-/**
- * Helper: run a Zod schema against a command and return Result<void>.
- * Formats all Zod issues into a single error message.
- */
-export function validateCommand(schema: SafeParseable, command: unknown): Result<void> {
-  const result = schema.safeParse(command);
-
-  if (result.success) {
-    return Result.success(undefined);
-  }
-
-  const messages = result.error.issues
-    .map((issue) => {
-      const path = issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ` : '';
-      return `${path}${issue.message}`;
-    })
-    .join('; ');
-
-  return Result.validationError(messages);
-}

package/src/entities/BaseEntity.ts

@@ -1,16 +0,0 @@
-import {
-  PrimaryGeneratedColumn,
-  CreateDateColumn,
-  UpdateDateColumn,
-} from 'typeorm';
-
-export abstract class BaseEntity {
-  @PrimaryGeneratedColumn('uuid')
-  id!: string;
-
-  @CreateDateColumn({ type: 'timestamptz' })
-  createdAt!: Date;
-
-  @UpdateDateColumn({ type: 'timestamptz' })
-  updatedAt!: Date;
-}

package/src/entities/TenantBaseEntity.ts

@@ -1,7 +0,0 @@
-import { Column } from 'typeorm';
-import { BaseEntity } from './BaseEntity';
-
-export abstract class TenantBaseEntity extends BaseEntity {
-  @Column({ type: 'uuid' })
-  organizationId!: string;
-}

package/src/events/DomainEvent.ts

@@ -1,27 +0,0 @@
-import { v4 as uuidv4 } from 'uuid';
-
-export interface DomainEventPayload {
-  [key: string]: unknown;
-}
-
-export class DomainEvent {
-  public readonly eventId: string;
-  public readonly occurredAt: Date;
-
-  constructor(
-    public readonly eventType: string,
-    public readonly aggregateId: string,
-    public readonly payload: DomainEventPayload,
-    public readonly organizationId?: string,
-  ) {
-    this.eventId = uuidv4();
-    this.occurredAt = new Date();
-  }
-
-  /** The Redis Stream key this event should be published to */
-  get streamKey(): string {
-    // e.g. 'build.completed' → 'arex:events:builds'
-    const category = this.eventType.split('.')[0];
-    return `arex:events:${category}s`;
-  }
-}

package/src/events/OutboxEvent.entity.ts

@@ -1,56 +0,0 @@
-import {
-  Column,
-  CreateDateColumn,
-  Entity,
-  Index,
-  PrimaryGeneratedColumn,
-} from 'typeorm';
-
-export enum OutboxEventStatus {
-  Pending = 'Pending',
-  Published = 'Published',
-  Failed = 'Failed',
-}
-
-@Entity('outbox_events')
-@Index('idx_outbox_pending', ['status', 'createdAt'], {
-  where: `"status" = 'Pending'`,
-})
-export class OutboxEvent {
-  @PrimaryGeneratedColumn('uuid')
-  id!: string;
-
-  @Column({ type: 'varchar' })
-  eventType!: string;
-
-  @Column({ type: 'varchar' })
-  aggregateId!: string;
-
-  @Column({ type: 'varchar' })
-  streamKey!: string;
-
-  @Column({ type: 'jsonb' })
-  payload!: Record<string, unknown>;
-
-  @Column({ type: 'uuid', nullable: true })
-  organizationId!: string | null;
-
-  @Column({
-    type: 'enum',
-    enum: OutboxEventStatus,
-    default: OutboxEventStatus.Pending,
-  })
-  status!: OutboxEventStatus;
-
-  @Column({ type: 'int', default: 0 })
-  publishAttempts!: number;
-
-  @Column({ type: 'varchar', nullable: true })
-  lastError!: string | null;
-
-  @CreateDateColumn({ type: 'timestamptz' })
-  createdAt!: Date;
-
-  @Column({ type: 'timestamptz', nullable: true })
-  publishedAt!: Date | null;
-}

package/src/events/OutboxPublisherService.ts

@@ -1,94 +0,0 @@
-import { Injectable, Logger, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
-import { DataSource } from 'typeorm';
-import { OutboxEvent, OutboxEventStatus } from './OutboxEvent.entity';
-import { RedisStreamPublisher } from './RedisStreamPublisher';
-
-const POLL_INTERVAL_MS = 100;
-const BATCH_SIZE = 50;
-const MAX_PUBLISH_ATTEMPTS = 5;
-const DLQ_STREAM = 'arex:events:dlq';
-
-@Injectable()
-export class OutboxPublisherService implements OnModuleInit, OnModuleDestroy {
-  private readonly logger = new Logger(OutboxPublisherService.name);
-  private timer: ReturnType<typeof setInterval> | null = null;
-  private processing = false;
-
-  constructor(
-    private readonly dataSource: DataSource,
-    private readonly redisPublisher: RedisStreamPublisher,
-  ) {}
-
-  onModuleInit() {
-    this.timer = setInterval(() => this.pollAndPublish(), POLL_INTERVAL_MS);
-    this.logger.log(`Outbox publisher started (${POLL_INTERVAL_MS}ms poll interval)`);
-  }
-
-  onModuleDestroy() {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-    this.logger.log('Outbox publisher stopped');
-  }
-
-  private async pollAndPublish(): Promise<void> {
-    if (this.processing) return;
-    this.processing = true;
-
-    try {
-      const repo = this.dataSource.getRepository(OutboxEvent);
-
-      const events = await repo.find({
-        where: { status: OutboxEventStatus.Pending },
-        order: { createdAt: 'ASC' },
-        take: BATCH_SIZE,
-      });
-
-      for (const event of events) {
-        try {
-          await this.redisPublisher.publishToStream(event.streamKey, {
-            eventId: event.id,
-            eventType: event.eventType,
-            aggregateId: event.aggregateId,
-            organizationId: event.organizationId || '',
-            payload: JSON.stringify(event.payload),
-            occurredAt: event.createdAt.toISOString(),
-          });
-
-          event.status = OutboxEventStatus.Published;
-          event.publishedAt = new Date();
-          await repo.save(event);
-        } catch (error) {
-          event.publishAttempts += 1;
-          event.lastError = (error as Error).message;
-
-          if (event.publishAttempts >= MAX_PUBLISH_ATTEMPTS) {
-            event.status = OutboxEventStatus.Failed;
-            this.logger.error(
-              `Event ${event.id} exceeded max attempts, routing to DLQ`,
-            );
-
-            try {
-              await this.redisPublisher.publishToStream(DLQ_STREAM, {
-                eventId: event.id,
-                eventType: event.eventType,
-                aggregateId: event.aggregateId,
-                error: event.lastError || 'unknown',
-                payload: JSON.stringify(event.payload),
-              });
-            } catch {
-              this.logger.error(`Failed to route event ${event.id} to DLQ`);
-            }
-          }
-
-          await repo.save(event);
-        }
-      }
-    } catch (error) {
-      this.logger.error('Outbox poll cycle failed', (error as Error).stack);
-    } finally {
-      this.processing = false;
-    }
-  }
-}

package/src/events/RedisStreamConsumer.ts

@@ -1,172 +0,0 @@
-import { Logger, Inject, Optional, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
-import { REDIS_CLIENT } from '../cqrs/constants';
-import type { Redis } from 'ioredis';
-
-/**
- * Abstract base class for Redis Stream consumer groups.
- *
- * Subclasses declare `streamKey`, `consumerGroup`, `consumerName`
- * and implement `handleMessage(fields)`.
- *
- * Lifecycle:
- *  - OnModuleInit: creates consumer group (idempotent), starts read loop
- *  - OnModuleDestroy: stops the read loop gracefully, disconnects dedicated client
- *
- * Connection strategy:
- *  - Shared REDIS_CLIENT: used for non-blocking ops (XGROUP CREATE, XACK)
- *  - Dedicated cloned connection: used ONLY for blocking XREADGROUP BLOCK calls
- *  - This prevents blocking consumers from starving non-blocking callers
- *    (cache, distributed locks, publishers) that share the main REDIS_CLIENT.
- *
- * Features:
- *  - Auto-creates consumer group via XGROUP CREATE ... MKSTREAM
- *  - Recovers pending (unacked) messages on startup before reading new ones
- *  - XREADGROUP BLOCK for efficient new-message polling (on dedicated connection)
- *  - XACK after successful processing (on shared connection)
- *  - Graceful shutdown (finishes in-flight message, disconnects dedicated client)
- */
-export abstract class RedisStreamConsumer implements OnModuleInit, OnModuleDestroy {
-  protected readonly logger = new Logger(this.constructor.name);
-
-  abstract readonly streamKey: string;
-  abstract readonly consumerGroup: string;
-  abstract readonly consumerName: string;
-
-  /** Override to filter by eventType. Return true to process. Default: all messages. */
-  protected shouldHandle(_fields: Record<string, string>): boolean {
-    return true;
-  }
-
-  abstract handleMessage(fields: Record<string, string>): Promise<void>;
-
-  private running = false;
-
-  /** Dedicated connection for blocking XREADGROUP — cloned from shared client on init */
-  private blockingClient?: Redis;
-
-  constructor(
-    @Optional() @Inject(REDIS_CLIENT) protected readonly redis?: Redis,
-  ) {}
-
-  async onModuleInit(): Promise<void> {
-    if (!this.redis) {
-      this.logger.warn('Redis client not available — consumer disabled');
-      return;
-    }
-
-    // Clone a dedicated connection for blocking reads.
-    // This prevents XREADGROUP BLOCK from starving cache/lock/publish ops on the shared client.
-    this.blockingClient = this.redis.duplicate();
-    this.blockingClient.on('error', (err) =>
-      this.logger.error(`Blocking client error on ${this.streamKey}: ${err.message}`),
-    );
-
-    // Create consumer group (idempotent) — uses shared client (non-blocking)
-    try {
-      await this.redis.xgroup(
-        'CREATE',
-        this.streamKey,
-        this.consumerGroup,
-        '0',
-        'MKSTREAM',
-      );
-      this.logger.log(`Created consumer group "${this.consumerGroup}" on "${this.streamKey}"`);
-    } catch (err: any) {
-      if (!err.message?.includes('BUSYGROUP')) {
-        throw err;
-      }
-      // Group already exists — fine
-    }
-
-    this.running = true;
-
-    // Process pending messages first, then new ones
-    // Run in background so NestJS startup isn't blocked
-    void this.consumeLoop();
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    this.running = false;
-
-    // Disconnect the dedicated blocking client
-    if (this.blockingClient) {
-      this.blockingClient.disconnect();
-      this.blockingClient = undefined;
-    }
-  }
-
-  private async consumeLoop(): Promise<void> {
-    // Phase 1: recover pending (unacked) messages
-    await this.readMessages('0');
-
-    // Phase 2: read new messages
-    while (this.running) {
-      await this.readMessages('>');
-    }
-  }
-
-  private async readMessages(id: '0' | '>'): Promise<void> {
-    if (!this.redis || !this.blockingClient || !this.running) return;
-
-    try {
-      const blockMs = id === '>' ? 5000 : undefined;
-      const args: (string | number)[] = [
-        'GROUP',
-        this.consumerGroup,
-        this.consumerName,
-        'COUNT',
-        '10',
-      ];
-      if (blockMs !== undefined) {
-        args.push('BLOCK', blockMs);
-      }
-      args.push('STREAMS', this.streamKey, id);
-
-      // Use dedicated blocking client for XREADGROUP — never the shared REDIS_CLIENT
-      const results = await (this.blockingClient as any).xreadgroup(...args) as
-        Array<[string, Array<[string, string[]]>]> | null;
-
-      if (!results || results.length === 0) {
-        if (id === '0') return; // No pending — switch to new messages
-        return;
-      }
-
-      const [, entries] = results[0];
-
-      if (entries.length === 0 && id === '0') {
-        return; // All pending recovered
-      }
-
-      for (const [messageId, fieldArray] of entries) {
-        // Parse flat field array into Record
-        const fields: Record<string, string> = {};
-        for (let i = 0; i < fieldArray.length; i += 2) {
-          fields[fieldArray[i]] = fieldArray[i + 1];
-        }
-
-        if (!this.shouldHandle(fields)) {
-          // Ack and skip — uses shared client (non-blocking)
-          await this.redis.xack(this.streamKey, this.consumerGroup, messageId);
-          continue;
-        }
-
-        try {
-          await this.handleMessage(fields);
-          // XACK on shared client — non-blocking
-          await this.redis.xack(this.streamKey, this.consumerGroup, messageId);
-        } catch (err: any) {
-          this.logger.error(
-            `Failed to process message ${messageId} on ${this.streamKey}: ${err.message}`,
-            err.stack,
-          );
-          // Don't ack — message stays pending for retry on next startup
-        }
-      }
-    } catch (err: any) {
-      if (!this.running) return; // Shutdown in progress
-      this.logger.error(`Consumer read error on ${this.streamKey}: ${err.message}`, err.stack);
-      // Back off before retrying
-      await new Promise((r) => setTimeout(r, 2000));
-    }
-  }
-}

package/src/events/RedisStreamPublisher.ts

@@ -1,54 +0,0 @@
-import { Injectable, Logger, Inject, Optional } from '@nestjs/common';
-import { REDIS_CLIENT } from '../cqrs/constants';
-import type { Redis } from 'ioredis';
-import { DomainEvent } from './DomainEvent';
-
-const MAX_STREAM_LENGTH = 10000;
-
-@Injectable()
-export class RedisStreamPublisher {
-  private readonly logger = new Logger(RedisStreamPublisher.name);
-
-  constructor(
-    @Optional() @Inject(REDIS_CLIENT) private readonly redis?: Redis,
-  ) {}
-
-  async publish(event: DomainEvent): Promise<void> {
-    if (!this.redis) {
-      this.logger.warn('Redis client not available, skipping event publish');
-      return;
-    }
-
-    await this.publishToStream(event.streamKey, {
-      eventId: event.eventId,
-      eventType: event.eventType,
-      aggregateId: event.aggregateId,
-      organizationId: event.organizationId || '',
-      payload: JSON.stringify(event.payload),
-      occurredAt: event.occurredAt.toISOString(),
-    });
-  }
-
-  async publishToStream(
-    streamKey: string,
-    fields: Record<string, string>,
-  ): Promise<string | null> {
-    if (!this.redis) return null;
-
-    try {
-      const messageId = await this.redis.xadd(
-        streamKey,
-        'MAXLEN',
-        '~',
-        String(MAX_STREAM_LENGTH),
-        '*',
-        ...Object.entries(fields).flat(),
-      );
-      this.logger.debug(`Published to ${streamKey}: ${messageId}`);
-      return messageId;
-    } catch (error) {
-      this.logger.error(`Failed to publish to ${streamKey}`, (error as Error).stack);
-      throw error;
-    }
-  }
-}