@zdavison/matador 2.0.8 → 2.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (196) hide show
  1. package/package.json +1 -1
  2. package/src/index.ts +1 -0
  3. package/dist/checkpoint/context.d.ts +0 -59
  4. package/dist/checkpoint/context.d.ts.map +0 -1
  5. package/dist/checkpoint/context.js +0 -140
  6. package/dist/checkpoint/context.test.d.ts +0 -2
  7. package/dist/checkpoint/context.test.d.ts.map +0 -1
  8. package/dist/checkpoint/context.test.js +0 -424
  9. package/dist/checkpoint/index.d.ts +0 -7
  10. package/dist/checkpoint/index.d.ts.map +0 -1
  11. package/dist/checkpoint/index.js +0 -6
  12. package/dist/checkpoint/stores/memory.d.ts +0 -29
  13. package/dist/checkpoint/stores/memory.d.ts.map +0 -1
  14. package/dist/checkpoint/stores/memory.js +0 -39
  15. package/dist/checkpoint/stores/noop.d.ts +0 -14
  16. package/dist/checkpoint/stores/noop.d.ts.map +0 -1
  17. package/dist/checkpoint/stores/noop.js +0 -18
  18. package/dist/checkpoint/stores/stores.test.d.ts +0 -2
  19. package/dist/checkpoint/stores/stores.test.d.ts.map +0 -1
  20. package/dist/checkpoint/stores/stores.test.js +0 -146
  21. package/dist/checkpoint/types.d.ts +0 -119
  22. package/dist/checkpoint/types.d.ts.map +0 -1
  23. package/dist/checkpoint/types.js +0 -1
  24. package/dist/codec/codec.d.ts +0 -29
  25. package/dist/codec/codec.d.ts.map +0 -1
  26. package/dist/codec/codec.js +0 -15
  27. package/dist/codec/header-aware-codec.d.ts +0 -36
  28. package/dist/codec/header-aware-codec.d.ts.map +0 -1
  29. package/dist/codec/header-aware-codec.js +0 -1
  30. package/dist/codec/index.d.ts +0 -6
  31. package/dist/codec/index.d.ts.map +0 -1
  32. package/dist/codec/index.js +0 -3
  33. package/dist/codec/json-codec.d.ts +0 -13
  34. package/dist/codec/json-codec.d.ts.map +0 -1
  35. package/dist/codec/json-codec.js +0 -64
  36. package/dist/codec/rabbitmq-codec.d.ts +0 -28
  37. package/dist/codec/rabbitmq-codec.d.ts.map +0 -1
  38. package/dist/codec/rabbitmq-codec.js +0 -242
  39. package/dist/codec/rabbitmq-codec.test.d.ts +0 -2
  40. package/dist/codec/rabbitmq-codec.test.d.ts.map +0 -1
  41. package/dist/codec/rabbitmq-codec.test.js +0 -433
  42. package/dist/core/fanout.d.ts +0 -59
  43. package/dist/core/fanout.d.ts.map +0 -1
  44. package/dist/core/fanout.js +0 -121
  45. package/dist/core/fanout.test.d.ts +0 -2
  46. package/dist/core/fanout.test.d.ts.map +0 -1
  47. package/dist/core/fanout.test.js +0 -1054
  48. package/dist/core/index.d.ts +0 -7
  49. package/dist/core/index.d.ts.map +0 -1
  50. package/dist/core/index.js +0 -3
  51. package/dist/core/matador.d.ts +0 -133
  52. package/dist/core/matador.d.ts.map +0 -1
  53. package/dist/core/matador.js +0 -228
  54. package/dist/core/matador.test.d.ts +0 -2
  55. package/dist/core/matador.test.d.ts.map +0 -1
  56. package/dist/core/matador.test.js +0 -446
  57. package/dist/core/shutdown.d.ts +0 -78
  58. package/dist/core/shutdown.d.ts.map +0 -1
  59. package/dist/core/shutdown.js +0 -111
  60. package/dist/core/shutdown.test.d.ts +0 -2
  61. package/dist/core/shutdown.test.d.ts.map +0 -1
  62. package/dist/core/shutdown.test.js +0 -524
  63. package/dist/errors/checkpoint-errors.d.ts +0 -30
  64. package/dist/errors/checkpoint-errors.d.ts.map +0 -1
  65. package/dist/errors/checkpoint-errors.js +0 -49
  66. package/dist/errors/has-description.d.ts +0 -18
  67. package/dist/errors/has-description.d.ts.map +0 -1
  68. package/dist/errors/has-description.js +0 -9
  69. package/dist/errors/index.d.ts +0 -6
  70. package/dist/errors/index.d.ts.map +0 -1
  71. package/dist/errors/index.js +0 -22
  72. package/dist/errors/matador-errors.d.ts +0 -183
  73. package/dist/errors/matador-errors.d.ts.map +0 -1
  74. package/dist/errors/matador-errors.js +0 -376
  75. package/dist/errors/retry-errors.d.ts +0 -102
  76. package/dist/errors/retry-errors.d.ts.map +0 -1
  77. package/dist/errors/retry-errors.js +0 -155
  78. package/dist/errors/retry-errors.test.d.ts +0 -2
  79. package/dist/errors/retry-errors.test.d.ts.map +0 -1
  80. package/dist/errors/retry-errors.test.js +0 -136
  81. package/dist/hooks/index.d.ts +0 -4
  82. package/dist/hooks/index.d.ts.map +0 -1
  83. package/dist/hooks/index.js +0 -2
  84. package/dist/hooks/safe-hooks.d.ts +0 -32
  85. package/dist/hooks/safe-hooks.d.ts.map +0 -1
  86. package/dist/hooks/safe-hooks.js +0 -120
  87. package/dist/hooks/types.d.ts +0 -172
  88. package/dist/hooks/types.d.ts.map +0 -1
  89. package/dist/hooks/types.js +0 -9
  90. package/dist/index.cjs +0 -3228
  91. package/dist/index.cjs.map +0 -1
  92. package/dist/index.d.cts +0 -23
  93. package/dist/index.d.ts +0 -23
  94. package/dist/index.d.ts.map +0 -1
  95. package/dist/index.js +0 -31
  96. package/dist/index.js.map +0 -1
  97. package/dist/pipeline/index.d.ts +0 -3
  98. package/dist/pipeline/index.d.ts.map +0 -1
  99. package/dist/pipeline/index.js +0 -1
  100. package/dist/pipeline/pipeline.d.ts +0 -63
  101. package/dist/pipeline/pipeline.d.ts.map +0 -1
  102. package/dist/pipeline/pipeline.js +0 -273
  103. package/dist/pipeline/pipeline.test.d.ts +0 -2
  104. package/dist/pipeline/pipeline.test.d.ts.map +0 -1
  105. package/dist/pipeline/pipeline.test.js +0 -1112
  106. package/dist/retry/index.d.ts +0 -4
  107. package/dist/retry/index.d.ts.map +0 -1
  108. package/dist/retry/index.js +0 -1
  109. package/dist/retry/policy.d.ts +0 -43
  110. package/dist/retry/policy.d.ts.map +0 -1
  111. package/dist/retry/policy.js +0 -1
  112. package/dist/retry/standard-policy.d.ts +0 -44
  113. package/dist/retry/standard-policy.d.ts.map +0 -1
  114. package/dist/retry/standard-policy.js +0 -102
  115. package/dist/retry/standard-policy.test.d.ts +0 -2
  116. package/dist/retry/standard-policy.test.d.ts.map +0 -1
  117. package/dist/retry/standard-policy.test.js +0 -196
  118. package/dist/schema/index.d.ts +0 -4
  119. package/dist/schema/index.d.ts.map +0 -1
  120. package/dist/schema/index.js +0 -2
  121. package/dist/schema/registry.d.ts +0 -63
  122. package/dist/schema/registry.d.ts.map +0 -1
  123. package/dist/schema/registry.js +0 -174
  124. package/dist/schema/registry.test.d.ts +0 -2
  125. package/dist/schema/registry.test.d.ts.map +0 -1
  126. package/dist/schema/registry.test.js +0 -278
  127. package/dist/schema/types.d.ts +0 -158
  128. package/dist/schema/types.d.ts.map +0 -1
  129. package/dist/schema/types.js +0 -74
  130. package/dist/schema/types.test.d.ts +0 -2
  131. package/dist/schema/types.test.d.ts.map +0 -1
  132. package/dist/schema/types.test.js +0 -242
  133. package/dist/topology/builder.d.ts +0 -80
  134. package/dist/topology/builder.d.ts.map +0 -1
  135. package/dist/topology/builder.js +0 -165
  136. package/dist/topology/builder.test.d.ts +0 -2
  137. package/dist/topology/builder.test.d.ts.map +0 -1
  138. package/dist/topology/builder.test.js +0 -360
  139. package/dist/topology/index.d.ts +0 -5
  140. package/dist/topology/index.d.ts.map +0 -1
  141. package/dist/topology/index.js +0 -2
  142. package/dist/topology/types.d.ts +0 -128
  143. package/dist/topology/types.d.ts.map +0 -1
  144. package/dist/topology/types.js +0 -28
  145. package/dist/transport/capabilities.d.ts +0 -66
  146. package/dist/transport/capabilities.d.ts.map +0 -1
  147. package/dist/transport/capabilities.js +0 -18
  148. package/dist/transport/connection-manager.d.ts +0 -95
  149. package/dist/transport/connection-manager.d.ts.map +0 -1
  150. package/dist/transport/connection-manager.js +0 -144
  151. package/dist/transport/index.d.ts +0 -11
  152. package/dist/transport/index.d.ts.map +0 -1
  153. package/dist/transport/index.js +0 -5
  154. package/dist/transport/local/local-transport.d.ts +0 -62
  155. package/dist/transport/local/local-transport.d.ts.map +0 -1
  156. package/dist/transport/local/local-transport.js +0 -241
  157. package/dist/transport/local/local-transport.test.d.ts +0 -2
  158. package/dist/transport/local/local-transport.test.d.ts.map +0 -1
  159. package/dist/transport/local/local-transport.test.js +0 -192
  160. package/dist/transport/multi/multi-transport.d.ts +0 -94
  161. package/dist/transport/multi/multi-transport.d.ts.map +0 -1
  162. package/dist/transport/multi/multi-transport.js +0 -184
  163. package/dist/transport/multi/multi-transport.test.d.ts +0 -2
  164. package/dist/transport/multi/multi-transport.test.d.ts.map +0 -1
  165. package/dist/transport/multi/multi-transport.test.js +0 -236
  166. package/dist/transport/rabbitmq/rabbitmq-transport.d.ts +0 -83
  167. package/dist/transport/rabbitmq/rabbitmq-transport.d.ts.map +0 -1
  168. package/dist/transport/rabbitmq/rabbitmq-transport.js +0 -541
  169. package/dist/transport/rabbitmq/rabbitmq-transport.test.d.ts +0 -2
  170. package/dist/transport/rabbitmq/rabbitmq-transport.test.d.ts.map +0 -1
  171. package/dist/transport/rabbitmq/rabbitmq-transport.test.js +0 -100
  172. package/dist/transport/transport.d.ts +0 -152
  173. package/dist/transport/transport.d.ts.map +0 -1
  174. package/dist/transport/transport.js +0 -1
  175. package/dist/types/common.d.ts +0 -41
  176. package/dist/types/common.d.ts.map +0 -1
  177. package/dist/types/common.js +0 -12
  178. package/dist/types/dispatcher.d.ts +0 -14
  179. package/dist/types/dispatcher.d.ts.map +0 -1
  180. package/dist/types/dispatcher.js +0 -1
  181. package/dist/types/envelope.d.ts +0 -131
  182. package/dist/types/envelope.d.ts.map +0 -1
  183. package/dist/types/envelope.js +0 -99
  184. package/dist/types/event.d.ts +0 -92
  185. package/dist/types/event.d.ts.map +0 -1
  186. package/dist/types/event.js +0 -26
  187. package/dist/types/event.test.d.ts +0 -2
  188. package/dist/types/event.test.d.ts.map +0 -1
  189. package/dist/types/event.test.js +0 -130
  190. package/dist/types/index.d.ts +0 -11
  191. package/dist/types/index.d.ts.map +0 -1
  192. package/dist/types/index.js +0 -4
  193. package/dist/types/subscriber.d.ts +0 -227
  194. package/dist/types/subscriber.d.ts.map +0 -1
  195. package/dist/types/subscriber.js +0 -97
  196. package/tsconfig.tsbuildinfo +0 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zdavison/matador",
