awaitly 1.34.0 → 2.0.0

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 (241) hide show
  1. package/dist/{duration.d.ts → di-BDlT7InM.d.cts} +15 -1
  2. package/dist/{duration.d.cts → di-BbFFfO8y.d.ts} +15 -1
  3. package/dist/errors-DtXvrCiO.d.cts +708 -0
  4. package/dist/errors-DtXvrCiO.d.ts +708 -0
  5. package/dist/index.cjs +4594 -1
  6. package/dist/index.cjs.map +1 -1
  7. package/dist/index.d.cts +1970 -141
  8. package/dist/index.d.ts +1970 -141
  9. package/dist/index.js +4398 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/result.cjs +641 -1
  12. package/dist/result.cjs.map +1 -1
  13. package/dist/result.d.cts +35 -5
  14. package/dist/result.d.ts +35 -5
  15. package/dist/result.js +561 -1
  16. package/dist/result.js.map +1 -1
  17. package/dist/testing.cjs +4202 -8
  18. package/dist/testing.cjs.map +1 -1
  19. package/dist/testing.d.cts +2 -6
  20. package/dist/testing.d.ts +2 -6
  21. package/dist/testing.js +4154 -8
  22. package/dist/testing.js.map +1 -1
  23. package/dist/{run-entry-D2MmJFj9.d.cts → types-B8NfNRGX.d.ts} +1152 -1499
  24. package/dist/{run-entry-Dduz-is2.d.ts → types-BZ2f4MRR.d.cts} +1152 -1499
  25. package/dist/workflow.cjs +7096 -6
  26. package/dist/workflow.cjs.map +1 -1
  27. package/dist/workflow.d.cts +3346 -22
  28. package/dist/workflow.d.ts +3346 -22
  29. package/dist/workflow.js +6929 -6
  30. package/dist/workflow.js.map +1 -1
  31. package/package.json +13 -178
  32. package/dist/adapters.cjs +0 -7
  33. package/dist/adapters.cjs.map +0 -1
  34. package/dist/adapters.d.cts +0 -179
  35. package/dist/adapters.d.ts +0 -179
  36. package/dist/adapters.js +0 -7
  37. package/dist/adapters.js.map +0 -1
  38. package/dist/batch.cjs +0 -7
  39. package/dist/batch.cjs.map +0 -1
  40. package/dist/batch.d.cts +0 -200
  41. package/dist/batch.d.ts +0 -200
  42. package/dist/batch.js +0 -7
  43. package/dist/batch.js.map +0 -1
  44. package/dist/bind-deps.cjs +0 -2
  45. package/dist/bind-deps.cjs.map +0 -1
  46. package/dist/bind-deps.d.cts +0 -28
  47. package/dist/bind-deps.d.ts +0 -28
  48. package/dist/bind-deps.js +0 -2
  49. package/dist/bind-deps.js.map +0 -1
  50. package/dist/cache.cjs +0 -2
  51. package/dist/cache.cjs.map +0 -1
  52. package/dist/cache.d.cts +0 -269
  53. package/dist/cache.d.ts +0 -269
  54. package/dist/cache.js +0 -2
  55. package/dist/cache.js.map +0 -1
  56. package/dist/circuit-breaker.cjs +0 -7
  57. package/dist/circuit-breaker.cjs.map +0 -1
  58. package/dist/circuit-breaker.d.cts +0 -211
  59. package/dist/circuit-breaker.d.ts +0 -211
  60. package/dist/circuit-breaker.js +0 -7
  61. package/dist/circuit-breaker.js.map +0 -1
  62. package/dist/conditional.cjs +0 -2
  63. package/dist/conditional.cjs.map +0 -1
  64. package/dist/conditional.d.cts +0 -252
  65. package/dist/conditional.d.ts +0 -252
  66. package/dist/conditional.js +0 -2
  67. package/dist/conditional.js.map +0 -1
  68. package/dist/core.cjs +0 -7
  69. package/dist/core.cjs.map +0 -1
  70. package/dist/core.d.cts +0 -5
  71. package/dist/core.d.ts +0 -5
  72. package/dist/core.js +0 -7
  73. package/dist/core.js.map +0 -1
  74. package/dist/di-COl5oFnR.d.cts +0 -15
  75. package/dist/di-CyDj_JyZ.d.ts +0 -15
  76. package/dist/diagnostics.cjs +0 -8
  77. package/dist/diagnostics.cjs.map +0 -1
  78. package/dist/diagnostics.d.cts +0 -68
  79. package/dist/diagnostics.d.ts +0 -68
  80. package/dist/diagnostics.js +0 -8
  81. package/dist/diagnostics.js.map +0 -1
  82. package/dist/durable.cjs +0 -11
  83. package/dist/durable.cjs.map +0 -1
  84. package/dist/durable.d.cts +0 -9
  85. package/dist/durable.d.ts +0 -9
  86. package/dist/durable.js +0 -11
  87. package/dist/durable.js.map +0 -1
  88. package/dist/duration.cjs +0 -2
  89. package/dist/duration.cjs.map +0 -1
  90. package/dist/duration.js +0 -2
  91. package/dist/duration.js.map +0 -1
  92. package/dist/engine.cjs +0 -11
  93. package/dist/engine.cjs.map +0 -1
  94. package/dist/engine.d.cts +0 -115
  95. package/dist/engine.d.ts +0 -115
  96. package/dist/engine.js +0 -11
  97. package/dist/engine.js.map +0 -1
  98. package/dist/errors.cjs +0 -2
  99. package/dist/errors.cjs.map +0 -1
  100. package/dist/errors.d.cts +0 -361
  101. package/dist/errors.d.ts +0 -361
  102. package/dist/errors.js +0 -2
  103. package/dist/errors.js.map +0 -1
  104. package/dist/fetch.cjs +0 -7
  105. package/dist/fetch.cjs.map +0 -1
  106. package/dist/fetch.d.cts +0 -86
  107. package/dist/fetch.d.ts +0 -86
  108. package/dist/fetch.js +0 -7
  109. package/dist/fetch.js.map +0 -1
  110. package/dist/flow.cjs +0 -7
  111. package/dist/flow.cjs.map +0 -1
  112. package/dist/flow.d.cts +0 -163
  113. package/dist/flow.d.ts +0 -163
  114. package/dist/flow.js +0 -7
  115. package/dist/flow.js.map +0 -1
  116. package/dist/functional.cjs +0 -2
  117. package/dist/functional.cjs.map +0 -1
  118. package/dist/functional.d.cts +0 -444
  119. package/dist/functional.d.ts +0 -444
  120. package/dist/functional.js +0 -2
  121. package/dist/functional.js.map +0 -1
  122. package/dist/guards-BodHXLzX.d.cts +0 -72
  123. package/dist/guards-CeWoQ8fn.d.ts +0 -72
  124. package/dist/hitl-BPE_1UiM.d.cts +0 -468
  125. package/dist/hitl-byp570uC.d.ts +0 -468
  126. package/dist/hitl.cjs +0 -7
  127. package/dist/hitl.cjs.map +0 -1
  128. package/dist/hitl.d.cts +0 -442
  129. package/dist/hitl.d.ts +0 -442
  130. package/dist/hitl.js +0 -7
  131. package/dist/hitl.js.map +0 -1
  132. package/dist/index-BYT3amEz.d.ts +0 -417
  133. package/dist/index-C_ak66jy.d.cts +0 -417
  134. package/dist/match-entry-DjI2bLpD.d.cts +0 -209
  135. package/dist/match-entry-DjI2bLpD.d.ts +0 -209
  136. package/dist/match.cjs +0 -2
  137. package/dist/match.cjs.map +0 -1
  138. package/dist/match.d.cts +0 -1
  139. package/dist/match.d.ts +0 -1
  140. package/dist/match.js +0 -2
  141. package/dist/match.js.map +0 -1
  142. package/dist/otel.cjs +0 -2
  143. package/dist/otel.cjs.map +0 -1
  144. package/dist/otel.d.cts +0 -188
  145. package/dist/otel.d.ts +0 -188
  146. package/dist/otel.js +0 -2
  147. package/dist/otel.js.map +0 -1
  148. package/dist/persistence-entry-DOMx3woy.d.ts +0 -822
  149. package/dist/persistence-entry-ymCA4iDu.d.cts +0 -822
  150. package/dist/persistence.cjs +0 -2
  151. package/dist/persistence.cjs.map +0 -1
  152. package/dist/persistence.d.cts +0 -7
  153. package/dist/persistence.d.ts +0 -7
  154. package/dist/persistence.js +0 -2
  155. package/dist/persistence.js.map +0 -1
  156. package/dist/policies.cjs +0 -2
  157. package/dist/policies.cjs.map +0 -1
  158. package/dist/policies.d.cts +0 -379
  159. package/dist/policies.d.ts +0 -379
  160. package/dist/policies.js +0 -2
  161. package/dist/policies.js.map +0 -1
  162. package/dist/ratelimit.cjs +0 -7
  163. package/dist/ratelimit.cjs.map +0 -1
  164. package/dist/ratelimit.d.cts +0 -458
  165. package/dist/ratelimit.d.ts +0 -458
  166. package/dist/ratelimit.js +0 -7
  167. package/dist/ratelimit.js.map +0 -1
  168. package/dist/reliability.cjs +0 -11
  169. package/dist/reliability.cjs.map +0 -1
  170. package/dist/reliability.d.cts +0 -11
  171. package/dist/reliability.d.ts +0 -11
  172. package/dist/reliability.js +0 -11
  173. package/dist/reliability.js.map +0 -1
  174. package/dist/resolver.cjs +0 -7
  175. package/dist/resolver.cjs.map +0 -1
  176. package/dist/resolver.d.cts +0 -68
  177. package/dist/resolver.d.ts +0 -68
  178. package/dist/resolver.js +0 -7
  179. package/dist/resolver.js.map +0 -1
  180. package/dist/resource.cjs +0 -7
  181. package/dist/resource.cjs.map +0 -1
  182. package/dist/resource.d.cts +0 -174
  183. package/dist/resource.d.ts +0 -174
  184. package/dist/resource.js +0 -7
  185. package/dist/resource.js.map +0 -1
  186. package/dist/result/retry.cjs +0 -2
  187. package/dist/result/retry.cjs.map +0 -1
  188. package/dist/result/retry.d.cts +0 -70
  189. package/dist/result/retry.d.ts +0 -70
  190. package/dist/result/retry.js +0 -2
  191. package/dist/result/retry.js.map +0 -1
  192. package/dist/retry.cjs +0 -2
  193. package/dist/retry.cjs.map +0 -1
  194. package/dist/retry.d.cts +0 -388
  195. package/dist/retry.d.ts +0 -388
  196. package/dist/retry.js +0 -2
  197. package/dist/retry.js.map +0 -1
  198. package/dist/run.cjs +0 -7
  199. package/dist/run.cjs.map +0 -1
  200. package/dist/run.d.cts +0 -4
  201. package/dist/run.d.ts +0 -4
  202. package/dist/run.js +0 -7
  203. package/dist/run.js.map +0 -1
  204. package/dist/saga.cjs +0 -11
  205. package/dist/saga.cjs.map +0 -1
  206. package/dist/saga.d.cts +0 -164
  207. package/dist/saga.d.ts +0 -164
  208. package/dist/saga.js +0 -11
  209. package/dist/saga.js.map +0 -1
  210. package/dist/singleflight.cjs +0 -2
  211. package/dist/singleflight.cjs.map +0 -1
  212. package/dist/singleflight.d.cts +0 -145
  213. package/dist/singleflight.d.ts +0 -145
  214. package/dist/singleflight.js +0 -2
  215. package/dist/singleflight.js.map +0 -1
  216. package/dist/slugs.cjs +0 -2
  217. package/dist/slugs.cjs.map +0 -1
  218. package/dist/slugs.d.cts +0 -67
  219. package/dist/slugs.d.ts +0 -67
  220. package/dist/slugs.js +0 -2
  221. package/dist/slugs.js.map +0 -1
  222. package/dist/streaming.cjs +0 -9
  223. package/dist/streaming.cjs.map +0 -1
  224. package/dist/streaming.d.cts +0 -596
  225. package/dist/streaming.d.ts +0 -596
  226. package/dist/streaming.js +0 -9
  227. package/dist/streaming.js.map +0 -1
  228. package/dist/tagged-error.cjs +0 -2
  229. package/dist/tagged-error.cjs.map +0 -1
  230. package/dist/tagged-error.d.cts +0 -275
  231. package/dist/tagged-error.d.ts +0 -275
  232. package/dist/tagged-error.js +0 -2
  233. package/dist/tagged-error.js.map +0 -1
  234. package/dist/types-DQmzO9f4.d.ts +0 -323
  235. package/dist/types-qBUOYi-4.d.cts +0 -323
  236. package/dist/webhook.cjs +0 -7
  237. package/dist/webhook.cjs.map +0 -1
  238. package/dist/webhook.d.cts +0 -499
  239. package/dist/webhook.d.ts +0 -499
  240. package/dist/webhook.js +0 -7
  241. package/dist/webhook.js.map +0 -1
