@nestjs-redisx/locks 1.0.0

package/dist/index.mjs

@@ -0,0 +1,625 @@
+import { Reflector } from '@nestjs/core';
+import { Logger, Injectable, Inject, Optional } from '@nestjs/common';
+import 'reflect-metadata';
+import { REDIS_DRIVER, RedisXError, ErrorCode } from '@nestjs-redisx/core';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/shared/constants/index.ts
+var LOCKS_PLUGIN_OPTIONS = /* @__PURE__ */ Symbol.for("LOCKS_PLUGIN_OPTIONS");
+var LOCK_SERVICE = /* @__PURE__ */ Symbol.for("LOCK_SERVICE");
+var LOCK_STORE = /* @__PURE__ */ Symbol.for("LOCK_STORE");
+var LockError = class extends RedisXError {
+  constructor(message, code, lockKey, cause) {
+    super(message, code, cause, { lockKey });
+    this.lockKey = lockKey;
+  }
+};
+var LockAcquisitionError = class extends LockError {
+  constructor(key, reason, cause) {
+    super(`Failed to acquire lock "${key}": ${reason}`, reason === "timeout" ? ErrorCode.LOCK_ACQUISITION_TIMEOUT : ErrorCode.LOCK_ACQUISITION_FAILED, key, cause);
+    this.reason = reason;
+  }
+};
+var LockNotOwnedError = class extends LockError {
+  constructor(key, token) {
+    super(`Lock "${key}" not owned by token "${token}"`, ErrorCode.LOCK_NOT_OWNED, key);
+    this.token = token;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      token: this.token
+    };
+  }
+};
+var LockExtensionError = class extends LockError {
+  constructor(key, token, cause) {
+    super(`Failed to extend lock "${key}"`, ErrorCode.LOCK_EXTENSION_FAILED, key, cause);
+    this.token = token;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      token: this.token
+    };
+  }
+};
+var LockExpiredError = class extends LockError {
+  constructor(key) {
+    super(`Lock "${key}" expired`, ErrorCode.LOCK_EXPIRED, key);
+  }
+};
+
+// src/lock/api/decorators/with-lock.decorator.ts
+var logger = new Logger("WithLock");
+var WITH_LOCK_OPTIONS = /* @__PURE__ */ Symbol.for("WITH_LOCK_OPTIONS");
+var globalLockServiceGetter = null;
+function registerLockServiceGetter(getter) {
+  globalLockServiceGetter = getter;
+}
+function WithLock(options) {
+  return (target, propertyKey, descriptor) => {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function(...args) {
+      if (!globalLockServiceGetter) {
+        logger.warn(`@WithLock: LockService not yet available, executing method without lock`);
+        return originalMethod.apply(this, args);
+      }
+      const lockService = globalLockServiceGetter();
+      if (!lockService) {
+        logger.warn(`@WithLock: LockService getter returned null, executing method without lock`);
+        return originalMethod.apply(this, args);
+      }
+      const key = buildLockKey(args, options);
+      let lock = null;
+      try {
+        lock = await lockService.acquire(key, {
+          ttl: options.ttl,
+          waitTimeout: options.waitTimeout,
+          autoRenew: options.autoRenew
+        });
+        const result = await originalMethod.apply(this, args);
+        return result;
+      } catch (error) {
+        if (error instanceof LockAcquisitionError) {
+          return handleLockFailed(key, options, error);
+        }
+        throw error;
+      } finally {
+        if (lock) {
+          await lock.release().catch((err) => {
+            logger.error(`@WithLock: Failed to release lock ${key}:`, err);
+          });
+        }
+      }
+    };
+    Object.defineProperty(descriptor.value, "name", {
+      value: originalMethod.name,
+      writable: false
+    });
+    Reflect.defineMetadata(WITH_LOCK_OPTIONS, options, descriptor.value);
+    return descriptor;
+  };
+}
+function buildLockKey(args, options) {
+  if (typeof options.key === "function") {
+    return options.key(...args);
+  }
+  return interpolateKey(options.key, args);
+}
+function interpolateKey(template, args) {
+  return template.replace(/\{(\d+)(?:\.(\w+))?\}/g, (_, index, prop) => {
+    const arg = args[Number(index)];
+    if (prop && typeof arg === "object" && arg !== null) {
+      return String(arg[prop]);
+    }
+    return String(arg);
+  });
+}
+function handleLockFailed(key, options, error) {
+  const handler = options.onLockFailed ?? "throw";
+  if (handler === "throw") {
+    throw error;
+  }
+  if (handler === "skip") {
+    return void 0;
+  }
+  if (typeof handler === "function") {
+    throw handler(key);
+  }
+  throw error;
+}
+
+// src/lock/application/services/lock-decorator-initializer.service.ts
+var LockDecoratorInitializerService = class {
+  constructor(lockService) {
+    this.lockService = lockService;
+  }
+  logger = new Logger(LockDecoratorInitializerService.name);
+  /**
+   * Called after all modules are initialized.
+   * Registers lock service getter for @WithLock decorator.
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async onModuleInit() {
+    this.logger.debug("Registering LockService getter for @WithLock decorator");
+    registerLockServiceGetter(() => this.lockService);
+    this.logger.log("@WithLock decorator initialized and ready to use");
+  }
+};
+LockDecoratorInitializerService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(LOCK_SERVICE))
+], LockDecoratorInitializerService);
+
+// src/lock/domain/entities/lock.entity.ts
+var Lock = class {
+  /**
+   * Creates a new Lock instance.
+   *
+   * @param key - Lock key in Redis
+   * @param token - Unique ownership token
+   * @param ttl - Time-to-live in milliseconds
+   * @param store - Lock store for persistence operations
+   */
+  constructor(key, token, ttl, store) {
+    this.store = store;
+    this.key = key;
+    this.token = token;
+    this.ttl = ttl;
+    this.acquiredAt = /* @__PURE__ */ new Date();
+    this._expiresAt = new Date(Date.now() + ttl);
+  }
+  key;
+  token;
+  ttl;
+  acquiredAt;
+  _expiresAt;
+  autoRenewTimer = null;
+  released = false;
+  /**
+   * Gets the expiration timestamp.
+   */
+  get expiresAt() {
+    return this._expiresAt;
+  }
+  /**
+   * Checks if auto-renewal is active.
+   */
+  get isAutoRenewing() {
+    return this.autoRenewTimer !== null;
+  }
+  /**
+   * Releases the lock.
+   *
+   * Stops auto-renewal and removes the lock from Redis.
+   * Idempotent - can be called multiple times safely.
+   *
+   * @throws {LockNotOwnedError} If lock is not owned by this token
+   */
+  async release() {
+    if (this.released) {
+      return;
+    }
+    this.stopAutoRenew();
+    const success = await this.store.release(this.key, this.token);
+    if (!success) {
+      throw new LockNotOwnedError(this.key, this.token);
+    }
+    this.released = true;
+  }
+  /**
+   * Extends the lock TTL.
+   *
+   * @param ttl - New TTL in milliseconds
+   * @throws {LockNotOwnedError} If lock was already released
+   * @throws {LockExtensionError} If extension fails (lock expired or not owned)
+   */
+  async extend(ttl) {
+    if (this.released) {
+      throw new LockNotOwnedError(this.key, this.token);
+    }
+    const success = await this.store.extend(this.key, this.token, ttl);
+    if (!success) {
+      throw new LockExtensionError(this.key, this.token);
+    }
+    this._expiresAt = new Date(Date.now() + ttl);
+  }
+  /**
+   * Checks if lock is still held.
+   *
+   * @returns False if released, otherwise checks Redis
+   */
+  async isHeld() {
+    if (this.released) {
+      return false;
+    }
+    return this.store.isHeldBy(this.key, this.token);
+  }
+  /**
+   * Starts automatic lock renewal.
+   *
+   * The lock will be extended at the specified interval
+   * until stopAutoRenew() is called or extension fails.
+   *
+   * @param intervalMs - Renewal interval in milliseconds
+   */
+  startAutoRenew(intervalMs) {
+    if (this.autoRenewTimer) {
+      return;
+    }
+    this.autoRenewTimer = setInterval(async () => {
+      try {
+        await this.extend(this.ttl);
+      } catch {
+        this.stopAutoRenew();
+      }
+    }, intervalMs);
+    if (this.autoRenewTimer.unref) {
+      this.autoRenewTimer.unref();
+    }
+  }
+  /**
+   * Stops automatic lock renewal.
+   *
+   * Safe to call multiple times.
+   */
+  stopAutoRenew() {
+    if (this.autoRenewTimer) {
+      clearInterval(this.autoRenewTimer);
+      this.autoRenewTimer = null;
+    }
+  }
+};
+
+// src/lock/application/services/lock.service.ts
+var METRICS_SERVICE = /* @__PURE__ */ Symbol.for("METRICS_SERVICE");
+var TRACING_SERVICE = /* @__PURE__ */ Symbol.for("TRACING_SERVICE");
+var LockService = class {
+  constructor(config, store, metrics, tracing) {
+    this.config = config;
+    this.store = store;
+    this.metrics = metrics;
+    this.tracing = tracing;
+  }
+  logger = new Logger(LockService.name);
+  activeLocks = /* @__PURE__ */ new Set();
+  /**
+   * Lifecycle hook: releases all active locks on shutdown.
+   */
+  async onModuleDestroy() {
+    const releasePromises = Array.from(this.activeLocks).map(
+      (lock) => lock.release().catch((error) => {
+        this.logger.error(`Failed to release lock ${lock.key} during shutdown:`, error);
+      })
+    );
+    await Promise.all(releasePromises);
+    this.activeLocks.clear();
+  }
+  /**
+   * Acquires lock with exponential backoff retry.
+   */
+  async acquire(key, options = {}) {
+    const span = this.tracing?.startSpan("lock.acquire", {
+      kind: "INTERNAL",
+      attributes: { "lock.key": key, "lock.ttl": options.ttl }
+    });
+    const fullKey = this.buildKey(key);
+    const ttl = this.resolveTtl(options.ttl);
+    const token = this.generateToken();
+    const retry = this.resolveRetryConfig(options);
+    const startTime = Date.now();
+    let delay = retry.initialDelay;
+    try {
+      for (let attempt = 0; attempt <= retry.maxRetries; attempt++) {
+        const acquired = await this.store.acquire(fullKey, token, ttl);
+        if (acquired) {
+          const waitDuration = (Date.now() - startTime) / 1e3;
+          this.metrics?.observeHistogram("redisx_lock_wait_duration_seconds", waitDuration);
+          this.metrics?.incrementCounter("redisx_lock_acquisitions_total", { status: "acquired" });
+          this.metrics?.incrementGauge("redisx_locks_active");
+          span?.setAttribute("lock.acquired", true);
+          span?.setAttribute("lock.attempts", attempt + 1);
+          span?.setStatus("OK");
+          const lock = this.createLock(fullKey, token, ttl, options);
+          this.activeLocks.add(lock);
+          return lock;
+        }
+        if (attempt === retry.maxRetries) {
+          this.metrics?.incrementCounter("redisx_lock_acquisitions_total", { status: "failed" });
+          span?.setAttribute("lock.acquired", false);
+          span?.setAttribute("lock.attempts", attempt + 1);
+          span?.setStatus("ERROR");
+          throw new LockAcquisitionError(key, "timeout");
+        }
+        await this.sleep(delay);
+        delay = Math.min(delay * retry.multiplier, retry.maxDelay);
+      }
+      this.metrics?.incrementCounter("redisx_lock_acquisitions_total", { status: "failed" });
+      throw new LockAcquisitionError(key, "timeout");
+    } catch (error) {
+      span?.recordException(error);
+      span?.setStatus("ERROR");
+      throw error;
+    } finally {
+      span?.end();
+    }
+  }
+  /**
+   * Tries to acquire lock once without retry.
+   */
+  async tryAcquire(key, options = {}) {
+    const fullKey = this.buildKey(key);
+    const ttl = this.resolveTtl(options.ttl);
+    const token = this.generateToken();
+    const acquired = await this.store.acquire(fullKey, token, ttl);
+    if (!acquired) {
+      this.metrics?.incrementCounter("redisx_lock_acquisitions_total", { status: "failed" });
+      return null;
+    }
+    this.metrics?.incrementCounter("redisx_lock_acquisitions_total", { status: "acquired" });
+    this.metrics?.incrementGauge("redisx_locks_active");
+    const lock = this.createLock(fullKey, token, ttl, options);
+    this.activeLocks.add(lock);
+    return lock;
+  }
+  /**
+   * Executes function with automatic lock management.
+   */
+  async withLock(key, fn, options = {}) {
+    const lock = await this.acquire(key, options);
+    const holdStart = Date.now();
+    try {
+      return await fn();
+    } finally {
+      const holdDuration = (Date.now() - holdStart) / 1e3;
+      this.metrics?.observeHistogram("redisx_lock_hold_duration_seconds", holdDuration);
+      this.metrics?.decrementGauge("redisx_locks_active");
+      await lock.release().catch((error) => {
+        this.logger.error(`Lock release failed for ${key}:`, error);
+      }).finally(() => {
+        this.activeLocks.delete(lock);
+      });
+    }
+  }
+  /**
+   * Checks if key is locked.
+   */
+  async isLocked(key) {
+    const fullKey = this.buildKey(key);
+    return this.store.exists(fullKey);
+  }
+  /**
+   * Force releases lock without ownership check.
+   */
+  async forceRelease(key) {
+    const fullKey = this.buildKey(key);
+    return this.store.forceRelease(fullKey);
+  }
+  /**
+   * Creates lock instance with optional auto-renewal.
+   */
+  createLock(fullKey, token, ttl, options) {
+    const lock = new Lock(fullKey, token, ttl, this.store);
+    const autoRenewEnabled = options.autoRenew ?? this.config.autoRenew?.enabled ?? true;
+    if (autoRenewEnabled) {
+      const intervalFraction = this.config.autoRenew?.intervalFraction ?? 0.5;
+      const interval = ttl * intervalFraction;
+      lock.startAutoRenew(interval);
+    }
+    return lock;
+  }
+  /**
+   * Builds full lock key with prefix.
+   */
+  buildKey(key) {
+    const prefix = this.config.keyPrefix ?? "_lock:";
+    return `${prefix}${key}`;
+  }
+  /**
+   * Generates unique lock token.
+   */
+  generateToken() {
+    return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  }
+  /**
+   * Resolves TTL with defaults and limits.
+   */
+  resolveTtl(ttl) {
+    const resolvedTtl = ttl ?? this.config.defaultTtl ?? 3e4;
+    const maxTtl = this.config.maxTtl ?? 3e5;
+    return Math.min(resolvedTtl, maxTtl);
+  }
+  /**
+   * Resolves retry configuration.
+   */
+  resolveRetryConfig(options) {
+    return {
+      maxRetries: options.retry?.maxRetries ?? this.config.retry?.maxRetries ?? 3,
+      initialDelay: options.retry?.initialDelay ?? this.config.retry?.initialDelay ?? 100,
+      maxDelay: this.config.retry?.maxDelay ?? 3e3,
+      multiplier: this.config.retry?.multiplier ?? 2
+    };
+  }
+  /**
+   * Sleeps for specified milliseconds.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+LockService = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(LOCKS_PLUGIN_OPTIONS)),
+  __decorateParam(1, Inject(LOCK_STORE)),
+  __decorateParam(2, Optional()),
+  __decorateParam(2, Inject(METRICS_SERVICE)),
+  __decorateParam(3, Optional()),
+  __decorateParam(3, Inject(TRACING_SERVICE))
+], LockService);
+
+// src/lock/infrastructure/scripts/lua-scripts.ts
+var RELEASE_LOCK_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+else
+  return 0
+end
+`.trim();
+var EXTEND_LOCK_SCRIPT = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("pexpire", KEYS[1], ARGV[2])
+else
+  return 0
+end
+`.trim();
+
+// src/lock/infrastructure/adapters/redis-lock-store.adapter.ts
+var RedisLockStoreAdapter = class {
+  constructor(driver) {
+    this.driver = driver;
+  }
+  releaseSha = null;
+  extendSha = null;
+  /**
+   * Lifecycle hook: loads Lua scripts into Redis on initialization.
+   */
+  async onModuleInit() {
+    this.releaseSha = await this.driver.scriptLoad(RELEASE_LOCK_SCRIPT);
+    this.extendSha = await this.driver.scriptLoad(EXTEND_LOCK_SCRIPT);
+  }
+  /**
+   * Acquires lock using SET NX PX.
+   */
+  async acquire(key, token, ttlMs) {
+    const result = await this.driver.set(key, token, {
+      nx: true,
+      // Only set if key doesn't exist
+      px: ttlMs
+      // TTL in milliseconds
+    });
+    return result === "OK";
+  }
+  /**
+   * Releases lock if owned by token (Lua script).
+   */
+  async release(key, token) {
+    if (!this.releaseSha) {
+      this.releaseSha = await this.driver.scriptLoad(RELEASE_LOCK_SCRIPT);
+    }
+    const result = await this.driver.evalsha(this.releaseSha, [key], [token]);
+    return result === 1;
+  }
+  /**
+   * Extends lock TTL if owned by token (Lua script).
+   */
+  async extend(key, token, ttlMs) {
+    if (!this.extendSha) {
+      this.extendSha = await this.driver.scriptLoad(EXTEND_LOCK_SCRIPT);
+    }
+    const result = await this.driver.evalsha(this.extendSha, [key], [token, ttlMs]);
+    return result === 1;
+  }
+  /**
+   * Checks if lock key exists.
+   */
+  async exists(key) {
+    const count = await this.driver.exists(key);
+    return count > 0;
+  }
+  /**
+   * Checks if lock is held by specific token.
+   */
+  async isHeldBy(key, token) {
+    const value = await this.driver.get(key);
+    return value === token;
+  }
+  /**
+   * Force removes lock without ownership check.
+   */
+  async forceRelease(key) {
+    const count = await this.driver.del(key);
+    return count > 0;
+  }
+};
+RedisLockStoreAdapter = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(REDIS_DRIVER))
+], RedisLockStoreAdapter);
+
+// src/locks.plugin.ts
+var DEFAULT_LOCKS_CONFIG = {
+  defaultTtl: 3e4,
+  maxTtl: 3e5,
+  keyPrefix: "_lock:",
+  retry: {
+    maxRetries: 3,
+    initialDelay: 100,
+    maxDelay: 3e3,
+    multiplier: 2
+  },
+  autoRenew: {
+    enabled: true,
+    intervalFraction: 0.5
+  }
+};
+var LocksPlugin = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  name = "locks";
+  version = "0.1.0";
+  description = "Distributed locking with auto-renewal and retry strategies";
+  getProviders() {
+    const config = {
+      defaultTtl: this.options.defaultTtl ?? DEFAULT_LOCKS_CONFIG.defaultTtl,
+      maxTtl: this.options.maxTtl ?? DEFAULT_LOCKS_CONFIG.maxTtl,
+      keyPrefix: this.options.keyPrefix ?? DEFAULT_LOCKS_CONFIG.keyPrefix,
+      retry: {
+        ...DEFAULT_LOCKS_CONFIG.retry,
+        ...this.options.retry
+      },
+      autoRenew: {
+        ...DEFAULT_LOCKS_CONFIG.autoRenew,
+        ...this.options.autoRenew
+      }
+    };
+    return [
+      // Configuration
+      {
+        provide: LOCKS_PLUGIN_OPTIONS,
+        useValue: config
+      },
+      // Store adapter
+      {
+        provide: LOCK_STORE,
+        useClass: RedisLockStoreAdapter
+      },
+      // Application service
+      {
+        provide: LOCK_SERVICE,
+        useClass: LockService
+      },
+      // @WithLock decorator initialization (proxy-based)
+      LockDecoratorInitializerService,
+      // Reflector is needed for decorator metadata
+      Reflector
+    ];
+  }
+  getExports() {
+    return [LOCK_SERVICE];
+  }
+};
+
+export { LOCKS_PLUGIN_OPTIONS, LOCK_SERVICE, LockAcquisitionError, LockError, LockExpiredError, LockExtensionError, LockNotOwnedError, LockService, LocksPlugin, WithLock };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map