Skip to content

v1.0.0

Choose a tag to compare

@koistya koistya released this 29 Sep 20:00
· 19 commits to main since this release
87dc020

🎯 Major API Redesign

This release represents a comprehensive overhaul of SyncGuard with significant breaking changes, enhanced type safety, and improved functionality.

Breaking Changes

1. New Result-Based Error Handling

  • Replaced exception-heavy error handling with discriminated union types (LockResult<T>)
  • Backend operations now return structured results instead of throwing
  • Example migration:
    // Before
    const lock = createLock(backend);
    await lock(workFn, { key: "resource:123" });
    
    // After
    const backend = createRedisBackend(redis);
    const result = await backend.acquire({ key: "resource:123" });
    if (result.ok) {
      // Use result.lockId and result.fence
    }

2. Fencing Token Support

  • All operations now support fencing tokens for stale lock protection
  • Compile-time type safety: result.fence is guaranteed when supportsFencing: true
  • Requires schema updates for existing deployments (new fence_counters collection/keys)

3. Enhanced Lookup Operations

  • Renamed get-lock-info.ts → lookup.ts in both backends
  • New unified lookup interface supporting both key-based and lockId-based queries
  • Added owns() and getByKey() helper functions

4. Restructured Common Module
Split monolithic common/backend.ts into focused modules:

  • types.ts - Core interfaces and types
  • constants.ts - Configuration constants
  • errors.ts - LockError class
  • validation.ts - Key & lockId validation
  • crypto.ts - Cryptographic functions
  • helpers.ts - Utility functions
  • auto-lock.ts - Auto-managed locks
  • config.ts - Configuration helpers
  • telemetry.ts - Observability decorators

✨ New Features

Fencing Tokens

  • Protect against stale lock scenarios in distributed systems
  • Lexicographic string comparison (fence > prevFence)
  • 19-digit zero-padded format for cross-language compatibility

Enhanced Type Safety

  • Parameterized result types by backend capabilities
  • Direct result.fence access without runtime assertions
  • Improved error codes with structured reasons

Lookup Operations

  • O(1) key-based lookup: getByKey(backend, key)
  • Ownership verification: owns(backend, lockId)
  • Debug access: lookupDebug() for raw lock data

Opt-In Telemetry

  • Zero-cost abstraction when disabled
  • Decorator pattern: withTelemetry(backend, options)
  • Async event callbacks that never block operations

🏗️ Architecture Improvements

ADR Documentation

Added 9 Architectural Decision Records covering:

  • Explicit ownership re-verification (ADR-003)
  • Lexicographic fence comparison (ADR-004-R2)
  • Unified time tolerance (ADR-005)
  • Mandatory uniform key truncation (ADR-006)
  • Opt-in telemetry (ADR-007)
  • Compile-time fencing contract (ADR-008)
  • Retry logic in helpers only (ADR-009)

Backend Operations

  • Atomicity improvements in both Redis (Lua scripts) and Firestore (transactions)
  • Centralized error mapping for consistent error handling
  • Script caching optimization for Redis operations
  • Enhanced test coverage with integration and performance tests

📚 Documentation

New Specifications

  • specs/interface.md - Complete LockBackend API contracts & usage patterns
  • Updated specs/firestore.md - Enhanced Firestore implementation requirements
  • Updated specs/redis.md - Enhanced Redis implementation requirements
  • specs/adrs.md - Architectural decision records

Updated Examples

  • Comprehensive usage examples for both Redis and Firestore
  • Manual lock control patterns
  • Ownership checking examples
  • Rate limiting and job processing patterns

🧪 Testing Infrastructure

New Test Suites

  • Unit tests: bun run test:unit (fast, mocked dependencies)
  • Integration tests: bun run test:integration (Redis + Firestore emulator)
  • Performance tests: bun run test:performance (benchmarks)

CI/CD Enhancements

  • Added Firestore emulator to CI pipeline
  • Redis service containers for integration testing
  • Separate workflows for unit and integration tests

📦 Installation & Migration

New Dependencies

# Firestore backend
npm install syncguard @google-cloud/firestore

# Redis backend
npm install syncguard ioredis

Migration Guide

For Auto-Managed Locks:

// Still works - minimal changes required
import { createLock } from "syncguard/redis";
const lock = createLock(redis);
await lock(workFn, { key: "resource:123" });

For Manual Lock Control:

// Before
const result = await lock.acquire({ key: "batch:daily" });
if (result.success) {
  try {
    await work();
  } finally {
    await lock.release(result.lockId);
  }
}

// After
const backend = createRedisBackend(redis);
const result = await backend.acquire({ key: "batch:daily" });
if (result.ok) {
  try {
    const { lockId, fence } = result; // Now with fencing!
    await work(fence);
  } finally {
    await backend.release({ lockId });
  }
}

Error Handling:

// result.ok replaced result.success
// result.reason provides structured error information
if (!result.ok) {
  console.log(`Lock failed: ${result.reason}`);
}

⚠️ Required Schema Updates

Firestore

Add new collection for fence counters (default: fence_counters):

const lock = createLock(db, {
  collection: "locks",
  fenceCollection: "fence_counters" // New!
});

Redis

Fence counters use existing key-value store with configurable prefix:

const lock = createLock(redis, {
  keyPrefix: "myapp" // Default: "syncguard"
});

🔍 What's Next

This release establishes a solid foundation for v1.0. Future work will focus on:

  • Additional backend implementations (PostgreSQL, DynamoDB)
  • Performance optimizations
  • Enhanced observability features
  • Production deployment guides

📊 Statistics

  • 64 files changed
  • 9,097 additions, 1,735 deletions
  • 9 new ADRs documenting architectural decisions
  • 3 new test suites (unit, integration, performance)
  • 1,293 lines of new interface documentation

🙏 Acknowledgments

This release represents a complete rethink of the distributed locking API, prioritizing:

  • Type safety and compile-time guarantees
  • Predictable cross-backend behavior
  • Production-grade fencing token support
  • Clear architectural documentation

Special thanks to early adopters who provided feedback that shaped this redesign.