@zdavison/matador 2.0.1

package/dist/core/shutdown.test.js

@@ -0,0 +1,524 @@
+import { beforeEach, describe, expect, it, mock } from 'bun:test';
+import { ShutdownManager } from './shutdown.js';
+describe('ShutdownManager', () => {
+    let getEnqueueCount;
+    let stopReceiving;
+    let disconnectTransport;
+    let manager;
+    let enqueuedCount;
+    beforeEach(() => {
+        enqueuedCount = 0;
+        getEnqueueCount = mock(() => enqueuedCount);
+        stopReceiving = mock(async () => { });
+        disconnectTransport = mock(async () => { });
+    });
+    describe('static factory', () => {
+        it('should create instance via static create method', () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            expect(manager).toBeInstanceOf(ShutdownManager);
+            expect(manager.state).toBe('running');
+        });
+        it('should accept partial config overrides', () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, { gracefulShutdownTimeout: 5000 });
+            expect(manager).toBeInstanceOf(ShutdownManager);
+        });
+    });
+    describe('initial state', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should start in running state', () => {
+            expect(manager.state).toBe('running');
+        });
+        it('should allow enqueue initially', () => {
+            expect(manager.isEnqueueAllowed).toBe(true);
+        });
+        it('should report idle when no events processing', () => {
+            const state = manager.getHandlersState();
+            expect(state.isIdle).toBe(true);
+            expect(state.eventsBeingProcessed).toBe(0);
+            expect(state.eventsBeingEnqueued).toBe(0);
+        });
+    });
+    describe('getHandlersState', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should return correct handler state with no activity', () => {
+            const state = manager.getHandlersState();
+            expect(state.eventsBeingProcessed).toBe(0);
+            expect(state.eventsBeingEnqueued).toBe(0);
+            expect(state.isIdle).toBe(true);
+        });
+        it('should track events being processed', () => {
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            const state = manager.getHandlersState();
+            expect(state.eventsBeingProcessed).toBe(2);
+            expect(state.isIdle).toBe(false);
+        });
+        it('should track events being enqueued via callback', () => {
+            enqueuedCount = 3;
+            const state = manager.getHandlersState();
+            expect(state.eventsBeingEnqueued).toBe(3);
+            expect(state.isIdle).toBe(false);
+        });
+        it('should report not idle when processing exists', () => {
+            manager.incrementProcessing();
+            enqueuedCount = 0;
+            const state = manager.getHandlersState();
+            expect(state.isIdle).toBe(false);
+        });
+        it('should report not idle when enqueuing exists', () => {
+            enqueuedCount = 2;
+            const state = manager.getHandlersState();
+            expect(state.isIdle).toBe(false);
+        });
+        it('should report idle only when both counters are zero', () => {
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            enqueuedCount = 1;
+            let state = manager.getHandlersState();
+            expect(state.isIdle).toBe(false);
+            manager.decrementProcessing();
+            state = manager.getHandlersState();
+            expect(state.isIdle).toBe(false);
+            manager.decrementProcessing();
+            state = manager.getHandlersState();
+            expect(state.isIdle).toBe(false);
+            enqueuedCount = 0;
+            state = manager.getHandlersState();
+            expect(state.isIdle).toBe(true);
+        });
+    });
+    describe('processing counter', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should increment processing counter', () => {
+            manager.incrementProcessing();
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(1);
+            manager.incrementProcessing();
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(2);
+        });
+        it('should decrement processing counter', () => {
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            manager.decrementProcessing();
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(2);
+            manager.decrementProcessing();
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(1);
+        });
+    });
+    describe('graceful shutdown', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should transition through all shutdown states', async () => {
+            const states = [];
+            const checkState = async () => {
+                states.push(manager.state);
+            };
+            stopReceiving = mock(async () => {
+                await checkState();
+            });
+            disconnectTransport = mock(async () => {
+                await checkState();
+            });
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            const initialState = manager.state;
+            await manager.shutdown();
+            const finalState = manager.state;
+            expect(initialState).toBe('running');
+            expect(states[0]).toBe('stopping-receive');
+            expect(states[1]).toBe('disconnecting');
+            expect(finalState).toBe('stopped');
+        });
+        it('should call stopReceiving during shutdown', async () => {
+            await manager.shutdown();
+            expect(stopReceiving).toHaveBeenCalledTimes(1);
+        });
+        it('should call disconnectTransport during shutdown', async () => {
+            await manager.shutdown();
+            expect(disconnectTransport).toHaveBeenCalledTimes(1);
+        });
+        it('should disable enqueue during shutdown', async () => {
+            expect(manager.isEnqueueAllowed).toBe(true);
+            await manager.shutdown();
+            expect(manager.isEnqueueAllowed).toBe(false);
+        });
+        it('should wait for in-flight messages to complete', async () => {
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            const shutdownPromise = manager.shutdown();
+            expect(manager.state).toBe('stopping-receive');
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            manager.decrementProcessing();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            manager.decrementProcessing();
+            await shutdownPromise;
+            expect(manager.state).toBe('stopped');
+        });
+        it('should wait for enqueued messages to complete', async () => {
+            enqueuedCount = 2;
+            const shutdownPromise = manager.shutdown();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            enqueuedCount = 0;
+            await shutdownPromise;
+            expect(manager.state).toBe('stopped');
+        });
+        it('should wait for both processing and enqueued to complete', async () => {
+            manager.incrementProcessing();
+            enqueuedCount = 1;
+            const shutdownPromise = manager.shutdown();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            manager.decrementProcessing();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            enqueuedCount = 0;
+            await shutdownPromise;
+            expect(manager.state).toBe('stopped');
+        });
+    });
+    describe('shutdown timeout', () => {
+        it('should force shutdown after timeout', async () => {
+            const logs = [];
+            const mockLogger = {
+                debug: (msg) => logs.push(`debug: ${msg}`),
+                info: (msg) => logs.push(`info: ${msg}`),
+                warn: (msg) => logs.push(`warn: ${msg}`),
+                error: (msg) => logs.push(`error: ${msg}`),
+            };
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 100,
+                idlePollingInterval: 20,
+                logger: mockLogger,
+            });
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            await manager.shutdown();
+            expect(manager.state).toBe('stopped');
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(2);
+            expect(logs.some((log) => log.includes('Shutdown timeout reached'))).toBe(true);
+            expect(logs.some((log) => log.includes('2 events still processing'))).toBe(true);
+        });
+        it('should use custom timeout configuration', async () => {
+            const logs = [];
+            const mockLogger = {
+                debug: () => { },
+                info: () => { },
+                warn: (msg) => logs.push(msg),
+                error: () => { },
+            };
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 50,
+                idlePollingInterval: 10,
+                logger: mockLogger,
+            });
+            manager.incrementProcessing();
+            const startTime = Date.now();
+            await manager.shutdown();
+            const duration = Date.now() - startTime;
+            expect(duration).toBeGreaterThanOrEqual(50);
+            expect(duration).toBeLessThan(200);
+            expect(logs.length).toBeGreaterThan(0);
+        });
+        it('should poll at configured interval', async () => {
+            let pollCount = 0;
+            const countingGetEnqueueCount = mock(() => {
+                pollCount++;
+                return 1;
+            });
+            manager = new ShutdownManager(countingGetEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 100,
+                idlePollingInterval: 20,
+            });
+            await manager.shutdown();
+            expect(pollCount).toBeGreaterThan(3);
+        });
+    });
+    describe('idempotent shutdown', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should be idempotent when called multiple times', async () => {
+            await manager.shutdown();
+            expect(manager.state).toBe('stopped');
+            await manager.shutdown();
+            expect(manager.state).toBe('stopped');
+            await manager.shutdown();
+            expect(manager.state).toBe('stopped');
+            expect(stopReceiving).toHaveBeenCalledTimes(1);
+            expect(disconnectTransport).toHaveBeenCalledTimes(1);
+        });
+        it('should handle concurrent shutdown calls', async () => {
+            const results = await Promise.all([
+                manager.shutdown(),
+                manager.shutdown(),
+                manager.shutdown(),
+            ]);
+            expect(manager.state).toBe('stopped');
+            expect(results).toHaveLength(3);
+            expect(stopReceiving).toHaveBeenCalledTimes(1);
+            expect(disconnectTransport).toHaveBeenCalledTimes(1);
+        });
+        it('should not restart shutdown sequence if already shutting down', async () => {
+            manager.incrementProcessing();
+            const shutdown1 = manager.shutdown();
+            expect(manager.state).toBe('stopping-receive');
+            const shutdown2 = manager.shutdown();
+            manager.decrementProcessing();
+            await Promise.all([shutdown1, shutdown2]);
+            expect(manager.state).toBe('stopped');
+            expect(stopReceiving).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('forceStop', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should stop immediately without waiting', async () => {
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            enqueuedCount = 5;
+            await manager.forceStop();
+            expect(manager.state).toBe('stopped');
+            expect(manager.isEnqueueAllowed).toBe(false);
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(2);
+            expect(manager.getHandlersState().eventsBeingEnqueued).toBe(5);
+        });
+        it('should call stopReceiving', async () => {
+            await manager.forceStop();
+            expect(stopReceiving).toHaveBeenCalledTimes(1);
+        });
+        it('should call disconnectTransport', async () => {
+            await manager.forceStop();
+            expect(disconnectTransport).toHaveBeenCalledTimes(1);
+        });
+        it('should complete much faster than graceful shutdown', async () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 1000,
+            });
+            manager.incrementProcessing();
+            const startTime = Date.now();
+            await manager.forceStop();
+            const duration = Date.now() - startTime;
+            expect(duration).toBeLessThan(100);
+        });
+        it('should disable enqueue', async () => {
+            expect(manager.isEnqueueAllowed).toBe(true);
+            await manager.forceStop();
+            expect(manager.isEnqueueAllowed).toBe(false);
+        });
+    });
+    describe('state transitions', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should follow correct sequence: running -> stopping-receive -> waiting-handlers -> stopping-enqueue -> disconnecting -> stopped', async () => {
+            const states = [];
+            states.push(manager.state);
+            const originalStopReceiving = stopReceiving;
+            const originalDisconnect = disconnectTransport;
+            stopReceiving = mock(async () => {
+                await originalStopReceiving();
+                states.push(manager.state);
+            });
+            disconnectTransport = mock(async () => {
+                await originalDisconnect();
+                states.push(manager.state);
+            });
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            manager.incrementProcessing();
+            const shutdownPromise = manager.shutdown();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            states.push(manager.state);
+            manager.decrementProcessing();
+            await shutdownPromise;
+            states.push(manager.state);
+            expect(states[0]).toBe('running');
+            expect(states[1]).toBe('stopping-receive');
+            expect(states[2]).toBe('waiting-handlers');
+            expect(states[3]).toBe('disconnecting');
+            expect(states[4]).toBe('stopped');
+        });
+        it('should remain in waiting-handlers while events are processing', async () => {
+            manager.incrementProcessing();
+            const shutdownPromise = manager.shutdown();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            manager.decrementProcessing();
+            await shutdownPromise;
+            expect(manager.state).toBe('stopped');
+        });
+    });
+    describe('event handler deregistration during shutdown', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should block new enqueue operations after stopping-enqueue state', async () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                idlePollingInterval: 20,
+            });
+            manager.incrementProcessing();
+            expect(manager.isEnqueueAllowed).toBe(true);
+            const shutdownPromise = manager.shutdown();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            expect(manager.state).toBe('waiting-handlers');
+            expect(manager.isEnqueueAllowed).toBe(true);
+            manager.decrementProcessing();
+            await shutdownPromise;
+            expect(manager.state).toBe('stopped');
+            expect(manager.isEnqueueAllowed).toBe(false);
+        });
+        it('should allow completion of in-flight events during shutdown', async () => {
+            manager.incrementProcessing();
+            manager.incrementProcessing();
+            const initialCount = manager.getHandlersState().eventsBeingProcessed;
+            const shutdownPromise = manager.shutdown();
+            await new Promise((resolve) => setTimeout(resolve, 50));
+            manager.decrementProcessing();
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(initialCount - 1);
+            manager.decrementProcessing();
+            await shutdownPromise;
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(0);
+            expect(manager.state).toBe('stopped');
+        });
+    });
+    describe('configuration', () => {
+        it('should use default configuration when none provided', () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            expect(manager).toBeInstanceOf(ShutdownManager);
+        });
+        it('should accept custom gracefulShutdownTimeout', async () => {
+            const logs = [];
+            const mockLogger = {
+                debug: () => { },
+                info: () => { },
+                warn: (msg) => logs.push(msg),
+                error: () => { },
+            };
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 10,
+                idlePollingInterval: 5,
+                logger: mockLogger,
+            });
+            manager.incrementProcessing();
+            const startTime = Date.now();
+            await manager.shutdown();
+            const duration = Date.now() - startTime;
+            expect(duration).toBeGreaterThanOrEqual(10);
+            expect(duration).toBeLessThan(100);
+        });
+        it('should accept custom logger', async () => {
+            const logs = [];
+            const mockLogger = {
+                debug: (msg) => logs.push(msg),
+                info: (msg) => logs.push(msg),
+                warn: (msg) => logs.push(msg),
+                error: (msg) => logs.push(msg),
+            };
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 50,
+                logger: mockLogger,
+            });
+            manager.incrementProcessing();
+            await manager.shutdown();
+            expect(logs.some((log) => log.includes('Shutdown timeout reached'))).toBe(true);
+        });
+        it('should accept custom idlePollingInterval', async () => {
+            let pollCount = 0;
+            const countingGetEnqueueCount = mock(() => {
+                pollCount++;
+                if (pollCount > 2) {
+                    return 0;
+                }
+                return 1;
+            });
+            manager = new ShutdownManager(countingGetEnqueueCount, stopReceiving, disconnectTransport, {
+                idlePollingInterval: 10,
+                gracefulShutdownTimeout: 1000,
+            });
+            const startTime = Date.now();
+            await manager.shutdown();
+            const duration = Date.now() - startTime;
+            expect(pollCount).toBeGreaterThanOrEqual(2);
+            expect(duration).toBeGreaterThanOrEqual(20);
+            expect(duration).toBeLessThan(200);
+        });
+    });
+    describe('error handling', () => {
+        it('should handle errors in stopReceiving', async () => {
+            const error = new Error('Stop receiving failed');
+            stopReceiving = mock(async () => {
+                throw error;
+            });
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            await expect(manager.shutdown()).rejects.toThrow('Stop receiving failed');
+        });
+        it('should handle errors in disconnectTransport', async () => {
+            const error = new Error('Disconnect failed');
+            disconnectTransport = mock(async () => {
+                throw error;
+            });
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            await expect(manager.shutdown()).rejects.toThrow('Disconnect failed');
+        });
+        it('should handle errors in getEnqueueCount callback', async () => {
+            getEnqueueCount = mock(() => {
+                throw new Error('Count failed');
+            });
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+            expect(() => manager.getHandlersState()).toThrow('Count failed');
+        });
+    });
+    describe('edge cases', () => {
+        beforeEach(() => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport);
+        });
+        it('should handle shutdown with no active events', async () => {
+            await manager.shutdown();
+            expect(manager.state).toBe('stopped');
+            expect(manager.getHandlersState().isIdle).toBe(true);
+        });
+        it('should handle rapid increment/decrement cycles', () => {
+            for (let i = 0; i < 100; i++) {
+                manager.incrementProcessing();
+            }
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(100);
+            for (let i = 0; i < 100; i++) {
+                manager.decrementProcessing();
+            }
+            expect(manager.getHandlersState().eventsBeingProcessed).toBe(0);
+            expect(manager.getHandlersState().isIdle).toBe(true);
+        });
+        it('should handle events completing exactly at timeout', async () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 100,
+                idlePollingInterval: 50,
+            });
+            manager.incrementProcessing();
+            const shutdownPromise = manager.shutdown();
+            setTimeout(() => {
+                manager.decrementProcessing();
+            }, 90);
+            await shutdownPromise;
+            expect(manager.state).toBe('stopped');
+        });
+        it('should handle zero timeout gracefully', async () => {
+            manager = new ShutdownManager(getEnqueueCount, stopReceiving, disconnectTransport, {
+                gracefulShutdownTimeout: 0,
+            });
+            manager.incrementProcessing();
+            await manager.shutdown();
+            expect(manager.state).toBe('stopped');
+        });
+    });
+});

