🛡️ IronGuard

Unbreakable TypeScript compile-time lock order violation detection system with runtime mutual exclusion. Prevents both deadlocks (through compile-time validation) and race conditions (through async mutual exclusion).

Installation

``bash
npm install @markdrei/ironguard-typescript-locks
`

Quick Start

`typescript
import {
createLockContext,
LOCK_1,
LOCK_3,
type LockContext
} from '@markdrei/ironguard-typescript-locks';

// Basic lock acquisition with automatic cleanup
async function example(): Promise {
const ctx0 = createLockContext();

await ctx0.useLockWithAcquire(LOCK_1, async (ctx1) => {
console.log(Holding: [${ctx1.getHeldLocks()}]); // [1]

await ctx1.useLockWithAcquire(LOCK_3, async (ctx13) => {
console.log(Holding: [${ctx13.getHeldLocks()}]); // [1, 3]
// Use locks here
}); // LOCK_3 auto-released
}); // LOCK_1 auto-released
}
`

What It Delivers

- Compile-time deadlock prevention: TypeScript type system enforces lock ordering
- Runtime thread safety: Async mutual exclusion prevents race conditions
- Read/write lock semantics: Concurrent readers with writer preference
- Context transfer validation: Type-safe function parameters with lock requirements
- Flexible lock patterns: Sequential acquisition, lock skipping, temporary elevation
- 15 lock levels supported: LOCK_1 through LOCK_15 available
- Production-ready: Clean API, comprehensive testing, proper resource management

Core Features

$3

For fine-grained control, acquire and release locks explicitly:

`typescript
const ctx1 = await createLockContext().acquireWrite(LOCK_1);
try {
const ctx13 = await ctx1.acquireWrite(LOCK_3);
try {
// Use locks here
} finally {
ctx13.releaseLock(LOCK_3); // Release only LOCK_3
}
} finally {
ctx1.releaseLock(LOCK_1); // Release only LOCK_1
}
`

$3

Full read/write lock support with concurrent readers and writer preference:

`typescript
// Multiple readers can hold the same lock simultaneously
const reader1 = await createLockContext().acquireRead(LOCK_3);
const reader2 = await createLockContext().acquireRead(LOCK_3); // ✅ Concurrent

// Writers get priority over new readers
const writer = await createLockContext().acquireWrite(LOCK_3); // ⏳ Waits for readers
`

$3

Pass lock contexts between functions with compile-time validation:

`typescript
import type { LocksAtMost5, HasLock3Context } from '@markdrei/ironguard-typescript-locks';

// Accepts any ordered combination of locks 1-5
async function middleProcessor(context: LockContext): Promise {
// Can acquire locks > 5
const withLock6 = await context.acquireWrite(LOCK_6);
try {
// Use locks
} finally {
withLock6.releaseLock(LOCK_6);
}
}

// Requires LOCK_3 to be held
function processData(
ctx: HasLock3Context
): void {
ctx.useLock(LOCK_3, () => {
// TypeScript guarantees LOCK_3 is present
});
}
`

$3

`typescript
// Pre-defined types for locks 1-9
import type { LocksAtMost1, LocksAtMost5, LocksAtMost9 } from '@markdrei/ironguard-typescript-locks';

// Nullable types for locks 10-15 (performance optimization)
import type { NullableLocksAtMost10, NullableLocksAtMost15 } from '@markdrei/ironguard-typescript-locks';

// Ensure specific locks are held
import type { HasLock3Context, HasLock11Context } from '@markdrei/ironguard-typescript-locks';
`

What's Missing

- Performance benchmarks for high-contention scenarios
- Lock timeout/cancellation mechanisms
- Lock priority/scheduling policies

Commands

`bash

See IronGuard in action

npm run examples

Run all tests

npm test

Run compile-time validation tests

npm run test:compile

Build the project

npm run build
``

Documentation

- Quick Start Guide - Essential features and usage patterns
- Debugging Guide - Debug mode and stack trace capture for lock analysis
- Lock Context Transfer Patterns - Guide to passing contexts between functions using LocksAtMost and NullableLocksAtMost types
- Read/Write Lock Best Practices - Concurrent readers and writer preference
- Compile-time Testing Guide - How to validate TypeScript lock safety
- Changelog - Version history and release notes

License

MIT