@quanticjs/core 1.1.1

package/dist/testing/TestingModuleFactory.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestingModuleFactory = exports.createMockRedisClient = exports.createMockRepository = void 0;
+const testing_1 = require("@nestjs/testing");
+const cqrs_1 = require("@nestjs/cqrs");
+const typeorm_1 = require("@nestjs/typeorm");
+const common_1 = require("@nestjs/common");
+const QuanticCommandBus_1 = require("../cqrs/pipeline/QuanticCommandBus");
+const QuanticQueryBus_1 = require("../cqrs/pipeline/QuanticQueryBus");
+const LogBehavior_1 = require("../cqrs/behaviors/LogBehavior");
+const ValidationBehavior_1 = require("../cqrs/behaviors/ValidationBehavior");
+const CacheBehavior_1 = require("../cqrs/behaviors/CacheBehavior");
+const DistributedLockBehavior_1 = require("../cqrs/behaviors/DistributedLockBehavior");
+const TransactionalBehavior_1 = require("../cqrs/behaviors/TransactionalBehavior");
+const PerformanceBehavior_1 = require("../cqrs/behaviors/PerformanceBehavior");
+const MetricsService_1 = require("../metrics/MetricsService");
+const constants_1 = require("../cqrs/constants");
+const mocks_1 = require("./mocks");
+Object.defineProperty(exports, "createMockRepository", { enumerable: true, get: function () { return mocks_1.createMockRepository; } });
+Object.defineProperty(exports, "createMockRedisClient", { enumerable: true, get: function () { return mocks_1.createMockRedisClient; } });
+/**
+ * Factory for bootstrapping a NestJS TestingModule preconfigured
+ * with mocked repositories, Redis, and optionally the CQRS pipeline.
+ */
+class TestingModuleFactory {
+    static create(options = {}) {
+        const { providers = [], entities = [], overrides = [], withPipeline = false } = options;
+        const mockRepos = entities.map((entity) => ({
+            provide: (0, typeorm_1.getRepositoryToken)(entity),
+            useValue: (0, mocks_1.createMockRepository)(),
+        }));
+        const mockRedis = { provide: constants_1.REDIS_CLIENT, useValue: (0, mocks_1.createMockRedisClient)() };
+        const pipelineProviders = withPipeline
+            ? [
+                LogBehavior_1.LogBehavior,
+                ValidationBehavior_1.ValidationBehavior,
+                CacheBehavior_1.CacheBehavior,
+                DistributedLockBehavior_1.DistributedLockBehavior,
+                TransactionalBehavior_1.TransactionalBehavior,
+                PerformanceBehavior_1.PerformanceBehavior,
+                MetricsService_1.MetricsService,
+                QuanticCommandBus_1.QuanticCommandBus,
+                QuanticQueryBus_1.QuanticQueryBus,
+            ]
+            : [];
+        let builder = testing_1.Test.createTestingModule({
+            imports: [cqrs_1.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
+        common_1.Logger.overrideLogger(['error']);
+        return builder;
+    }
+}
+exports.TestingModuleFactory = TestingModuleFactory;

package/dist/testing/index.d.ts

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

package/dist/testing/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMockRedisClient = exports.createMockRepository = exports.TestingModuleFactory = void 0;
+var TestingModuleFactory_1 = require("./TestingModuleFactory");
+Object.defineProperty(exports, "TestingModuleFactory", { enumerable: true, get: function () { return TestingModuleFactory_1.TestingModuleFactory; } });
+Object.defineProperty(exports, "createMockRepository", { enumerable: true, get: function () { return TestingModuleFactory_1.createMockRepository; } });
+Object.defineProperty(exports, "createMockRedisClient", { enumerable: true, get: function () { return TestingModuleFactory_1.createMockRedisClient; } });

package/dist/testing/mocks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Creates a mock repository with common TypeORM repository methods stubbed.
+ */
+export declare function createMockRepository<T = any>(): {
+    find: jest.Mock<any, any, any>;
+    findOne: jest.Mock<any, any, any>;
+    findOneBy: jest.Mock<any, any, any>;
+    findAndCount: jest.Mock<any, any, any>;
+    save: jest.Mock<any, any, any>;
+    create: jest.Mock<any, any, any>;
+    update: jest.Mock<any, any, any>;
+    delete: jest.Mock<any, any, any>;
+    remove: jest.Mock<any, any, any>;
+    count: jest.Mock<any, any, any>;
+    createQueryBuilder: jest.Mock<{
+        where: jest.Mock<any, any, any>;
+        andWhere: jest.Mock<any, any, any>;
+        orderBy: jest.Mock<any, any, any>;
+        addOrderBy: jest.Mock<any, any, any>;
+        take: jest.Mock<any, any, any>;
+        skip: jest.Mock<any, any, any>;
+        leftJoinAndSelect: jest.Mock<any, any, any>;
+        getMany: jest.Mock<any, any, any>;
+        getOne: jest.Mock<any, any, any>;
+        getManyAndCount: jest.Mock<any, any, any>;
+    }, [], any>;
+    manager: {
+        transaction: jest.Mock<any, any, any>;
+    };
+};
+/**
+ * Creates a mock Redis client with common ioredis methods stubbed.
+ */
+export declare function createMockRedisClient(): Record<string, jest.Mock<any, any, any>>;

package/dist/testing/mocks.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMockRepository = createMockRepository;
+exports.createMockRedisClient = createMockRedisClient;
+/**
+ * Creates a mock repository with common TypeORM repository methods stubbed.
+ */
+function createMockRepository() {
+    return {
+        find: jest.fn(),
+        findOne: jest.fn(),
+        findOneBy: jest.fn(),
+        findAndCount: jest.fn(),
+        save: jest.fn().mockImplementation((entity) => Promise.resolve(entity)),
+        create: jest.fn().mockImplementation((dto) => 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) => cb({
+                save: jest.fn().mockImplementation((entity) => Promise.resolve(entity)),
+                findOne: jest.fn(),
+            })),
+        },
+    };
+}
+/**
+ * Creates a mock Redis client with common ioredis methods stubbed.
+ */
+function createMockRedisClient() {
+    const client = {
+        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/dist/unleash/initial-flags.d.ts

@@ -0,0 +1,7 @@
+export declare const FEATURE_FLAGS: {
+    readonly ENABLE_PREMIUM_MODE: "enable-premium-mode";
+    readonly ENABLE_AGENCY_PLAN: "enable-agency-plan";
+    readonly ENABLE_BACKLOG_GENERATION: "enable-backlog-generation";
+};
+export type FeatureFlagName = (typeof FEATURE_FLAGS)[keyof typeof FEATURE_FLAGS];
+//# sourceMappingURL=initial-flags.d.ts.map

package/dist/unleash/initial-flags.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEATURE_FLAGS = void 0;
+exports.FEATURE_FLAGS = {
+    ENABLE_PREMIUM_MODE: 'enable-premium-mode',
+    ENABLE_AGENCY_PLAN: 'enable-agency-plan',
+    ENABLE_BACKLOG_GENERATION: 'enable-backlog-generation',
+};
+//# sourceMappingURL=initial-flags.js.map

package/dist/unleash/unleash.module.d.ts

@@ -0,0 +1,9 @@
+import { DynamicModule } from '@nestjs/common';
+export interface UnleashModuleOptions {
+    url?: string;
+    appName?: string;
+    customHeaders?: Record<string, string>;
+}
+export declare class UnleashModule {
+    static forRoot(options?: UnleashModuleOptions): DynamicModule;
+}

package/dist/unleash/unleash.module.js

@@ -0,0 +1,47 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var UnleashModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnleashModule = void 0;
+const common_1 = require("@nestjs/common");
+const unleash_client_1 = require("unleash-client");
+const FeatureFlagBehavior_1 = require("../cqrs/behaviors/FeatureFlagBehavior");
+let UnleashModule = UnleashModule_1 = class UnleashModule {
+    static forRoot(options) {
+        const unleashProvider = {
+            provide: unleash_client_1.Unleash,
+            useFactory: () => {
+                const logger = new common_1.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 (0, unleash_client_1.initialize)({
+                    url,
+                    appName,
+                    customHeaders: {
+                        Authorization: token,
+                    },
+                    refreshInterval: 10000,
+                });
+            },
+        };
+        return {
+            module: UnleashModule_1,
+            providers: [unleashProvider, FeatureFlagBehavior_1.FeatureFlagBehavior],
+            exports: [unleash_client_1.Unleash, FeatureFlagBehavior_1.FeatureFlagBehavior],
+        };
+    }
+};
+exports.UnleashModule = UnleashModule;
+exports.UnleashModule = UnleashModule = UnleashModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], UnleashModule);

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@quanticjs/core",
+  "version": "1.1.1",
+  "description": "NestJS CQRS framework — Result<T>, pipeline behaviors, base entities, multi-tenancy, Redis Streams, observability",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quanticjs/quanticjs-backend.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint 'src/**/*.ts'",
+    "test": "jest --passWithNoTests"
+  },
+  "dependencies": {
+    "cockatiel": "^3.2.1",
+    "uuid": "^11.1.0",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/passport": "^11.0.0",
+    "@nestjs/swagger": "^11.0.0",
+    "@nestjs/terminus": "^11.0.0",
+    "@nestjs/throttler": "^6.0.0",
+    "helmet": "^8.0.0",
+    "ioredis": "^5.0.0",
+    "jwks-rsa": "^4.0.0",
+    "nestjs-pino": "^4.0.0",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.0",
+    "pino": "^10.0.0",
+    "pino-http": "^11.0.0",
+    "pino-seq": "^3.0.0 || ^4.0.0",
+    "prom-client": "^15.0.0",
+    "typeorm": "^0.3.20",
+    "unleash-client": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": false
+    },
+    "@nestjs/passport": {
+      "optional": false
+    },
+    "@nestjs/swagger": {
+      "optional": false
+    },
+    "@nestjs/terminus": {
+      "optional": false
+    },
+    "@nestjs/throttler": {
+      "optional": false
+    },
+    "helmet": {
+      "optional": false
+    },
+    "ioredis": {
+      "optional": false
+    },
+    "jwks-rsa": {
+      "optional": false
+    },
+    "nestjs-pino": {
+      "optional": false
+    },
+    "passport": {
+      "optional": false
+    },
+    "passport-jwt": {
+      "optional": false
+    },
+    "pino": {
+      "optional": false
+    },
+    "pino-http": {
+      "optional": false
+    },
+    "pino-seq": {
+      "optional": false
+    },
+    "prom-client": {
+      "optional": false
+    },
+    "typeorm": {
+      "optional": false
+    },
+    "unleash-client": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/swagger": "^11.4.2",
+    "@nestjs/terminus": "^11.1.1",
+    "@nestjs/testing": "^11.1.19",
+    "@nestjs/throttler": "^6.5.0",
+    "@nestjs/typeorm": "^11.0.1",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^29.5.0",
+    "@types/passport-jwt": "^4.0.1",
+    "@types/node": "^22.0.0",
+    "@types/uuid": "^10.0.0",
+    "cookie-parser": "^1.4.7",
+    "@nestjs/passport": "^11.0.5",
+    "eslint": "^9.0.0",
+    "express": "^5.2.1",
+    "helmet": "^8.1.0",
+    "ioredis": "^5.10.1",
+    "jest": "^29.7.0",
+    "jwks-rsa": "^4.0.1",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.1",
+    "nestjs-pino": "^4.6.1",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0",
+    "pino-seq": "^4.0.0",
+    "prom-client": "^15.1.3",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "ts-jest": "^29.2.0",
+    "typeorm": "^0.3.29",
+    "typescript": "^5.7.0",
+    "unleash-client": "^6.10.1"
+  }
+}