package/dist/errors/checkpoint-errors.d.ts

@@ -0,0 +1,30 @@
+import { MatadorError } from './matador-errors.js';
+/**
+ * Thrown when a duplicate io() key is used within a single subscriber execution.
+ * Each io() call must have a unique key to prevent cache collisions.
+ */
+export declare class DuplicateIoKeyError extends MatadorError {
+    readonly key: string;
+    readonly subscriberName: string;
+    readonly description: string;
+    constructor(key: string, subscriberName: string);
+}
+/**
+ * Thrown when checkpoint store operations fail.
+ */
+export declare class CheckpointStoreError extends MatadorError {
+    readonly operation: 'get' | 'set' | 'delete';
+    readonly envelopeId: string;
+    readonly cause: Error;
+    readonly description: string;
+    constructor(operation: 'get' | 'set' | 'delete', envelopeId: string, cause: Error);
+}
+/**
+ * Type guard for DuplicateIoKeyError.
+ */
+export declare function isDuplicateIoKeyError(error: unknown): error is DuplicateIoKeyError;
+/**
+ * Type guard for CheckpointStoreError.
+ */
+export declare function isCheckpointStoreError(error: unknown): error is CheckpointStoreError;
+//# sourceMappingURL=checkpoint-errors.d.ts.map

