Repository navigation
v1.0.0
🎯 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.fenceis guaranteed whensupportsFencing: true - Requires schema updates for existing deployments (new
fence_counterscollection/keys)
3. Enhanced Lookup Operations
- Renamed
get-lock-info.ts→lookup.tsin both backends - New unified lookup interface supporting both key-based and lockId-based queries
- Added
owns()andgetByKey()helper functions
4. Restructured Common Module
Split monolithic common/backend.ts into focused modules:
types.ts- Core interfaces and typesconstants.ts- Configuration constantserrors.ts- LockError classvalidation.ts- Key & lockId validationcrypto.ts- Cryptographic functionshelpers.ts- Utility functionsauto-lock.ts- Auto-managed locksconfig.ts- Configuration helperstelemetry.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.fenceaccess 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 ioredisMigration 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.