package/src/bootstrap/bootstrapService.ts

@@ -0,0 +1,72 @@
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { Logger } from 'nestjs-pino';
+import helmet from 'helmet';
+import cookieParser from 'cookie-parser';
+import { GlobalExceptionFilter } from '../filters/GlobalExceptionFilter';
+
+export interface BootstrapOptions {
+  module: any;
+  port: number;
+  serviceName: string;
+  rawBody?: boolean;
+}
+
+export async function bootstrapService(options: BootstrapOptions): Promise<INestApplication> {
+  const { module, port, serviceName, rawBody } = options;
+
+  const app = await NestFactory.create(module, {
+    bufferLogs: true,
+    ...(rawBody ? { rawBody: true } : {}),
+  });
+
+  app.useLogger(app.get(Logger));
+
+  // Security headers
+  app.use(helmet());
+
+  // Cookie parsing (required for OAuth flows)
+  app.use(cookieParser());
+
+  // CORS
+  const allowedOrigins = (process.env.CORS_ORIGINS || 'http://localhost:5173').split(',');
+  app.enableCors({
+    origin: allowedOrigins,
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-Tenant-ID', 'X-Correlation-ID'],
+    exposedHeaders: ['X-Correlation-ID'],
+    maxAge: 86400,
+  });
+
+  // Global exception filter
+  app.useGlobalFilters(new GlobalExceptionFilter());
+
+  // Global validation pipe
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+    }),
+  );
+
+  // Swagger — disabled in production
+  if (process.env.NODE_ENV !== 'production') {
+    const config = new DocumentBuilder()
+      .setTitle(`AREX — ${serviceName}`)
+      .setDescription(`OpenAPI spec for ${serviceName}`)
+      .setVersion('1.0.0')
+      .addBearerAuth()
+      .build();
+    const document = SwaggerModule.createDocument(app, config);
+    SwaggerModule.setup('swagger', app, document);
+  }
+
+  // Enable graceful shutdown hooks (SIGTERM, SIGINT)
+  app.enableShutdownHooks();
+
+  await app.listen(port);
+  return app;
+}

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