package/dist/errors/checkpoint-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-errors.d.ts","sourceRoot":"","sources":["../../src/errors/checkpoint-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;aASjC,GAAG,EAAE,MAAM;aACX,cAAc,EAAE,MAAM;IATxC,QAAQ,CAAC,WAAW,SAKmB;gBAGrB,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM;CAOzC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;aAOlC,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ;aACnC,UAAU,EAAE,MAAM;aAClB,KAAK,EAAE,KAAK;IAR9B,QAAQ,CAAC,WAAW,SAGsD;gBAGxD,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,EACnC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,KAAK;CAM/B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,mBAAmB,CAE9B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,oBAAoB,CAE/B"}

package/dist/errors/checkpoint-errors.js

@@ -0,0 +1,49 @@
+import { MatadorError } from './matador-errors.js';
+/**
+ * Thrown when a duplicate io() key is used within a single subscriber execution.
+ * Each io() call must have a unique key to prevent cache collisions.
+ */
+export class DuplicateIoKeyError extends MatadorError {
+    key;
+    subscriberName;
+    description = 'The same io() key was used multiple times in a single subscriber execution. ' +
+        'Each io() call must have a unique key to ensure correct checkpoint behavior. ' +
+        'ACTION: Ensure all io() keys are unique within the subscriber. ' +
+        'For dynamic operations (e.g., loops), include a unique identifier in the key ' +
+        '(e.g., `process-item-${item.id}`).';
+    constructor(key, subscriberName) {
+        super(`Duplicate io key "${key}" in subscriber "${subscriberName}". ` +
+            `Each io() call must have a unique key.`);
+        this.key = key;
+        this.subscriberName = subscriberName;
+    }
+}
+/**
+ * Thrown when checkpoint store operations fail.
+ */
+export class CheckpointStoreError extends MatadorError {
+    operation;
+    envelopeId;
+    cause;
+    description = 'A checkpoint store operation failed. This may cause issues with resumable subscribers. ' +
+        'ACTION: Check the underlying storage system (Redis, etc.) for connectivity issues. ' +
+        'The subscriber may re-execute operations that were already completed.';
+    constructor(operation, envelopeId, cause) {
+        super(`Checkpoint store ${operation} failed for envelope "${envelopeId}": ${cause.message}`);
+        this.operation = operation;
+        this.envelopeId = envelopeId;
+        this.cause = cause;
+    }
+}
+/**
+ * Type guard for DuplicateIoKeyError.
+ */
+export function isDuplicateIoKeyError(error) {
+    return error instanceof DuplicateIoKeyError;
+}
+/**
+ * Type guard for CheckpointStoreError.
+ */
+export function isCheckpointStoreError(error) {
+    return error instanceof CheckpointStoreError;
+}