package/dist/webhook.d.cts DELETED
@@ -1,499 +0,0 @@
1
- import { R as Result, c as AsyncResult, ah as RunStep } from './run-entry-D2MmJFj9.cjs';
2
- import { a as Workflow } from './persistence-entry-ymCA4iDu.cjs';
3
- import { UnexpectedError } from './errors.cjs';
4
- import './types-qBUOYi-4.cjs';
5
- import '@standard-schema/spec';
6
- import './tagged-error.cjs';
7
- import './slugs.cjs';
8
-
9
- /**
10
- * awaitly/webhook
11
- *
12
- * Webhook and event trigger adapters for exposing workflows as HTTP endpoints.
13
- * Framework-agnostic handlers that work with Express, Hono, Fastify, etc.
14
- */
15
-
16
- /**
17
- * Generic HTTP request representation.
18
- * Abstracts away framework-specific request objects.
19
- */
20
- interface WebhookRequest<Body = unknown> {
21
- /** HTTP method (GET, POST, PUT, DELETE, etc.) */
22
- method: string;
23
- /** Request path (e.g., "/api/checkout") */
24
- path: string;
25
- /** Request headers */
26
- headers: Record<string, string | string[] | undefined>;
27
- /** Parsed request body (JSON) */
28
- body: Body;
29
- /** Query parameters */
30
- query: Record<string, string | string[] | undefined>;
31
- /** Path parameters (e.g., { id: "123" }) */
32
- params: Record<string, string>;
33
- /** Raw request object from framework (for advanced use cases) */
34
- raw?: unknown;
35
- }
36
- /**
37
- * Generic HTTP response representation.
38
- */
39
- interface WebhookResponse<T = unknown> {
40
- /** HTTP status code */
41
- status: number;
42
- /** Response headers */
43
- headers?: Record<string, string>;
44
- /** Response body (will be JSON serialized) */
45
- body: T;
46
- }
47
- /**
48
- * Error response body structure.
49
- */
50
- interface ErrorResponseBody {
51
- error: {
52
- type: string;
53
- message?: string;
54
- details?: unknown;
55
- };
56
- }
57
- /**
58
- * Input validation result.
59
- */
60
- type ValidationResult<T, E = string> = Result<T, E>;
61
- /**
62
- * Standard validation error type.
63
- */
64
- interface ValidationError {
65
- type: "VALIDATION_ERROR";
66
- message: string;
67
- field?: string;
68
- details?: unknown;
69
- }
70
- /**
71
- * Type guard for ValidationError.
72
- */
73
- declare function isValidationError(e: unknown): e is ValidationError;
74
- /**
75
- * Configuration for creating a webhook handler.
76
- *
77
- * @template TInput - The validated input type
78
- * @template TOutput - The workflow output type
79
- * @template TError - The workflow error type
80
- * @template TBody - The raw request body type
81
- * @template TUnexpected - The workflow's unexpected error type (default UnexpectedError)
82
- */
83
- interface WebhookHandlerConfig<TInput, TOutput, TError, TBody = unknown, TUnexpected = UnexpectedError> {
84
- /**
85
- * Validate and transform the incoming request.
86
- * Return ok(input) to proceed, or err(validationError) to reject.
87
- *
88
- * @param req - The incoming request
89
- * @returns Validated input or validation error
90
- */
91
- validateInput: (req: WebhookRequest<TBody>) => ValidationResult<TInput, ValidationError> | Promise<ValidationResult<TInput, ValidationError>>;
92
- /**
93
- * Map workflow result to HTTP response.
94
- * Called for both success and error cases.
95
- *
96
- * @param result - The workflow result (error union is TError | TUnexpected)
97
- * @param req - The original request (for context)
98
- * @returns HTTP response
99
- */
100
- mapResult: (result: Result<TOutput, TError | TUnexpected>, req: WebhookRequest<TBody>) => WebhookResponse;
101
- /**
102
- * Optional: Map validation errors to HTTP response.
103
- * Defaults to 400 Bad Request with error details.
104
- *
105
- * @param error - The validation error
106
- * @param req - The original request
107
- * @returns HTTP response
108
- */
109
- mapValidationError?: (error: ValidationError, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
110
- /**
111
- * Optional: Handle unexpected errors during request processing.
112
- * Defaults to 500 Internal Server Error.
113
- *
114
- * @param error - The unexpected error
115
- * @param req - The original request
116
- * @returns HTTP response
117
- */
118
- mapUnexpectedError?: (error: unknown, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
119
- /**
120
- * Optional: Request middleware.
121
- * Transform or enrich the request before validation.
122
- *
123
- * @param req - The incoming request
124
- * @returns Transformed request
125
- */
126
- beforeValidation?: (req: WebhookRequest<TBody>) => WebhookRequest<TBody> | Promise<WebhookRequest<TBody>>;
127
- /**
128
- * Optional: Response middleware.
129
- * Transform the response before sending.
130
- *
131
- * @param response - The response to send
132
- * @param req - The original request
133
- * @returns Transformed response
134
- */
135
- afterResponse?: (response: WebhookResponse, req: WebhookRequest<TBody>) => WebhookResponse | Promise<WebhookResponse>;
136
- }
137
- /**
138
- * A webhook handler function that processes requests.
139
- */
140
- type WebhookHandler<TBody = unknown> = (req: WebhookRequest<TBody>) => Promise<WebhookResponse>;
141
- /**
142
- * Default validation error mapper.
143
- * Returns 400 Bad Request with error details.
144
- */
145
- declare function defaultValidationErrorMapper(error: ValidationError): WebhookResponse<ErrorResponseBody>;
146
- /**
147
- * Default unexpected error mapper.
148
- * Returns 500 Internal Server Error.
149
- */
150
- declare function defaultUnexpectedErrorMapper(error: unknown): WebhookResponse<ErrorResponseBody>;
151
- /**
152
- * Create a webhook handler for a workflow.
153
- *
154
- * This factory creates an HTTP handler function that:
155
- * 1. Validates the incoming request
156
- * 2. Executes the workflow with the validated input
157
- * 3. Maps the result to an HTTP response
158
- *
159
- * The handler is framework-agnostic and returns a standard response object.
160
- * Use framework adapters (createExpressHandler, createHonoHandler, etc.) to
161
- * integrate with specific frameworks.
162
- *
163
- * @template TInput - The validated input type passed to the workflow
164
- * @template TOutput - The workflow output type
165
- * @template TError - The workflow error type
166
- * @template TBody - The raw request body type
167
- * @template TDeps - The workflow dependencies type
168
- *
169
- * @param workflow - The workflow function to execute
170
- * @param workflowFn - The workflow body function ({ step, deps, args }) => output
171
- * @param config - Handler configuration
172
- * @returns A webhook handler function
173
- *
174
- * @example
175
- * ```typescript
176
- * const checkoutWorkflow = createWorkflow('checkout', { chargeCard, sendEmail });
177
- *
178
- * const handler = createWebhookHandler(
179
- * checkoutWorkflow,
180
- * async ({ step, deps, args: input }) => {
181
- * const charge = await step('chargeCard', () => deps.chargeCard(input.amount));
182
- * await step('sendEmail', () => deps.sendEmail(input.email, charge.receiptUrl));
183
- * return { chargeId: charge.id };
184
- * },
185
- * {
186
- * validateInput: (req) => {
187
- * const { amount, email } = req.body;
188
- * if (!amount || !email) {
189
- * return err({ type: 'VALIDATION_ERROR', message: 'Missing required fields' });
190
- * }
191
- * return ok({ amount, email });
192
- * },
193
- * mapResult: (result) => {
194
- * if (result.ok) {
195
- * return { status: 200, body: result.value };
196
- * }
197
- * if (result.error === 'CARD_DECLINED') {
198
- * return { status: 402, body: { error: { type: 'CARD_DECLINED' } } };
199
- * }
200
- * return { status: 500, body: { error: { type: 'UNKNOWN' } } };
201
- * },
202
- * }
203
- * );
204
- *
205
- * // Use with Express
206
- * app.post('/checkout', async (req, res) => {
207
- * const response = await handler(toWebhookRequest(req));
208
- * res.status(response.status).json(response.body);
209
- * });
210
- * ```
211
- */
212
- declare function createWebhookHandler<TInput, TOutput, TError, TUnexpected, TBody = unknown, TDeps = unknown>(workflow: Workflow<TError, TUnexpected, TDeps>, workflowFn: (context: {
213
- step: RunStep<TError | TUnexpected>;
214
- deps: TDeps;
215
- args: TInput;
216
- }) => TOutput | Promise<TOutput>, config: WebhookHandlerConfig<TInput, TOutput, TError, TBody, TUnexpected>): WebhookHandler<TBody>;
217
- declare function createWebhookHandler<TInput, TOutput, TError, TBody = unknown, TDeps = unknown>(workflow: Workflow<TError, UnexpectedError, TDeps>, workflowFn: (context: {
218
- step: RunStep<TError | UnexpectedError>;
219
- deps: TDeps;
220
- args: TInput;
221
- }) => TOutput | Promise<TOutput>, config: WebhookHandlerConfig<TInput, TOutput, TError, TBody, UnexpectedError>): WebhookHandler<TBody>;
222
- /**
223
- * Configuration for a simple webhook handler without workflow.
224
- * Use with createSimpleHandler for endpoints that don't need step orchestration.
225
- *
226
- * @template TInput - Validated input type
227
- * @template TOutput - Handler success output type
228
- * @template TError - Handler error type
229
- * @template TBody - Raw request body type
230
- */
231
- interface SimpleHandlerConfig<TInput, TOutput, TError, TBody = unknown> {
232
- /** Validate and transform the incoming request; return ok(input) or err(ValidationError). */
233
- validateInput: (req: WebhookRequest<TBody>) => ValidationResult<TInput, ValidationError> | Promise<ValidationResult<TInput, ValidationError>>;
234
- /** Execute the business logic; return Result. */
235
- handler: (input: TInput, req: WebhookRequest<TBody>) => AsyncResult<TOutput, TError>;
236
- /** Map the handler result to an HTTP response. */
237
- mapResult: (result: Result<TOutput, TError>, req: WebhookRequest<TBody>) => WebhookResponse;
238
- /** Optional: map validation errors to response. Defaults to 400 with error details. */
239
- mapValidationError?: (error: ValidationError, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
240
- /** Optional: handle unexpected errors. Defaults to 500. */
241
- mapUnexpectedError?: (error: unknown, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
242
- }
243
- /**
244
- * Create a simple webhook handler without workflow orchestration.
245
- * Useful for simple endpoints that don't need step-based error handling.
246
- *
247
- * @example
248
- * ```typescript
249
- * const handler = createSimpleHandler({
250
- * validateInput: (req) => {
251
- * const { id } = req.params;
252
- * if (!id) return err({ type: 'VALIDATION_ERROR', message: 'Missing id' });
253
- * return ok({ id });
254
- * },
255
- * handler: async ({ id }) => {
256
- * const user = await db.findUser(id);
257
- * return user ? ok(user) : err('NOT_FOUND' as const);
258
- * },
259
- * mapResult: (result) => {
260
- * if (result.ok) return { status: 200, body: result.value };
261
- * return { status: 404, body: { error: { type: 'NOT_FOUND' } } };
262
- * },
263
- * });
264
- * ```
265
- */
266
- declare function createSimpleHandler<TInput, TOutput, TError, TBody = unknown>(config: SimpleHandlerConfig<TInput, TOutput, TError, TBody>): WebhookHandler<TBody>;
267
- /**
268
- * Standard error mapping configuration.
269
- */
270
- interface ErrorMapping<TError> {
271
- /** The error value to match */
272
- error: TError;
273
- /** HTTP status code for this error */
274
- status: number;
275
- /** Optional custom message */
276
- message?: string;
277
- }
278
- /**
279
- * Create a result mapper from error mappings.
280
- * Provides a declarative way to map workflow errors to HTTP responses.
281
- *
282
- * @param mappings - Array of error mappings
283
- * @param defaultStatus - Default status for unmapped errors (default: 500)
284
- * @returns A mapResult function for use in handler config
285
- *
286
- * @example
287
- * ```typescript
288
- * const mapResult = createResultMapper<CheckoutOutput, CheckoutError>([
289
- * { error: 'NOT_FOUND', status: 404, message: 'Resource not found' },
290
- * { error: 'CARD_DECLINED', status: 402, message: 'Payment failed' },
291
- * { error: 'RATE_LIMITED', status: 429, message: 'Too many requests' },
292
- * ]);
293
- *
294
- * const handler = createWebhookHandler(workflow, workflowFn, {
295
- * validateInput,
296
- * mapResult,
297
- * });
298
- * ```
299
- */
300
- declare function createResultMapper<TOutput, TError>(mappings: ErrorMapping<TError>[], options?: {
301
- defaultStatus?: number;
302
- successStatus?: number;
303
- }): (result: Result<TOutput, TError | UnexpectedError>) => WebhookResponse;
304
- /**
305
- * Express-style request object (minimal interface).
306
- */
307
- interface ExpressLikeRequest {
308
- method: string;
309
- path: string;
310
- headers: Record<string, string | string[] | undefined>;
311
- body: unknown;
312
- query: Record<string, string | string[] | undefined>;
313
- params: Record<string, string>;
314
- }
315
- /**
316
- * Express-style response object (minimal interface).
317
- */
318
- interface ExpressLikeResponse {
319
- status(code: number): ExpressLikeResponse;
320
- set(headers: Record<string, string>): ExpressLikeResponse;
321
- json(body: unknown): void;
322
- }
323
- /**
324
- * Convert an Express-like request to WebhookRequest.
325
- *
326
- * @param req - Express-like request object
327
- * @returns WebhookRequest
328
- *
329
- * @example
330
- * ```typescript
331
- * app.post('/checkout', async (req, res) => {
332
- * const webhookReq = toWebhookRequest(req);
333
- * const response = await handler(webhookReq);
334
- * res.status(response.status).json(response.body);
335
- * });
336
- * ```
337
- */
338
- declare function toWebhookRequest<TBody = unknown>(req: ExpressLikeRequest): WebhookRequest<TBody>;
339
- /**
340
- * Send a WebhookResponse using an Express-like response object.
341
- *
342
- * @param res - Express-like response object
343
- * @param response - WebhookResponse to send
344
- *
345
- * @example
346
- * ```typescript
347
- * app.post('/checkout', async (req, res) => {
348
- * const response = await handler(toWebhookRequest(req));
349
- * sendWebhookResponse(res, response);
350
- * });
351
- * ```
352
- */
353
- declare function sendWebhookResponse(res: ExpressLikeResponse, response: WebhookResponse): void;
354
- /**
355
- * Create an Express-compatible middleware from a webhook handler.
356
- *
357
- * @param handler - Webhook handler function
358
- * @returns Express middleware function
359
- *
360
- * @example
361
- * ```typescript
362
- * const handler = createWebhookHandler(workflow, workflowFn, config);
363
- * const middleware = createExpressHandler(handler);
364
- * app.post('/checkout', middleware);
365
- * ```
366
- */
367
- declare function createExpressHandler<TBody = unknown>(handler: WebhookHandler<TBody>): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<void>;
368
- /**
369
- * Create a validation error.
370
- *
371
- * @param message - Error message
372
- * @param field - Optional field name
373
- * @param details - Optional additional details
374
- * @returns ValidationError
375
- */
376
- declare function validationError(message: string, field?: string, details?: unknown): ValidationError;
377
- /**
378
- * Create a required field validator.
379
- *
380
- * @param fields - Field names to validate
381
- * @returns Validation function
382
- *
383
- * @example
384
- * ```typescript
385
- * const validateRequired = requireFields(['email', 'password']);
386
- *
387
- * const validateInput = (req) => {
388
- * const result = validateRequired(req.body);
389
- * if (!result.ok) return result;
390
- * return ok(req.body as LoginInput);
391
- * };
392
- * ```
393
- */
394
- declare function requireFields(fields: string[]): (body: Record<string, unknown>) => ValidationResult<void, ValidationError>;
395
- /**
396
- * Compose multiple validators into a single validator.
397
- *
398
- * @param validators - Validators to compose
399
- * @returns Combined validator function
400
- *
401
- * @example
402
- * ```typescript
403
- * const validate = composeValidators(
404
- * requireFields(['email', 'password']),
405
- * validateEmailFormat,
406
- * validatePasswordStrength
407
- * );
408
- * ```
409
- */
410
- declare function composeValidators<T>(...validators: Array<(input: T) => ValidationResult<void, ValidationError>>): (input: T) => ValidationResult<void, ValidationError>;
411
- /**
412
- * Generic event message for queue-based triggers.
413
- */
414
- interface EventMessage<T = unknown> {
415
- /** Unique message ID */
416
- id: string;
417
- /** Event type/name */
418
- type: string;
419
- /** Event payload */
420
- payload: T;
421
- /** Event metadata */
422
- metadata?: {
423
- timestamp?: number;
424
- source?: string;
425
- correlationId?: string;
426
- [key: string]: unknown;
427
- };
428
- }
429
- /**
430
- * Result of processing an event.
431
- */
432
- interface EventProcessingResult {
433
- /** Whether the event was processed successfully */
434
- success: boolean;
435
- /** Should the message be acknowledged (removed from queue)? */
436
- ack: boolean;
437
- /** Optional error details */
438
- error?: {
439
- type: string;
440
- message?: string;
441
- retryable?: boolean;
442
- };
443
- }
444
- /**
445
- * Configuration for event trigger handlers.
446
- */
447
- interface EventTriggerConfig<TPayload, TOutput, TError, TUnexpected = UnexpectedError> {
448
- /** Validate the event payload */
449
- validatePayload: (event: EventMessage<TPayload>) => ValidationResult<TPayload, ValidationError>;
450
- /** Map workflow result to processing result */
451
- mapResult: (result: Result<TOutput, TError | TUnexpected>, event: EventMessage<TPayload>) => EventProcessingResult;
452
- /** Optional: Determine if error is retryable */
453
- isRetryable?: (error: TError | TUnexpected) => boolean;
454
- }
455
- /**
456
- * Event handler function type.
457
- */
458
- type EventHandler<TPayload = unknown> = (event: EventMessage<TPayload>) => Promise<EventProcessingResult>;
459
- /**
460
- * Create an event handler for queue-based triggers.
461
- *
462
- * @example
463
- * ```typescript
464
- * const handler = createEventHandler(
465
- * checkoutWorkflow,
466
- * async ({ step, deps, args: payload }) => {
467
- * const charge = await step('chargeCard', () => deps.chargeCard(payload.amount));
468
- * return { chargeId: charge.id };
469
- * },
470
- * {
471
- * validatePayload: (event) => {
472
- * if (!event.payload.amount) {
473
- * return err({ type: 'VALIDATION_ERROR', message: 'Missing amount' });
474
- * }
475
- * return ok(event.payload);
476
- * },
477
- * mapResult: (result) => ({
478
- * success: result.ok,
479
- * ack: result.ok || !isRetryableError(result.error),
480
- * error: result.ok ? undefined : { type: String(result.error) },
481
- * }),
482
- * }
483
- * );
484
- *
485
- * // Use with SQS, RabbitMQ, etc.
486
- * queue.consume(async (message) => {
487
- * const result = await handler(message);
488
- * if (result.ack) await message.ack();
489
- * else await message.nack();
490
- * });
491
- * ```
492
- */
493
- declare function createEventHandler<TPayload, TOutput, TError, TDeps = unknown, TUnexpected = UnexpectedError>(workflow: Workflow<TError, TUnexpected, TDeps>, workflowFn: (context: {
494
- step: RunStep<TError | TUnexpected>;
495
- deps: TDeps;
496
- args: TPayload;
497
- }) => TOutput | Promise<TOutput>, config: EventTriggerConfig<TPayload, TOutput, TError, TUnexpected>): EventHandler<TPayload>;
498
-
499
- export { type ErrorMapping, type ErrorResponseBody, type EventHandler, type EventMessage, type EventProcessingResult, type EventTriggerConfig, type ExpressLikeRequest, type ExpressLikeResponse, type SimpleHandlerConfig, type ValidationError, type ValidationResult, type WebhookHandler, type WebhookHandlerConfig, type WebhookRequest, type WebhookResponse, composeValidators, createEventHandler, createExpressHandler, createResultMapper, createSimpleHandler, createWebhookHandler, defaultUnexpectedErrorMapper, defaultValidationErrorMapper, isValidationError, requireFields, sendWebhookResponse, toWebhookRequest, validationError };