@@ -0,0 +1,63 @@
+import { CacheBehavior } from './CacheBehavior';
+import { Result } from '../../result/Result';
+import { Cache } from '../decorators/Cache.decorator';
+
+@Cache('test:{id}', { ttlSeconds: 60 })
+class CachedQuery {
+  constructor(public readonly id: string) {}
+}
+
+class UncachedQuery {
+  constructor(public readonly id: string) {}
+}
+
+describe('CacheBehavior', () => {
+  let redis: { get: jest.Mock; set: jest.Mock };
+  let behavior: CacheBehavior;
+  const next = jest.fn();
+
+  beforeEach(() => {
+    redis = {
+      get: jest.fn().mockResolvedValue(null),
+      set: jest.fn().mockResolvedValue('OK'),
+    };
+    behavior = new CacheBehavior(redis as any);
+    next.mockReset().mockResolvedValue(Result.success({ data: 'fresh' }));
+  });
+
+  it('should skip cache for commands without @Cache decorator', async () => {
+    const result = await behavior.execute(new UncachedQuery('1'), next);
+
+    expect(result.isSuccess).toBe(true);
+    expect(redis.get).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return cached value on cache hit', async () => {
+    redis.get.mockResolvedValue(JSON.stringify({ data: 'cached' }));
+
+    const result = await behavior.execute(new CachedQuery('abc'), next);
+
+    expect(result.isSuccess).toBe(true);
+    expect(result.value).toEqual({ data: 'cached' });
+    expect(next).not.toHaveBeenCalled();
+    expect(redis.get).toHaveBeenCalledWith('test:abc');
+  });
+
+  it('should call handler and cache result on cache miss', async () => {
+    const result = await behavior.execute(new CachedQuery('abc'), next);
+
+    expect(result.isSuccess).toBe(true);
+    expect(result.value).toEqual({ data: 'fresh' });
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(redis.set).toHaveBeenCalledWith('test:abc', JSON.stringify({ data: 'fresh' }), 'EX', 60);
+  });
+
+  it('should skip cache when redis is not available', async () => {
+    const noCacheBehavior = new CacheBehavior(undefined);
+    const result = await noCacheBehavior.execute(new CachedQuery('1'), next);
+
+    expect(result.isSuccess).toBe(true);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});

package/src/cqrs/behaviors/CacheBehavior.ts

@@ -0,0 +1,54 @@
+import { Injectable, Logger, Optional, Inject } from '@nestjs/common';
+import { getCacheMetadata } from '../decorators/Cache.decorator';
+import { Result } from '../../result/Result';
+import { REDIS_CLIENT } from '../constants';
+import type { Redis } from 'ioredis';
+
+@Injectable()
+export class CacheBehavior {
+  private readonly logger = new Logger(CacheBehavior.name);
+
+  constructor(
+    @Optional() @Inject(REDIS_CLIENT) private readonly redis?: Redis,
+  ) {}
+
+  async execute<T>(command: object, next: () => Promise<Result<T>>): Promise<Result<T>> {
+    const metadata = getCacheMetadata(command.constructor);
+
+    if (!metadata || !this.redis) {
+      return next();
+    }
+
+    const cacheKey = this.interpolateKey(metadata.key, command);
+
+    try {
+      const cached = await this.redis.get(cacheKey);
+      if (cached) {
+        this.logger.debug(`Cache hit: ${cacheKey}`);
+        return Result.success(JSON.parse(cached) as T);
+      }
+    } catch {
+      this.logger.warn(`Cache read failed for key: ${cacheKey}`);
+    }
+
+    const result = await next();
+
+    if (result.isSuccess && result.value !== undefined) {
+      try {
+        await this.redis.set(cacheKey, JSON.stringify(result.value), 'EX', metadata.ttlSeconds!);
+        this.logger.debug(`Cache set: ${cacheKey} (TTL: ${metadata.ttlSeconds}s)`);
+      } catch {
+        this.logger.warn(`Cache write failed for key: ${cacheKey}`);
+      }
+    }
+
+    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/DistributedLockBehavior.ts

@@ -0,0 +1,88 @@
+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) : '';
+    });
+  }
+}