syncguard
Version:
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.
66 lines (65 loc) • 2.51 kB
TypeScript
/**
* Symbol for attaching failure reason metadata to results without polluting public API.
* Enables telemetry decorator to track failure reasons without exposing them to users.
*/
export declare const FAILURE_REASON: unique symbol;
/** Internal tracking for telemetry events (not in public result types) */
export type MutationReason = "expired" | "not-found";
/**
* Internal state taxonomy mapping backend observations to user-facing reasons.
* DO NOT export in public API - used only by telemetry/mapping layers.
*/
export type MutationCondition = "succeeded"
/** Expiry observed deterministically before mutation */
| "observable-expired"
/** No record found in storage */
| "never-existed"
/** Record exists but lockId mismatch */
| "ownership-mismatch"
/** Auto-removed due to expiry */
| "cleaned-up-after-expiry"
/** Clock skew, snapshot race, stale index, etc. */
| "ambiguous-unknown";
export type MutationResult = {
ok: true;
} | {
ok: false;
reason: MutationReason;
};
/**
* Maps internal backend conditions to public API results.
* Conservative strategy: collapses ambiguous states to "not-found" for safety.
*/
export declare function mapToMutationResult(cond: MutationCondition): MutationResult;
/**
* Decodes Redis Lua script return codes to MutationCondition.
* @param code - Script result: 1=success, 0=ownership mismatch, -1=not found, -2=expired
* @see redis/scripts.ts
*/
export declare function mapRedisScriptResult(code: number): MutationCondition;
/**
* Maps Firestore transaction/query observations to MutationCondition.
* @param conditions - Query result analysis
* @param conditions.documentExists - !querySnapshot.empty
* @param conditions.ownershipValid - data?.lockId === lockId
* @param conditions.isLive - Computed via time authority + tolerance
* @see common/time-predicates.ts
*/
export declare function mapFirestoreConditions(conditions: {
/** Document found in query result */
documentExists: boolean;
/** Stored lockId matches request */
ownershipValid: boolean;
/** Lock not expired per time authority */
isLive: boolean;
}): MutationCondition;
/**
* Unified backend observation mapper for Redis codes or Firestore conditions.
* @param observation - Redis script code or Firestore query analysis
* @see docs/specs/interface.md
*/
export declare function mapBackendObservation(observation: number | {
documentExists: boolean;
ownershipValid: boolean;
isLive: boolean;
}): MutationCondition;