@zdavison/matador 2.0.1

package/dist/checkpoint/context.test.js

@@ -0,0 +1,424 @@
+import { beforeEach, describe, expect, it, vi } from 'bun:test';
+import { DuplicateIoKeyError } from '../errors/index.js';
+import { ResumableContext } from './context.js';
+import { MemoryCheckpointStore } from './stores/memory.js';
+function createTestEnvelope(id = 'test-envelope-id', attempts = 1) {
+    return {
+        id,
+        data: { userId: '123' },
+        docket: {
+            eventKey: 'test.event',
+            targetSubscriber: 'test-subscriber',
+            importance: 'should-investigate',
+            attempts,
+            createdAt: new Date().toISOString(),
+        },
+    };
+}
+function createTestSubscriber(name = 'test-subscriber') {
+    return {
+        name,
+        description: 'Test subscriber',
+        idempotent: 'resumable',
+        importance: 'should-investigate',
+    };
+}
+describe('ResumableContext', () => {
+    let store;
+    let envelope;
+    let subscriber;
+    beforeEach(() => {
+        store = new MemoryCheckpointStore();
+        envelope = createTestEnvelope();
+        subscriber = createTestSubscriber();
+    });
+    describe('io()', () => {
+        it('should execute function and cache result on first call', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            let executeCount = 0;
+            const result = await context.io('step-1', () => {
+                executeCount++;
+                return 'result-1';
+            });
+            expect(result).toBe('result-1');
+            expect(executeCount).toBe(1);
+            expect(store.size).toBe(1);
+        });
+        it('should return cached result on retry without re-executing', async () => {
+            // First execution - cache the result
+            const firstContext = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            let executeCount = 0;
+            await firstContext.io('step-1', () => {
+                executeCount++;
+                return 'result-1';
+            });
+            expect(executeCount).toBe(1);
+            // Simulate retry - load existing checkpoint
+            const checkpoint = await store.get(envelope.id);
+            const retryContext = new ResumableContext({
+                store,
+                envelope: createTestEnvelope(envelope.id, 2),
+                subscriber,
+                existingCheckpoint: checkpoint,
+            });
+            const result = await retryContext.io('step-1', () => {
+                executeCount++;
+                return 'should-not-be-used';
+            });
+            expect(result).toBe('result-1');
+            expect(executeCount).toBe(1); // Still 1, not re-executed
+        });
+        it('should throw DuplicateIoKeyError on duplicate key within same execution', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            await context.io('same-key', () => 'first');
+            await expect(context.io('same-key', () => 'second')).rejects.toThrow(DuplicateIoKeyError);
+        });
+        it('should handle async functions', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            const result = await context.io('async-step', async () => {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                return { value: 42 };
+            });
+            expect(result).toEqual({ value: 42 });
+        });
+        it('should not cache failed operations', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            // First attempt - fails
+            await expect(context.io('failing-step', () => {
+                throw new Error('Operation failed');
+            })).rejects.toThrow('Operation failed');
+            // Checkpoint should not contain the failed step
+            const checkpoint = await store.get(envelope.id);
+            expect(checkpoint?.completedSteps['failing-step']).toBeUndefined();
+        });
+        it('should persist checkpoint after each io() call', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            await context.io('step-1', () => 'result-1');
+            let checkpoint = await store.get(envelope.id);
+            expect(Object.keys(checkpoint.completedSteps)).toHaveLength(1);
+            await context.io('step-2', () => 'result-2');
+            checkpoint = await store.get(envelope.id);
+            expect(Object.keys(checkpoint.completedSteps)).toHaveLength(2);
+        });
+        it('should support various JSON-serializable return types', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            expect(await context.io('string', () => 'hello')).toBe('hello');
+            expect(await context.io('number', () => 42)).toBe(42);
+            expect(await context.io('boolean', () => true)).toBe(true);
+            expect(await context.io('null', () => null)).toBe(null);
+            expect(await context.io('array', () => [1, 2, 3])).toEqual([1, 2, 3]);
+            expect(await context.io('object', () => ({ foo: 'bar' }))).toEqual({
+                foo: 'bar',
+            });
+        });
+    });
+    describe('all()', () => {
+        it('should execute multiple operations in parallel', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            const executionOrder = [];
+            const [a, b, c] = await context.all([
+                [
+                    'fetch-a',
+                    () => {
+                        executionOrder.push('a');
+                        return 'result-a';
+                    },
+                ],
+                [
+                    'fetch-b',
+                    () => {
+                        executionOrder.push('b');
+                        return 'result-b';
+                    },
+                ],
+                [
+                    'fetch-c',
+                    () => {
+                        executionOrder.push('c');
+                        return 'result-c';
+                    },
+                ],
+            ]);
+            expect(a).toBe('result-a');
+            expect(b).toBe('result-b');
+            expect(c).toBe('result-c');
+            expect(executionOrder).toHaveLength(3);
+        });
+        it('should cache all results on retry', async () => {
+            // First execution
+            const firstContext = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            let executeCount = 0;
+            await firstContext.all([
+                [
+                    'fetch-a',
+                    () => {
+                        executeCount++;
+                        return 'result-a';
+                    },
+                ],
+                [
+                    'fetch-b',
+                    () => {
+                        executeCount++;
+                        return 'result-b';
+                    },
+                ],
+            ]);
+            expect(executeCount).toBe(2);
+            // Retry with cached checkpoint
+            const checkpoint = await store.get(envelope.id);
+            const retryContext = new ResumableContext({
+                store,
+                envelope: createTestEnvelope(envelope.id, 2),
+                subscriber,
+                existingCheckpoint: checkpoint,
+            });
+            const [a, b] = await retryContext.all([
+                [
+                    'fetch-a',
+                    () => {
+                        executeCount++;
+                        return 'new-a';
+                    },
+                ],
+                [
+                    'fetch-b',
+                    () => {
+                        executeCount++;
+                        return 'new-b';
+                    },
+                ],
+            ]);
+            expect(a).toBe('result-a'); // Cached
+            expect(b).toBe('result-b'); // Cached
+            expect(executeCount).toBe(2); // Still 2, not re-executed
+        });
+        it('should throw on duplicate key in all()', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            await expect(context.all([
+                ['same-key', () => 'first'],
+                ['same-key', () => 'second'],
+            ])).rejects.toThrow(DuplicateIoKeyError);
+        });
+        it('should throw if all() key conflicts with previous io() key', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            await context.io('used-key', () => 'first');
+            await expect(context.all([
+                ['used-key', () => 'second'],
+                ['new-key', () => 'third'],
+            ])).rejects.toThrow(DuplicateIoKeyError);
+        });
+    });
+    describe('attempt and isRetry', () => {
+        it('should report attempt number from envelope', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope: createTestEnvelope('test', 3),
+                subscriber,
+            });
+            expect(context.attempt).toBe(3);
+        });
+        it('should report isRetry as false for first attempt', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope: createTestEnvelope('test', 1),
+                subscriber,
+            });
+            expect(context.isRetry).toBe(false);
+        });
+        it('should report isRetry as true for subsequent attempts', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope: createTestEnvelope('test', 2),
+                subscriber,
+            });
+            expect(context.isRetry).toBe(true);
+        });
+    });
+    describe('clear()', () => {
+        it('should delete checkpoint from store', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            await context.io('step-1', () => 'result');
+            expect(store.size).toBe(1);
+            await context.clear();
+            expect(store.size).toBe(0);
+        });
+    });
+    describe('hooks', () => {
+        it('should call onCheckpointHit when using cached value', async () => {
+            const onCheckpointHit = vi.fn();
+            // First execution - populate cache
+            const firstContext = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            await firstContext.io('cached-step', () => 'cached-result');
+            // Retry with hooks
+            const checkpoint = await store.get(envelope.id);
+            const retryContext = new ResumableContext({
+                store,
+                envelope: createTestEnvelope(envelope.id, 2),
+                subscriber,
+                existingCheckpoint: checkpoint,
+                hooks: { onCheckpointHit },
+            });
+            await retryContext.io('cached-step', () => 'new-result');
+            expect(onCheckpointHit).toHaveBeenCalledWith({
+                envelope: expect.anything(),
+                subscriber,
+                stepKey: 'cached-step',
+            });
+        });
+        it('should call onCheckpointMiss when executing fresh', async () => {
+            const onCheckpointMiss = vi.fn();
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+                hooks: { onCheckpointMiss },
+            });
+            await context.io('fresh-step', () => 'result');
+            expect(onCheckpointMiss).toHaveBeenCalledWith({
+                envelope,
+                subscriber,
+                stepKey: 'fresh-step',
+            });
+        });
+    });
+    describe('real-world scenarios', () => {
+        it('should replay cached steps and execute new ones on retry', async () => {
+            const executionLog = [];
+            let shouldFail = true;
+            // First attempt - fails after step-1
+            const firstContext = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            try {
+                await firstContext.io('step-0', () => {
+                    executionLog.push('step-0');
+                    return 'result-0';
+                });
+                await firstContext.io('step-1', () => {
+                    executionLog.push('step-1');
+                    return 'result-1';
+                });
+                if (shouldFail) {
+                    shouldFail = false;
+                    throw new Error('Simulated failure');
+                }
+                await firstContext.io('step-2', () => {
+                    executionLog.push('step-2');
+                    return 'result-2';
+                });
+            }
+            catch {
+                // Expected failure
+            }
+            expect(executionLog).toEqual(['step-0', 'step-1']);
+            // Retry - step-0 and step-1 use cache, step-2 executes
+            executionLog.length = 0;
+            const checkpoint = await store.get(envelope.id);
+            const retryContext = new ResumableContext({
+                store,
+                envelope: createTestEnvelope(envelope.id, 2),
+                subscriber,
+                existingCheckpoint: checkpoint,
+            });
+            await retryContext.io('step-0', () => {
+                executionLog.push('step-0');
+                return 'should-not-use';
+            });
+            await retryContext.io('step-1', () => {
+                executionLog.push('step-1');
+                return 'should-not-use';
+            });
+            await retryContext.io('step-2', () => {
+                executionLog.push('step-2');
+                return 'result-2';
+            });
+            expect(executionLog).toEqual(['step-2']); // Only step-2 executed!
+        });
+        it('should handle conditional io() calls correctly', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope: { ...envelope, data: { sendEmail: true } },
+                subscriber,
+            });
+            const result = await context.io('send-email', () => ({
+                messageId: 'msg-123',
+            }));
+            expect(result).toEqual({ messageId: 'msg-123' });
+        });
+        it('should handle dynamic loop with unique keys', async () => {
+            const context = new ResumableContext({
+                store,
+                envelope,
+                subscriber,
+            });
+            const items = [
+                { id: 'item-1', value: 10 },
+                { id: 'item-2', value: 20 },
+                { id: 'item-3', value: 30 },
+            ];
+            const results = [];
+            for (const item of items) {
+                const processed = await context.io(`process-${item.id}`, () => {
+                    return item.value * 2;
+                });
+                results.push(processed);
+            }
+            expect(results).toEqual([20, 40, 60]);
+        });
+    });
+});

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,7 @@
+export type { Checkpoint, CheckpointClearedContext, CheckpointHitContext, CheckpointLoadedContext, CheckpointMissContext, CheckpointStore, JsonSerializable, SubscriberContext, } from './types.js';
+export type { ResumableContextConfig, ResumableContextHooks, } from './context.js';
+export { ResumableContext } from './context.js';
+export { MemoryCheckpointStore } from './stores/memory.js';
+export { NoOpCheckpointStore } from './stores/noop.js';
+export { CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from '../errors/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpoint/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC"}

package/dist/checkpoint/index.js

@@ -0,0 +1,6 @@
+export { ResumableContext } from './context.js';
+// Stores
+export { MemoryCheckpointStore } from './stores/memory.js';
+export { NoOpCheckpointStore } from './stores/noop.js';
+// Errors (re-exported from ../errors for convenience)
+export { CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from '../errors/index.js';

package/dist/checkpoint/stores/memory.d.ts

@@ -0,0 +1,29 @@
+import type { Checkpoint, CheckpointStore } from '../types.js';
+/**
+ * In-memory checkpoint store for testing and development.
+ * Checkpoints are lost when the process restarts.
+ *
+ * For production use, implement a persistent store (e.g., RedisCheckpointStore).
+ */
+export declare class MemoryCheckpointStore implements CheckpointStore {
+    private readonly checkpoints;
+    get(envelopeId: string): Promise<Checkpoint | undefined>;
+    set(envelopeId: string, checkpoint: Checkpoint): Promise<void>;
+    delete(envelopeId: string): Promise<void>;
+    /**
+     * Gets the number of stored checkpoints.
+     * Useful for testing.
+     */
+    get size(): number;
+    /**
+     * Clears all stored checkpoints.
+     * Useful for testing.
+     */
+    clear(): void;
+    /**
+     * Gets all stored checkpoint IDs.
+     * Useful for testing.
+     */
+    keys(): string[];
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/checkpoint/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/checkpoint/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAEvD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIxD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,IAAI,IAAI,MAAM,EAAE;CAGjB"}

package/dist/checkpoint/stores/memory.js

@@ -0,0 +1,39 @@
+/**
+ * In-memory checkpoint store for testing and development.
+ * Checkpoints are lost when the process restarts.
+ *
+ * For production use, implement a persistent store (e.g., RedisCheckpointStore).
+ */
+export class MemoryCheckpointStore {
+    checkpoints = new Map();
+    async get(envelopeId) {
+        return this.checkpoints.get(envelopeId);
+    }
+    async set(envelopeId, checkpoint) {
+        this.checkpoints.set(envelopeId, checkpoint);
+    }
+    async delete(envelopeId) {
+        this.checkpoints.delete(envelopeId);
+    }
+    /**
+     * Gets the number of stored checkpoints.
+     * Useful for testing.
+     */
+    get size() {
+        return this.checkpoints.size;
+    }
+    /**
+     * Clears all stored checkpoints.
+     * Useful for testing.
+     */
+    clear() {
+        this.checkpoints.clear();
+    }
+    /**
+     * Gets all stored checkpoint IDs.
+     * Useful for testing.
+     */
+    keys() {
+        return [...this.checkpoints.keys()];
+    }
+}

package/dist/checkpoint/stores/noop.d.ts

@@ -0,0 +1,14 @@
+import type { Checkpoint, CheckpointStore } from '../types.js';
+/**
+ * No-operation checkpoint store that doesn't persist anything.
+ * Used when no checkpoint store is configured.
+ *
+ * With this store, resumable subscribers will work but checkpoints
+ * won't persist across retries - all io() operations will re-execute.
+ */
+export declare class NoOpCheckpointStore implements CheckpointStore {
+    get(_envelopeId: string): Promise<Checkpoint | undefined>;
+    set(_envelopeId: string, _checkpoint: Checkpoint): Promise<void>;
+    delete(_envelopeId: string): Promise<void>;
+}
+//# sourceMappingURL=noop.d.ts.map

package/dist/checkpoint/stores/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../../src/checkpoint/stores/noop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACnD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIzD,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD"}

package/dist/checkpoint/stores/noop.js

@@ -0,0 +1,18 @@
+/**
+ * No-operation checkpoint store that doesn't persist anything.
+ * Used when no checkpoint store is configured.
+ *
+ * With this store, resumable subscribers will work but checkpoints
+ * won't persist across retries - all io() operations will re-execute.
+ */
+export class NoOpCheckpointStore {
+    async get(_envelopeId) {
+        return undefined;
+    }
+    async set(_envelopeId, _checkpoint) {
+        // No-op
+    }
+    async delete(_envelopeId) {
+        // No-op
+    }
+}

package/dist/checkpoint/stores/stores.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stores.test.d.ts.map

package/dist/checkpoint/stores/stores.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.test.d.ts","sourceRoot":"","sources":["../../../src/checkpoint/stores/stores.test.ts"],"names":[],"mappings":""}