3
- "version": "2.0.8",
3
+ "version": "2.0.9",
4
4
  "description": "A batteries-included event system.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
package/src/index.ts CHANGED
@@ -124,6 +124,7 @@ export { CodecDecodeError, JsonCodec, RabbitMQCodec } from './codec/index.js';
124
124
  export type {
125
125
  MatadorSchema,
126
126
  RegisterOptions,
127
+ RuntimeSchemaEntryTuple,
127
128
  SchemaEntry,
128
129
  SchemaEntryTuple,
129
130
  SchemaIssue,
@@ -1,59 +0,0 @@
1
- import type { Envelope, SubscriberDefinition } from '../types/index.js';
2
- import type { Checkpoint, CheckpointHitContext, CheckpointMissContext, CheckpointStore, JsonSerializable, SubscriberContext } from './types.js';
3
- /**
4
- * Hooks for observability during context operations.
5
- */
6
- export interface ResumableContextHooks {
7
- onCheckpointHit?(context: CheckpointHitContext): void | Promise<void>;
8
- onCheckpointMiss?(context: CheckpointMissContext): void | Promise<void>;
9
- }
10
- /**
11
- * Configuration for creating a ResumableContext.
12
- */
13
- export interface ResumableContextConfig {
14
- readonly store: CheckpointStore;
15
- readonly envelope: Envelope;
16
- readonly subscriber: SubscriberDefinition;
17
- readonly existingCheckpoint?: Checkpoint | undefined;
18
- readonly hooks?: ResumableContextHooks | undefined;
19
- }
20
- /**
21
- * Implementation of SubscriberContext that provides io() caching.
22
- *
23
- * On first execution, io() calls execute their lambdas and cache results.
24
- * On retry (when existingCheckpoint is provided), cached results are returned
25
- * without re-executing the lambda.
26
- */
27
- export declare class ResumableContext implements SubscriberContext {
28
- private checkpoint;
29
- private readonly usedKeys;
30
- private readonly store;
31
- private readonly envelope;
32
- private readonly subscriber;
33
- private readonly hooks;
34
- constructor(config: ResumableContextConfig);
35
- get attempt(): number;
36
- get isRetry(): boolean;
37
- io<T extends JsonSerializable>(key: string, fn: () => Promise<T> | T): Promise<T>;
38
- all<T extends readonly [
39
- string,
40
- () => Promise<JsonSerializable> | JsonSerializable
41
- ][]>(ops: T): Promise<{
42
- [K in keyof T]: T[K] extends [string, () => Promise<infer R> | infer R] ? R : never;
43
- }>;
44
- /**
45
- * Clears the checkpoint from storage.
46
- * Called after successful completion or dead-letter.
47
- */
48
- clear(): Promise<void>;
49
- /**
50
- * Gets the current checkpoint state.
51
- * Useful for debugging and testing.
52
- */
53
- getCheckpoint(): Checkpoint;
54
- /**
55
- * Gets the number of cached steps.
56
- */
57
- get cachedStepCount(): number;
58
- }
59
- //# sourceMappingURL=context.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/checkpoint/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,gBAAgB,CAAC,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACpD;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;gBAE9C,MAAM,EAAE,sBAAsB;IAa1C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAEK,EAAE,CAAC,CAAC,SAAS,gBAAgB,EACjC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC;IA0CP,GAAG,CACP,CAAC,SAAS,SAAS;QACjB,MAAM;QACN,MAAM,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB;KACnD,EAAE,EAEH,GAAG,EAAE,CAAC,GACL,OAAO,CAAC;SACR,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GACnE,CAAC,GACD,KAAK;KACV,CAAC;IAoEF;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,aAAa,IAAI,UAAU;IAI3B;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;CACF"}
@@ -1,140 +0,0 @@
1
- import { DuplicateIoKeyError } from '../errors/index.js';
2
- /**
3
- * Implementation of SubscriberContext that provides io() caching.
4
- *
5
- * On first execution, io() calls execute their lambdas and cache results.
6
- * On retry (when existingCheckpoint is provided), cached results are returned
7
- * without re-executing the lambda.
8
- */
9
- export class ResumableContext {
10
- checkpoint;
11
- usedKeys = new Set();
12
- store;
13
- envelope;
14
- subscriber;
15
- hooks;
16
- constructor(config) {
17
- this.store = config.store;
18
- this.envelope = config.envelope;
19
- this.subscriber = config.subscriber;
20
- this.hooks = config.hooks;
21
- this.checkpoint = config.existingCheckpoint ?? {
22
- envelopeId: config.envelope.id,
23
- subscriberName: config.subscriber.name,
24
- completedSteps: {},
25
- };
26
- }
27
- get attempt() {
28
- return this.envelope.docket.attempts;
29
- }
30
- get isRetry() {
31
- return this.attempt > 1;
32
- }
33
- async io(key, fn) {
34
- // Validate key uniqueness within this execution
35
- if (this.usedKeys.has(key)) {
36
- throw new DuplicateIoKeyError(key, this.subscriber.name);
37
- }
38
- this.usedKeys.add(key);
39
- // Check cache first
40
- if (key in this.checkpoint.completedSteps) {
41
- await this.hooks?.onCheckpointHit?.({
42
- envelope: this.envelope,
43
- subscriber: this.subscriber,
44
- stepKey: key,
45
- });
46
- return this.checkpoint.completedSteps[key];
47
- }
48
- // Notify cache miss
49
- await this.hooks?.onCheckpointMiss?.({
50
- envelope: this.envelope,
51
- subscriber: this.subscriber,
52
- stepKey: key,
53
- });
54
- // Execute the function - errors propagate, no caching on failure
55
- const result = await fn();
56
- // Cache the result
57
- this.checkpoint = {
58
- ...this.checkpoint,
59
- completedSteps: {
60
- ...this.checkpoint.completedSteps,
61
- [key]: result,
62
- },
63
- };
64
- // Persist checkpoint immediately (incremental persistence)
65
- await this.store.set(this.envelope.id, this.checkpoint);
66
- return result;
67
- }
68
- async all(ops) {
69
- // First, check for duplicates within this all() call
70
- const keysInThisCall = new Set();
71
- for (const [key] of ops) {
72
- if (keysInThisCall.has(key)) {
73
- throw new DuplicateIoKeyError(key, this.subscriber.name);
74
- }
75
- keysInThisCall.add(key);
76
- }
77
- // Then validate against previously used keys
78
- for (const [key] of ops) {
79
- if (this.usedKeys.has(key)) {
80
- throw new DuplicateIoKeyError(key, this.subscriber.name);
81
- }
82
- }
83
- // Mark all keys as used
84
- for (const [key] of ops) {
85
- this.usedKeys.add(key);
86
- }
87
- // Execute all operations in parallel
88
- const results = await Promise.all(ops.map(async ([key, fn]) => {
89
- // Check cache first
90
- if (key in this.checkpoint.completedSteps) {
91
- await this.hooks?.onCheckpointHit?.({
92
- envelope: this.envelope,
93
- subscriber: this.subscriber,
94
- stepKey: key,
95
- });
96
- return this.checkpoint.completedSteps[key];
97
- }
98
- // Notify cache miss
99
- await this.hooks?.onCheckpointMiss?.({
100
- envelope: this.envelope,
101
- subscriber: this.subscriber,
102
- stepKey: key,
103
- });
104
- // Execute - errors propagate
105
- const result = await fn();
106
- // Cache individually (in local state, will persist after Promise.all)
107
- this.checkpoint = {
108
- ...this.checkpoint,
109
- completedSteps: {
110
- ...this.checkpoint.completedSteps,
111
- [key]: result,
112
- },
113
- };
114
- return result;
115
- }));
116
- // Persist after all parallel operations complete
117
- await this.store.set(this.envelope.id, this.checkpoint);
118
- return results;
119
- }
120
- /**
121
- * Clears the checkpoint from storage.
122
- * Called after successful completion or dead-letter.
123
- */
124
- async clear() {
125
- await this.store.delete(this.envelope.id);
126
- }
127
- /**
128
- * Gets the current checkpoint state.
129
- * Useful for debugging and testing.
130
- */
131
- getCheckpoint() {
132
- return this.checkpoint;
133
- }
134
- /**
135
- * Gets the number of cached steps.
136
- */
137
- get cachedStepCount() {
138
- return Object.keys(this.checkpoint.completedSteps).length;
139
- }
140
- }
@@ -1,2 +0,0 @@
1
- export {};
2
- //# sourceMappingURL=context.test.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../../src/checkpoint/context.test.ts"],"names":[],"mappings":""}
@@ -1,424 +0,0 @@
1
- import { beforeEach, describe, expect, it, vi } from 'bun:test';
2
- import { DuplicateIoKeyError } from '../errors/index.js';
3
- import { ResumableContext } from './context.js';
4
- import { MemoryCheckpointStore } from './stores/memory.js';
5
- function createTestEnvelope(id = 'test-envelope-id', attempts = 1) {
6
- return {
7
- id,
8
- data: { userId: '123' },
9
- docket: {
10
- eventKey: 'test.event',
11
- targetSubscriber: 'test-subscriber',
12
- importance: 'should-investigate',
13
- attempts,
14
- createdAt: new Date().toISOString(),
15
- },
16
- };
17
- }
18
- function createTestSubscriber(name = 'test-subscriber') {
19
- return {
20
- name,
21
- description: 'Test subscriber',
22
- idempotent: 'resumable',
23
- importance: 'should-investigate',
24
- };
25
- }
26
- describe('ResumableContext', () => {
27
- let store;
28
- let envelope;
29
- let subscriber;
30
- beforeEach(() => {
31
- store = new MemoryCheckpointStore();
32
- envelope = createTestEnvelope();
33
- subscriber = createTestSubscriber();
34
- });
35
- describe('io()', () => {
36
- it('should execute function and cache result on first call', async () => {
37
- const context = new ResumableContext({
38
- store,
39
- envelope,
40
- subscriber,
41
- });
42
- let executeCount = 0;
43
- const result = await context.io('step-1', () => {
44
- executeCount++;
45
- return 'result-1';
46
- });
47
- expect(result).toBe('result-1');
48
- expect(executeCount).toBe(1);
49
- expect(store.size).toBe(1);
50
- });
51
- it('should return cached result on retry without re-executing', async () => {
52
- // First execution - cache the result
53
- const firstContext = new ResumableContext({
54
- store,
55
- envelope,
56
- subscriber,
57
- });
58
- let executeCount = 0;
59
- await firstContext.io('step-1', () => {
60
- executeCount++;
61
- return 'result-1';
62
- });
63
- expect(executeCount).toBe(1);
64
- // Simulate retry - load existing checkpoint
65
- const checkpoint = await store.get(envelope.id);
66
- const retryContext = new ResumableContext({
67
- store,
68
- envelope: createTestEnvelope(envelope.id, 2),
69
- subscriber,
70
- existingCheckpoint: checkpoint,
71
- });
72
- const result = await retryContext.io('step-1', () => {
73
- executeCount++;
74
- return 'should-not-be-used';
75
- });
76
- expect(result).toBe('result-1');
77
- expect(executeCount).toBe(1); // Still 1, not re-executed
78
- });
79
- it('should throw DuplicateIoKeyError on duplicate key within same execution', async () => {
80
- const context = new ResumableContext({
81
- store,
82
- envelope,
83
- subscriber,
84
- });
85
- await context.io('same-key', () => 'first');
86
- await expect(context.io('same-key', () => 'second')).rejects.toThrow(DuplicateIoKeyError);
87
- });
88
- it('should handle async functions', async () => {
89
- const context = new ResumableContext({
90
- store,
91
- envelope,
92
- subscriber,
93
- });
94
- const result = await context.io('async-step', async () => {
95
- await new Promise((resolve) => setTimeout(resolve, 10));
96
- return { value: 42 };
97
- });
98
- expect(result).toEqual({ value: 42 });
99
- });
100
- it('should not cache failed operations', async () => {
101
- const context = new ResumableContext({
102
- store,
103
- envelope,
104
- subscriber,
105
- });
106
- // First attempt - fails
107
- await expect(context.io('failing-step', () => {
108
- throw new Error('Operation failed');
109
- })).rejects.toThrow('Operation failed');
110
- // Checkpoint should not contain the failed step
111
- const checkpoint = await store.get(envelope.id);
112
- expect(checkpoint?.completedSteps['failing-step']).toBeUndefined();
113
- });
114
- it('should persist checkpoint after each io() call', async () => {
115
- const context = new ResumableContext({
116
- store,
117
- envelope,
118
- subscriber,
119
- });
120
- await context.io('step-1', () => 'result-1');
121
- let checkpoint = await store.get(envelope.id);
122
- expect(Object.keys(checkpoint.completedSteps)).toHaveLength(1);
123
- await context.io('step-2', () => 'result-2');
124
- checkpoint = await store.get(envelope.id);
125
- expect(Object.keys(checkpoint.completedSteps)).toHaveLength(2);
126
- });
127
- it('should support various JSON-serializable return types', async () => {
128
- const context = new ResumableContext({
129
- store,
130
- envelope,
131
- subscriber,
132
- });
133
- expect(await context.io('string', () => 'hello')).toBe('hello');
134
- expect(await context.io('number', () => 42)).toBe(42);
135
- expect(await context.io('boolean', () => true)).toBe(true);
136
- expect(await context.io('null', () => null)).toBe(null);
137
- expect(await context.io('array', () => [1, 2, 3])).toEqual([1, 2, 3]);
138
- expect(await context.io('object', () => ({ foo: 'bar' }))).toEqual({
139
- foo: 'bar',
140
- });
141
- });
142
- });
143
- describe('all()', () => {
144
- it('should execute multiple operations in parallel', async () => {
145
- const context = new ResumableContext({
146
- store,
147
- envelope,
148
- subscriber,
149
- });
150
- const executionOrder = [];
151
- const [a, b, c] = await context.all([
152
- [
153
- 'fetch-a',
154
- () => {
155
- executionOrder.push('a');
156
- return 'result-a';
157
- },
158
- ],
159
- [
160
- 'fetch-b',
161
- () => {
162
- executionOrder.push('b');
163
- return 'result-b';
164
- },
165
- ],
166
- [
167
- 'fetch-c',
168
- () => {
169
- executionOrder.push('c');
170
- return 'result-c';
171
- },
172
- ],
173
- ]);
174
- expect(a).toBe('result-a');
175
- expect(b).toBe('result-b');
176
- expect(c).toBe('result-c');
177
- expect(executionOrder).toHaveLength(3);
178
- });
179
- it('should cache all results on retry', async () => {
180
- // First execution
181
- const firstContext = new ResumableContext({
182
- store,
183
- envelope,
184
- subscriber,
185
- });
186
- let executeCount = 0;
187
- await firstContext.all([
188
- [
189
- 'fetch-a',
190
- () => {
191
- executeCount++;
192
- return 'result-a';
193
- },
194
- ],
195
- [
196
- 'fetch-b',
197
- () => {
198
- executeCount++;
199
- return 'result-b';
200
- },
201
- ],
202
- ]);
203
- expect(executeCount).toBe(2);
204
- // Retry with cached checkpoint
205
- const checkpoint = await store.get(envelope.id);
206
- const retryContext = new ResumableContext({
207
- store,
208
- envelope: createTestEnvelope(envelope.id, 2),
209
- subscriber,
210
- existingCheckpoint: checkpoint,
211
- });
212
- const [a, b] = await retryContext.all([
213
- [
214
- 'fetch-a',
215
- () => {
216
- executeCount++;
217
- return 'new-a';
218
- },
219
- ],
220
- [
221
- 'fetch-b',
222
- () => {
223
- executeCount++;
224
- return 'new-b';
225
- },
226
- ],
227
- ]);
228
- expect(a).toBe('result-a'); // Cached
229
- expect(b).toBe('result-b'); // Cached
230
- expect(executeCount).toBe(2); // Still 2, not re-executed
231
- });
232
- it('should throw on duplicate key in all()', async () => {
233
- const context = new ResumableContext({
234
- store,
235
- envelope,
236
- subscriber,
237
- });
238
- await expect(context.all([
239
- ['same-key', () => 'first'],
240
- ['same-key', () => 'second'],
241
- ])).rejects.toThrow(DuplicateIoKeyError);
242
- });
243
- it('should throw if all() key conflicts with previous io() key', async () => {
244
- const context = new ResumableContext({
245
- store,
246
- envelope,
247
- subscriber,
248
- });
249
- await context.io('used-key', () => 'first');
250
- await expect(context.all([
251
- ['used-key', () => 'second'],
252
- ['new-key', () => 'third'],
253
- ])).rejects.toThrow(DuplicateIoKeyError);
254
- });
255
- });
256
- describe('attempt and isRetry', () => {
257
- it('should report attempt number from envelope', async () => {
258
- const context = new ResumableContext({
259
- store,
260
- envelope: createTestEnvelope('test', 3),
261
- subscriber,
262
- });
263
- expect(context.attempt).toBe(3);
264
- });
265
- it('should report isRetry as false for first attempt', async () => {
266
- const context = new ResumableContext({
267
- store,
268
- envelope: createTestEnvelope('test', 1),
269
- subscriber,
270
- });
271
- expect(context.isRetry).toBe(false);
272
- });
273
- it('should report isRetry as true for subsequent attempts', async () => {
274
- const context = new ResumableContext({
275
- store,
276
- envelope: createTestEnvelope('test', 2),
277
- subscriber,
278
- });
279
- expect(context.isRetry).toBe(true);
280
- });
281
- });
282
- describe('clear()', () => {
283
- it('should delete checkpoint from store', async () => {
284
- const context = new ResumableContext({
285
- store,
286
- envelope,
287
- subscriber,
288
- });
289
- await context.io('step-1', () => 'result');
290
- expect(store.size).toBe(1);
291
- await context.clear();
292
- expect(store.size).toBe(0);
293
- });
294
- });
295
- describe('hooks', () => {
296
- it('should call onCheckpointHit when using cached value', async () => {
297
- const onCheckpointHit = vi.fn();
298
- // First execution - populate cache
299
- const firstContext = new ResumableContext({
300
- store,
301
- envelope,
302
- subscriber,
303
- });
304
- await firstContext.io('cached-step', () => 'cached-result');
305
- // Retry with hooks
306
- const checkpoint = await store.get(envelope.id);
307
- const retryContext = new ResumableContext({
308
- store,
309
- envelope: createTestEnvelope(envelope.id, 2),
310
- subscriber,
311
- existingCheckpoint: checkpoint,
312
- hooks: { onCheckpointHit },
313
- });
314
- await retryContext.io('cached-step', () => 'new-result');
315
- expect(onCheckpointHit).toHaveBeenCalledWith({
316
- envelope: expect.anything(),
317
- subscriber,
318
- stepKey: 'cached-step',
319
- });
320
- });
321
- it('should call onCheckpointMiss when executing fresh', async () => {
322
- const onCheckpointMiss = vi.fn();
323
- const context = new ResumableContext({
324
- store,
325
- envelope,
326
- subscriber,
327
- hooks: { onCheckpointMiss },
328
- });
329
- await context.io('fresh-step', () => 'result');
330
- expect(onCheckpointMiss).toHaveBeenCalledWith({
331
- envelope,
332
- subscriber,
333
- stepKey: 'fresh-step',
334
- });
335
- });
336
- });
337
- describe('real-world scenarios', () => {
338
- it('should replay cached steps and execute new ones on retry', async () => {
339
- const executionLog = [];
340
- let shouldFail = true;
341
- // First attempt - fails after step-1
342
- const firstContext = new ResumableContext({
343
- store,
344
- envelope,
345
- subscriber,
346
- });
347
- try {
348
- await firstContext.io('step-0', () => {
349
- executionLog.push('step-0');
350
- return 'result-0';
351
- });
352
- await firstContext.io('step-1', () => {
353
- executionLog.push('step-1');
354
- return 'result-1';
355
- });
356
- if (shouldFail) {
357
- shouldFail = false;
358
- throw new Error('Simulated failure');
359
- }
360
- await firstContext.io('step-2', () => {
361
- executionLog.push('step-2');
362
- return 'result-2';
363
- });
364
- }
365
- catch {
366
- // Expected failure
367
- }
368
- expect(executionLog).toEqual(['step-0', 'step-1']);
369
- // Retry - step-0 and step-1 use cache, step-2 executes
370
- executionLog.length = 0;
371
- const checkpoint = await store.get(envelope.id);
372
- const retryContext = new ResumableContext({
373
- store,
374
- envelope: createTestEnvelope(envelope.id, 2),
375
- subscriber,
376
- existingCheckpoint: checkpoint,
377
- });
378
- await retryContext.io('step-0', () => {
379
- executionLog.push('step-0');
380
- return 'should-not-use';
381
- });
382
- await retryContext.io('step-1', () => {
383
- executionLog.push('step-1');
384
- return 'should-not-use';
385
- });
386
- await retryContext.io('step-2', () => {
387
- executionLog.push('step-2');
388
- return 'result-2';
389
- });
390
- expect(executionLog).toEqual(['step-2']); // Only step-2 executed!
391
- });
392
- it('should handle conditional io() calls correctly', async () => {
393
- const context = new ResumableContext({
394
- store,
395
- envelope: { ...envelope, data: { sendEmail: true } },
396
- subscriber,
397
- });
398
- const result = await context.io('send-email', () => ({
399
- messageId: 'msg-123',
400
- }));
401
- expect(result).toEqual({ messageId: 'msg-123' });
402
- });
403
- it('should handle dynamic loop with unique keys', async () => {
404
- const context = new ResumableContext({
405
- store,
406
- envelope,
407
- subscriber,
408
- });
409
- const items = [
410
- { id: 'item-1', value: 10 },
411
- { id: 'item-2', value: 20 },
412
- { id: 'item-3', value: 30 },
413
- ];
414
- const results = [];
415
- for (const item of items) {
416
- const processed = await context.io(`process-${item.id}`, () => {
417
- return item.value * 2;
418
- });
419
- results.push(processed);
420
- }
421
- expect(results).toEqual([20, 40, 60]);
422
- });
423
- });
424
- });
@@ -1,7 +0,0 @@
1
- export type { Checkpoint, CheckpointClearedContext, CheckpointHitContext, CheckpointLoadedContext, CheckpointMissContext, CheckpointStore, JsonSerializable, SubscriberContext, } from './types.js';
2
- export type { ResumableContextConfig, ResumableContextHooks, } from './context.js';
3
- export { ResumableContext } from './context.js';
4
- export { MemoryCheckpointStore } from './stores/memory.js';
5
- export { NoOpCheckpointStore } from './stores/noop.js';
6
- export { CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from '../errors/index.js';
7
- //# sourceMappingURL=index.d.ts.map
@@ -1 +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"}
@@ -1,6 +0,0 @@
1
- export { ResumableContext } from './context.js';
2
- // Stores
3
- export { MemoryCheckpointStore } from './stores/memory.js';
4
- export { NoOpCheckpointStore } from './stores/noop.js';
5
- // Errors (re-exported from ../errors for convenience)
6
- export { CheckpointStoreError, DuplicateIoKeyError, isCheckpointStoreError, isDuplicateIoKeyError, } from '../errors/index.js';