feat: add AsyncDisposable support for automatic lock cleanup (#13)

Author: koistya

.github/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thanks for your interest in contributing! This guide will help you get started.
 - **Bun**: Install from [bun.sh](https://bun.sh)
 - **Docker** (for integration tests): Any recent version
 - **PostgreSQL** (for integration tests): 14+ running on localhost:5432
-- **Node.js**: 18+ (Bun handles this, but good to have)
+- **Node.js**: 20+ (Bun handles this, but good to have)
 
 ## Quick Start
 

README.md

@@ -84,23 +84,50 @@ await lock(
 );
 ```
 
-### Manual Lock Control
+### Manual Lock Control with Automatic Cleanup
+
+Use `await using` for automatic cleanup on all code paths (Node.js ≥20):
 
 ```typescript
 const backend = createRedisBackend(redis);
 
-// Acquire lock manually
+// Lock automatically released on scope exit
+{
+  await using lock = await backend.acquire({
+    key: "batch:daily-report",
+    ttlMs: 300000, // 5 minutes
+  });
+
+  if (lock.ok) {
+    // TypeScript narrows lock to include handle methods after ok check
+    const { fence } = lock; // Fencing token for stale lock protection
+
+    await generateDailyReport(fence);
+
+    // Extend lock for long-running tasks
+    await lock.extend(300000);
+    await sendReportEmail();
+
+    // Lock released automatically here
+  } else {
+    console.log("Resource is locked by another process");
+  }
+}
+```
+
+**For older runtimes (Node.js <20)**, use try/finally:
+
+```typescript
 const result = await backend.acquire({
   key: "batch:daily-report",
-  ttlMs: 300000, // 5 minutes
+  ttlMs: 300000,
 });
 
 if (result.ok) {
   try {
-    const { lockId, fence } = result; // Fencing token for stale lock protection
+    const { lockId, fence } = result;
     await generateDailyReport(fence);
 
-    // Extend lock for long-running tasks
     const extended = await backend.extend({ lockId, ttlMs: 300000 });
     if (!extended.ok) {
       throw new Error("Failed to extend lock");
@@ -115,6 +142,25 @@ if (result.ok) {
 }
 ```
 
+**Error callbacks** for disposal failures:
+
+```typescript
+const backend = createRedisBackend(redis, {
+  onReleaseError: (error, context) => {
+    logger.error("Failed to release lock", {
+      error,
+      lockId: context.lockId,
+      key: context.key,
+    });
+  },
+});
+
+// All acquisitions automatically use the error callback
+await using lock = await backend.acquire({ key: "resource", ttlMs: 30000 });
+```
+
+**Note:** SyncGuard provides a safe-by-default error handler that automatically logs disposal failures in development mode (`NODE_ENV !== 'production'`). In production, enable logging with `SYNCGUARD_DEBUG=true` or provide a custom `onReleaseError` callback integrated with your observability stack.
+
 ### Ownership Checking
 
 ```typescript
@@ -134,12 +180,22 @@ if (info) {
 
 ```typescript
 // Basic lock options
-await lock(workFn, {
-  key: "resource:123", // Required: unique identifier
-  ttlMs: 30000, // Lock duration (default: 30s)
-  timeoutMs: 5000, // Max acquisition wait (default: 5s)
-  maxRetries: 10, // Retry attempts (default: 10)
-});
+await lock(
+  async () => {
+    // Your critical section
+  },
+  {
+    key: "resource:123", // Required: unique identifier
+    ttlMs: 30000, // Lock duration (default: 30s)
+    acquisition: {
+      timeoutMs: 5000, // Max acquisition wait (default: 5s)
+      maxRetries: 10, // Retry attempts (default: 10)
+      retryDelayMs: 100, // Initial retry delay (default: 100ms)
+      backoff: "exponential", // Backoff strategy: "exponential" | "fixed" (default: "exponential")
+      jitter: "equal", // Jitter strategy: "equal" | "full" | "none" (default: "equal")
+    },
+  },
+);
 ```
 
 ### Backend Configuration
@@ -236,7 +292,7 @@ const checkRateLimit = async (userId: string) => {
 
 - 🔒 **Bulletproof concurrency** - Atomic operations prevent race conditions
 - 🛡️ **Fencing tokens** - Monotonic counters protect against stale writes
-- 🧹 **Automatic cleanup** - TTL-based expiration, no manual cleanup needed
+- 🧹 **Automatic cleanup** - TTL-based expiration + `await using` (AsyncDisposable) support
 - 🔄 **Backend flexibility** - Redis (performance), PostgreSQL (zero overhead), or Firestore (serverless)
 - 🔁 **Smart retries** - Exponential backoff with jitter handles contention
 - 💙 **TypeScript-first** - Full type safety with compile-time guarantees

common/auto-lock.ts

@@ -9,9 +9,40 @@ import type {
   BackendCapabilities,
   LockBackend,
   LockConfig,
+  OnReleaseError,
 } from "./types.js";
 import { normalizeAndValidateKey } from "./validation.js";
 
+/**
+ * Default error handler for disposal failures in lock() helper.
+ * Provides safe-by-default observability without requiring user configuration.
+ *
+ * **Behavior**:
+ * - Development (NODE_ENV !== 'production'): Logs all disposal errors to console.error
+ * - Production: Silent by default, opt-in via SYNCGUARD_DEBUG=true environment variable
+ * - Security: Omits sensitive context (key, lockId) from logs by default
+ *
+ * **Note**: This is shared with the disposable.ts default handler for consistency.
+ *
+ * @see common/disposable.ts - Full documentation of default handler behavior
+ */
+const defaultDisposalErrorHandler: OnReleaseError = (err, ctx) => {
+  // Only log in development or when explicitly enabled via env var
+  const shouldLog =
+    process.env.NODE_ENV !== "production" ||
+    process.env.SYNCGUARD_DEBUG === "true";
+
+  if (shouldLog) {
+    console.error("[SyncGuard] Lock disposal failed:", {
+      error: err.message,
+      errorName: err.name,
+      source: ctx.source,
+      // Omit key and lockId to avoid leaking sensitive data in logs
+      // Users should provide custom callback for full context
+    });
+  }
+};
+
 /**
  * Auto-managed lock with retry logic for acquisition contention.
  * Backends perform single-attempt operations (ADR-009), retries handled here.
@@ -209,13 +240,28 @@ export async function lock<T, C extends BackendCapabilities>(
     try {
       await backend.release({ lockId, signal: config.signal });
     } catch (releaseError) {
-      if (config.onReleaseError) {
-        const error =
-          releaseError instanceof Error
-            ? releaseError
-            : new Error(String(releaseError));
+      // Always notify callback of disposal failure (uses default if not configured)
+      // This ensures consistent observability across low-level and high-level APIs
+      const errorHandler = config.onReleaseError ?? defaultDisposalErrorHandler;
+
+      try {
+        // Normalize to Error instance and preserve original for debugging
+        let normalizedError: Error;
+        if (releaseError instanceof Error) {
+          normalizedError = releaseError;
+        } else {
+          normalizedError = new Error(String(releaseError));
+          // Preserve original error for debugging
+          (normalizedError as any).originalError = releaseError;
+        }
 
-        config.onReleaseError(error, { lockId, key: normalizedKey });
+        errorHandler(normalizedError, {
+          lockId,
+          key: normalizedKey,
+          source: "disposal", // Automatic cleanup, not manual
+        });
+      } catch {
+        // Swallow callback errors - user's callback is responsible for safe error handling
       }
       // Swallow release errors: TTL cleanup handles orphaned locks
     }

common/backend.ts

@@ -13,6 +13,7 @@ export { createAutoLock, lock } from "./auto-lock.js";
 export * from "./config.js";
 export * from "./constants.js";
 export * from "./crypto.js";
+export * from "./disposable.js";
 export * from "./errors.js";
 export * from "./helpers.js";
 export * from "./telemetry.js";