/**
 * Distributed lock interface
 */
export interface Lock {
  /**
   * Unique lock identifier
   */
  id: string;

  /**
   * Lock resource name
   */
  resource: string;

  /**
   * Time when the lock was acquired
   */
  acquiredAt: number;

  /**
   * Lock expiration time
   */
  expiresAt: number;

  /**
   * Lock owner identifier
   */
  owner: string;

  /**
   * Metadata associated with the lock
   */
  metadata?: Record<string, any>;
}

/**
 * Lock manager interface for distributed locking
 */
export interface LockManager {
  /**
   * Acquire a lock on a resource
   * @param resource Resource to lock
   * @param ttl Time-to-live for the lock in milliseconds
   * @param options Additional lock options
   * @returns Promise resolving to the acquired lock or null if not acquired
   */
  acquire(resource: string, ttl: number, options?: LockOptions): Promise<Lock | null>;

  /**
   * Release a previously acquired lock
   * @param lock The lock to release
   * @returns Promise resolving to true if the lock was released
   */
  release(lock: Lock): Promise<boolean>;

  /**
   * Extend the TTL of an existing lock
   * @param lock The lock to extend
   * @param ttl Additional time in milliseconds to add to the lock TTL
   * @returns Promise resolving to the updated lock or null if extension failed
   */
  extend(lock: Lock, ttl: number): Promise<Lock | null>;

  /**
   * Check if a lock exists on a resource
   * @param resource Resource to check
   * @returns Promise resolving to the existing lock or null if not locked
   */
  check(resource: string): Promise<Lock | null>;

  /**
   * Get all locks
   * @returns Promise resolving to a map of resource-to-lock mappings
   */
  getAll(): Promise<Map<string, Lock>>;

  /**
   * Clear all locks (for administrative purposes)
   * @returns Promise resolving to true if successful
   */
  clear(): Promise<boolean>;

  /**
   * Execute a function within a lock
   * @param resource Resource to lock
   * @param fn Function to execute with the lock
   * @param ttl Time-to-live for the lock in milliseconds
   * @param options Additional lock options
   * @returns Promise resolving to the function result
   */
  withLock<T>(
    resource: string,
    fn: (lock: Lock) => Promise<T>,
    ttl: number,
    options?: LockOptions
  ): Promise<T>;
}

/**
 * Lock acquisition options
 */
export interface LockOptions {
  /**
   * Whether to wait for the lock to be available (default: false)
   */
  wait?: boolean;

  /**
   * Maximum time to wait for the lock in milliseconds
   */
  waitTimeout?: number;

  /**
   * Time between retry attempts in milliseconds
   */
  retryDelay?: number;

  /**
   * Maximum number of retry attempts
   */
  maxRetries?: number;

  /**
   * Custom owner identifier for the lock
   */
  owner?: string;

  /**
   * Additional metadata to store with the lock
   */
  metadata?: Record<string, any>;

  /**
   * Whether to automatically extend the lock while held (default: false)
   */
  autoExtend?: boolean;

  /**
   * How often to extend the lock in milliseconds (if autoExtend is true)
   */
  autoExtendInterval?: number;

  /**
   * Force acquire the lock, even if it's already held (use with caution)
   */
  force?: boolean;
}