package/dist/errors/has-description.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Interface for errors that provide a human-readable description.
+ * The description explains what the error means and what actions
+ * users should take when encountering it in logs/observability.
+ */
+export interface HasDescription {
+    /**
+     * Human-readable description of the error type.
+     * Intended for logging and observability to help users understand
+     * the error and determine appropriate remediation steps.
+     */
+    readonly description: string;
+}
+/**
+ * Type guard to check if an error implements HasDescription.
+ */
+export declare function hasDescription(error: unknown): error is HasDescription;
+//# sourceMappingURL=has-description.d.ts.map

package/dist/errors/has-description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"has-description.d.ts","sourceRoot":"","sources":["../../src/errors/has-description.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAOtE"}

package/dist/errors/has-description.js

@@ -0,0 +1,9 @@
+/**
+ * Type guard to check if an error implements HasDescription.
+ */
+export function hasDescription(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'description' in error &&
+        typeof error.description === 'string');
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+export type { HasDescription } from './has-description.js';
+export { hasDescription } from './has-description.js';
+export { DontRetry, DoRetry, EventAssertionError, isAssertionError, isDontRetry, isDoRetry, RetryControlError, } from './retry-errors.js';
+export { MatadorError, isMatadorError, NotStartedError, isNotStartedError, ShutdownInProgressError, TransportNotConnectedError, isTransportNotConnectedError, TransportClosedError, TransportSendError, AllTransportsFailedError, DelayedMessagesNotSupportedError, EventNotRegisteredError, isEventNotRegisteredError, SubscriberNotRegisteredError, isSubscriberNotRegisteredError, NoSubscribersExistError, InvalidSchemaError, SubscriberIsStubError, LocalTransportCannotProcessStubError, QueueNotFoundError, InvalidEventError, MessageMaybePoisonedError, isMessageMaybePoisonedError, IdempotentMessageCannotRetryError, isIdempotentMessageCannotRetryError, TimeoutError, } from './matador-errors.js';
+export { CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from './checkpoint-errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EACL,SAAS,EACT,OAAO,EACP,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,YAAY,EACZ,cAAc,EAEd,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EAEvB,0BAA0B,EAC1B,4BAA4B,EAC5B,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,gCAAgC,EAEhC,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,oCAAoC,EAEpC,kBAAkB,EAElB,iBAAiB,EAEjB,yBAAyB,EACzB,2BAA2B,EAC3B,iCAAiC,EACjC,mCAAmC,EAEnC,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,22 @@
+export { hasDescription } from './has-description.js';
+export { DontRetry, DoRetry, EventAssertionError, isAssertionError, isDontRetry, isDoRetry, RetryControlError, } from './retry-errors.js';
+export { 
+// Base class
+MatadorError, isMatadorError, 
+// Lifecycle errors
+NotStartedError, isNotStartedError, ShutdownInProgressError, 
+// Transport errors
+TransportNotConnectedError, isTransportNotConnectedError, TransportClosedError, TransportSendError, AllTransportsFailedError, DelayedMessagesNotSupportedError, 
+// Schema & configuration errors
+EventNotRegisteredError, isEventNotRegisteredError, SubscriberNotRegisteredError, isSubscriberNotRegisteredError, NoSubscribersExistError, InvalidSchemaError, SubscriberIsStubError, LocalTransportCannotProcessStubError, 
+// Queue errors
+QueueNotFoundError, 
+// Event validation errors
+InvalidEventError, 
+// Message processing errors
+MessageMaybePoisonedError, isMessageMaybePoisonedError, IdempotentMessageCannotRetryError, isIdempotentMessageCannotRetryError, 
+// Timeout errors
+TimeoutError, } from './matador-errors.js';
+export { 
+// Checkpoint errors
+CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from './checkpoint-errors.js';