syncguard/postgres/operations/lookup.d.ts

Functional TypeScript library for distributed locking across microservices. Prevents race conditions with Redis, PostgreSQL, Firestore, and custom backends. Features automatic lock management, timeout handling, and extensible architecture.

import type { Sql } from "postgres";
import { type KeyLookup, type LockInfo, type OwnershipLookup } from "../../common/backend.js";
import type { PostgresCapabilities, PostgresConfig } from "../types.js";
/**
 * Creates lookup operation for PostgreSQL backend.
 *
 * **Dual-mode operation:**
 * - Key lookup: Direct query by key (O(1) via primary key)
 * - LockId lookup: Query by lockId using index
 *
 * **Implementation Pattern:**
 * - Non-atomic (acceptable for diagnostic-only lookups per ADR-011)
 * - Returns sanitized LockInfo with hashed key/lockId
 * - Attaches raw data for debugging purposes
 * - Uses server time for liveness check
 * - Returns null for non-existent or expired locks
 *
 * Flow:
 * 1. Determine lookup mode (key vs lockId)
 * 2. Validate and normalize input
 * 3. Query database (key: primary key, lockId: index)
 * 4. Check liveness using server time
 * 5. Sanitize and return LockInfo or null
 *
 * @param sql - postgres.js SQL instance
 * @param config - PostgreSQL backend configuration
 * @returns Lookup operation function
 *
 * @see docs/specs/interface.md#lookup-operation-requirements - Normative requirements
 */
export declare function createLookupOperation(sql: Sql, config: PostgresConfig): (opts: KeyLookup | OwnershipLookup) => Promise<LockInfo<PostgresCapabilities> | null>;