@quanticjs/core 1.1.1

package/src/shared-kernel.module.ts

@@ -0,0 +1,87 @@
+import { DynamicModule, Global, Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+import { QuanticCommandBus } from './cqrs/pipeline/QuanticCommandBus';
+import { QuanticQueryBus } from './cqrs/pipeline/QuanticQueryBus';
+import { LogBehavior } from './cqrs/behaviors/LogBehavior';
+import { ValidationBehavior } from './cqrs/behaviors/ValidationBehavior';
+import { CacheBehavior } from './cqrs/behaviors/CacheBehavior';
+import { DistributedLockBehavior } from './cqrs/behaviors/DistributedLockBehavior';
+import { TransactionalBehavior } from './cqrs/behaviors/TransactionalBehavior';
+import { PerformanceBehavior } from './cqrs/behaviors/PerformanceBehavior';
+import { WorkflowBehavior } from './cqrs/behaviors/WorkflowBehavior';
+import { InvalidateCacheBehavior } from './cqrs/behaviors/InvalidateCacheBehavior';
+import { MetricsService } from './metrics/MetricsService';
+import { MetricsController } from './metrics/MetricsController';
+import { GracefulShutdownService } from './lifecycle/GracefulShutdownService';
+import { RedisStreamPublisher } from './events/RedisStreamPublisher';
+import { RedisModule, type RedisModuleOptions } from './redis/redis.module';
+import { UnleashModule, type UnleashModuleOptions } from './unleash/unleash.module';
+
+export type SharedKernelModuleOptions = QuanticModuleOptions;
+
+export interface QuanticModuleOptions {
+  redis?: RedisModuleOptions;
+  unleash?: UnleashModuleOptions | false;
+}
+
+@Global()
+@Module({})
+export class QuanticModule {
+  static forRoot(options: QuanticModuleOptions = {}): DynamicModule {
+    const imports: Array<DynamicModule> = [
+      CqrsModule.forRoot(),
+      RedisModule.forRoot(options.redis),
+    ];
+
+    if (options.unleash !== false) {
+      imports.push(UnleashModule.forRoot(options.unleash));
+    }
+
+    const exports: any[] = [
+      CqrsModule,
+      RedisModule,
+      RedisStreamPublisher,
+      LogBehavior,
+      ValidationBehavior,
+      CacheBehavior,
+      InvalidateCacheBehavior,
+      DistributedLockBehavior,
+      TransactionalBehavior,
+      PerformanceBehavior,
+      WorkflowBehavior,
+      MetricsService,
+      GracefulShutdownService,
+      QuanticCommandBus,
+      QuanticQueryBus,
+    ];
+
+    if (options.unleash !== false) {
+      exports.push(UnleashModule);
+    }
+
+    return {
+      module: QuanticModule,
+      imports,
+      controllers: [MetricsController],
+      providers: [
+        LogBehavior,
+        ValidationBehavior,
+        CacheBehavior,
+        InvalidateCacheBehavior,
+        DistributedLockBehavior,
+        TransactionalBehavior,
+        PerformanceBehavior,
+        WorkflowBehavior,
+        MetricsService,
+        GracefulShutdownService,
+        RedisStreamPublisher,
+        QuanticCommandBus,
+        QuanticQueryBus,
+      ],
+      exports,
+    };
+  }
+}
+
+/** @deprecated Use QuanticModule instead */
+export const SharedKernelModule = QuanticModule;

package/src/subscribers/TenantSubscriber.ts

@@ -0,0 +1,47 @@
+import { EventSubscriber, EntitySubscriberInterface, InsertEvent, UpdateEvent, RemoveEvent } from 'typeorm';
+import { TenantBaseEntity } from '../entities/TenantBaseEntity';
+import { tenantStore } from '../middleware/TenantStore';
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * TypeORM subscriber that sets PostgreSQL session variable `app.current_org_id`
+ * before write operations on tenant-scoped entities. This enables RLS policies.
+ *
+ * For SELECT queries, RLS is enforced via the session variable set by the
+ * TransactionalBehavior or manually via `SET LOCAL app.current_org_id`.
+ *
+ * Register this subscriber in each service's TypeORM DataSource config:
+ *   subscribers: [TenantSubscriber]
+ */
+@EventSubscriber()
+export class TenantSubscriber implements EntitySubscriberInterface<TenantBaseEntity> {
+  listenTo() {
+    return TenantBaseEntity;
+  }
+
+  async beforeInsert(event: InsertEvent<TenantBaseEntity>): Promise<void> {
+    const orgId = event.entity?.organizationId ?? this.getOrgIdFromStore();
+    await this.setTenantId(event.queryRunner, orgId);
+  }
+
+  async beforeUpdate(event: UpdateEvent<TenantBaseEntity>): Promise<void> {
+    const orgId = event.entity?.organizationId ?? this.getOrgIdFromStore();
+    await this.setTenantId(event.queryRunner, orgId);
+  }
+
+  async beforeRemove(event: RemoveEvent<TenantBaseEntity>): Promise<void> {
+    const orgId = event.entity?.organizationId ?? this.getOrgIdFromStore();
+    await this.setTenantId(event.queryRunner, orgId);
+  }
+
+  private getOrgIdFromStore(): string | null {
+    return tenantStore.getStore()?.organizationId ?? null;
+  }
+
+  private async setTenantId(queryRunner: any, organizationId?: string | null): Promise<void> {
+    if (organizationId && UUID_REGEX.test(organizationId)) {
+      await queryRunner.query(`SET LOCAL app.current_org_id = '${organizationId}'`);
+    }
+  }
+}

package/src/testing/TestingModuleFactory.ts

@@ -0,0 +1,78 @@
+import { Test, TestingModuleBuilder } from '@nestjs/testing';
+import { CqrsModule } from '@nestjs/cqrs';
+import { getRepositoryToken } from '@nestjs/typeorm';
+import { Logger } from '@nestjs/common';
+import { QuanticCommandBus } from '../cqrs/pipeline/QuanticCommandBus';
+import { QuanticQueryBus } from '../cqrs/pipeline/QuanticQueryBus';
+import { LogBehavior } from '../cqrs/behaviors/LogBehavior';
+import { ValidationBehavior } from '../cqrs/behaviors/ValidationBehavior';
+import { CacheBehavior } from '../cqrs/behaviors/CacheBehavior';
+import { DistributedLockBehavior } from '../cqrs/behaviors/DistributedLockBehavior';
+import { TransactionalBehavior } from '../cqrs/behaviors/TransactionalBehavior';
+import { PerformanceBehavior } from '../cqrs/behaviors/PerformanceBehavior';
+import { MetricsService } from '../metrics/MetricsService';
+import { REDIS_CLIENT } from '../cqrs/constants';
+import { createMockRepository, createMockRedisClient } from './mocks';
+
+export { createMockRepository, createMockRedisClient };
+
+export interface TestingModuleOptions {
+  /** Providers to register (handlers, services, etc.) */
+  providers?: any[];
+  /** Entity classes to auto-mock their repositories */
+  entities?: any[];
+  /** Additional overrides to apply to the TestingModule builder */
+  overrides?: Array<{ provide: any; useValue: any }>;
+  /** Whether to include the full CQRS pipeline behaviors (default: false) */
+  withPipeline?: boolean;
+}
+
+/**
+ * Factory for bootstrapping a NestJS TestingModule preconfigured
+ * with mocked repositories, Redis, and optionally the CQRS pipeline.
+ */
+export class TestingModuleFactory {
+  static create(options: TestingModuleOptions = {}): TestingModuleBuilder {
+    const { providers = [], entities = [], overrides = [], withPipeline = false } = options;
+
+    const mockRepos = entities.map((entity) => ({
+      provide: getRepositoryToken(entity),
+      useValue: createMockRepository(),
+    }));
+
+    const mockRedis = { provide: REDIS_CLIENT, useValue: createMockRedisClient() };
+
+    const pipelineProviders = withPipeline
+      ? [
+          LogBehavior,
+          ValidationBehavior,
+          CacheBehavior,
+          DistributedLockBehavior,
+          TransactionalBehavior,
+          PerformanceBehavior,
+          MetricsService,
+          QuanticCommandBus,
+          QuanticQueryBus,
+        ]
+      : [];
+
+    let builder = Test.createTestingModule({
+      imports: [CqrsModule.forRoot()],
+      providers: [
+        ...mockRepos,
+        mockRedis,
+        ...pipelineProviders,
+        ...providers,
+      ],
+    });
+
+    for (const override of overrides) {
+      builder = builder.overrideProvider(override.provide).useValue(override.useValue);
+    }
+
+    // Silence NestJS logs during tests
+    Logger.overrideLogger(['error']);
+
+    return builder;
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export { TestingModuleFactory, createMockRepository, createMockRedisClient } from './TestingModuleFactory';
+export type { TestingModuleOptions } from './TestingModuleFactory';

package/src/testing/mocks.ts

@@ -0,0 +1,59 @@
+/**
+ * Creates a mock repository with common TypeORM repository methods stubbed.
+ */
+export function createMockRepository<T = any>() {
+  return {
+    find: jest.fn(),
+    findOne: jest.fn(),
+    findOneBy: jest.fn(),
+    findAndCount: jest.fn(),
+    save: jest.fn().mockImplementation((entity: T) => Promise.resolve(entity)),
+    create: jest.fn().mockImplementation((dto: any) => dto),
+    update: jest.fn(),
+    delete: jest.fn(),
+    remove: jest.fn(),
+    count: jest.fn(),
+    createQueryBuilder: jest.fn(() => ({
+      where: jest.fn().mockReturnThis(),
+      andWhere: jest.fn().mockReturnThis(),
+      orderBy: jest.fn().mockReturnThis(),
+      addOrderBy: jest.fn().mockReturnThis(),
+      take: jest.fn().mockReturnThis(),
+      skip: jest.fn().mockReturnThis(),
+      leftJoinAndSelect: jest.fn().mockReturnThis(),
+      getMany: jest.fn().mockResolvedValue([]),
+      getOne: jest.fn().mockResolvedValue(null),
+      getManyAndCount: jest.fn().mockResolvedValue([[], 0]),
+    })),
+    manager: {
+      transaction: jest.fn().mockImplementation((cb: any) => cb({
+        save: jest.fn().mockImplementation((entity: any) => Promise.resolve(entity)),
+        findOne: jest.fn(),
+      })),
+    },
+  };
+}
+
+/**
+ * Creates a mock Redis client with common ioredis methods stubbed.
+ */
+export function createMockRedisClient() {
+  const client: Record<string, jest.Mock> = {
+    get: jest.fn().mockResolvedValue(null),
+    set: jest.fn().mockResolvedValue('OK'),
+    del: jest.fn().mockResolvedValue(1),
+    setex: jest.fn().mockResolvedValue('OK'),
+    exists: jest.fn().mockResolvedValue(0),
+    xadd: jest.fn().mockResolvedValue('1-0'),
+    xreadgroup: jest.fn().mockResolvedValue(null),
+    xack: jest.fn().mockResolvedValue(1),
+    xgroup: jest.fn().mockResolvedValue('OK'),
+    quit: jest.fn().mockResolvedValue('OK'),
+    disconnect: jest.fn(),
+    on: jest.fn().mockReturnThis(),
+    duplicate: jest.fn(),
+  };
+  // duplicate() returns a fresh mock with the same shape
+  client.duplicate.mockImplementation(() => createMockRedisClient());
+  return client;
+}

package/src/unleash/unleash.module.ts

@@ -0,0 +1,45 @@
+import { Module, Global, DynamicModule, Logger } from '@nestjs/common';
+import { initialize, Unleash } from 'unleash-client';
+import { FeatureFlagBehavior } from '../cqrs/behaviors/FeatureFlagBehavior';
+
+export interface UnleashModuleOptions {
+  url?: string;
+  appName?: string;
+  customHeaders?: Record<string, string>;
+}
+
+@Global()
+@Module({})
+export class UnleashModule {
+  static forRoot(options?: UnleashModuleOptions): DynamicModule {
+    const unleashProvider = {
+      provide: Unleash,
+      useFactory: () => {
+        const logger = new Logger('UnleashModule');
+        const url = options?.url || process.env['UNLEASH_URL'] || 'http://localhost:4242/api';
+        const appName = options?.appName || process.env['UNLEASH_APP_NAME'] || 'arex';
+        const token =
+          options?.customHeaders?.['Authorization'] ||
+          process.env['UNLEASH_API_TOKEN'] ||
+          '*:*.unleash-insecure-api-token';
+
+        logger.log(`Connecting to Unleash at ${url}`);
+
+        return initialize({
+          url,
+          appName,
+          customHeaders: {
+            Authorization: token,
+          },
+          refreshInterval: 10000,
+        });
+      },
+    };
+
+    return {
+      module: UnleashModule,
+      providers: [unleashProvider, FeatureFlagBehavior],
+      exports: [Unleash, FeatureFlagBehavior],
+    };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
+}