npm - awaitly - Versions diffs - 2.0.0 → 3.0.0 - Mend

awaitly 2.0.0 → 3.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 (88) hide show

package/dist/di-Biw_plBn.d.cts +15 -0
package/dist/di-DxyH2N3i.d.ts +15 -0
package/dist/durable.cjs +4670 -0
package/dist/durable.cjs.map +1 -0
package/dist/durable.d.cts +9 -0
package/dist/durable.d.ts +9 -0
package/dist/durable.js +4610 -0
package/dist/durable.js.map +1 -0
package/dist/{di-BbFFfO8y.d.ts → duration-BjVn3QpB.d.cts} +1 -15
package/dist/{di-BDlT7InM.d.cts → duration-BjVn3QpB.d.ts} +1 -15
package/dist/engine.cjs +4501 -0
package/dist/engine.cjs.map +1 -0
package/dist/engine.d.cts +113 -0
package/dist/engine.d.ts +113 -0
package/dist/engine.js +4474 -0
package/dist/engine.js.map +1 -0
package/dist/{errors-DtXvrCiO.d.cts → errors-sDSeaZBO.d.cts} +1 -1
package/dist/{errors-DtXvrCiO.d.ts → errors-sDSeaZBO.d.ts} +1 -1
package/dist/guards-CwQZro1F.d.ts +72 -0
package/dist/guards-DhhOJZda.d.cts +72 -0
package/dist/hitl-BnnnLzh2.d.cts +468 -0
package/dist/hitl-pYfkQMv_.d.ts +468 -0
package/dist/hitl.cjs +646 -0
package/dist/hitl.cjs.map +1 -0
package/dist/hitl.d.cts +440 -0
package/dist/hitl.d.ts +440 -0
package/dist/hitl.js +605 -0
package/dist/hitl.js.map +1 -0
package/dist/index-Bew12SZ8.d.ts +417 -0
package/dist/index-Bwt-iz50.d.cts +417 -0
package/dist/{types-B8NfNRGX.d.ts → index-Cv4K_3sZ.d.ts} +2 -1162
package/dist/{types-BZ2f4MRR.d.cts → index-ICmfQi08.d.cts} +2 -1162
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +11 -1527
package/dist/index.d.ts +11 -1527
package/dist/persistence.cjs +552 -0
package/dist/persistence.cjs.map +1 -0
package/dist/persistence.d.cts +254 -0
package/dist/persistence.d.ts +254 -0
package/dist/persistence.js +499 -0
package/dist/persistence.js.map +1 -0
package/dist/reliability.cjs +1651 -0
package/dist/reliability.cjs.map +1 -0
package/dist/reliability.d.cts +1442 -0
package/dist/reliability.d.ts +1442 -0
package/dist/reliability.js +1589 -0
package/dist/reliability.js.map +1 -0
package/dist/result.d.cts +1 -1
package/dist/result.d.ts +1 -1
package/dist/run.cjs +2283 -0
package/dist/run.cjs.map +1 -0
package/dist/run.d.cts +90 -0
package/dist/run.d.ts +90 -0
package/dist/run.js +2247 -0
package/dist/run.js.map +1 -0
package/dist/saga.cjs +3699 -0
package/dist/saga.cjs.map +1 -0
package/dist/saga.d.cts +162 -0
package/dist/saga.d.ts +162 -0
package/dist/saga.js +3670 -0
package/dist/saga.js.map +1 -0
package/dist/store-contract-BI98VYmX.d.ts +66 -0
package/dist/store-contract-C2HyR_o6.d.cts +66 -0
package/dist/streaming.cjs +895 -0
package/dist/streaming.cjs.map +1 -0
package/dist/streaming.d.cts +594 -0
package/dist/streaming.d.ts +594 -0
package/dist/streaming.js +832 -0
package/dist/streaming.js.map +1 -0
package/dist/testing.d.cts +4 -2
package/dist/testing.d.ts +4 -2
package/dist/types-BDTxgKKc.d.ts +845 -0
package/dist/types-C9Y71dua.d.cts +845 -0
package/dist/types-d8q8iQlk.d.cts +323 -0
package/dist/types-sObbY4mX.d.ts +323 -0
package/dist/webhook.cjs +461 -0
package/dist/webhook.cjs.map +1 -0
package/dist/webhook.d.cts +497 -0
package/dist/webhook.d.ts +497 -0
package/dist/webhook.js +422 -0
package/dist/webhook.js.map +1 -0
package/dist/workflow.cjs +2 -2614
package/dist/workflow.cjs.map +1 -1
package/dist/workflow.d.cts +12 -3023
package/dist/workflow.d.ts +12 -3023
package/dist/workflow.js +2 -2535
package/dist/workflow.js.map +1 -1
package/package.json +46 -1

package/dist/webhook.d.cts ADDED Viewed

@@ -0,0 +1,497 @@
+import { R as Result, A as AsyncResult, a as RunStep } from './index-ICmfQi08.cjs';
+import { W as Workflow } from './types-C9Y71dua.cjs';
+import { U as UnexpectedError } from './errors-sDSeaZBO.cjs';
+import './types-d8q8iQlk.cjs';
+import '@standard-schema/spec';
+/**
+ * awaitly/webhook
+ *
+ * Webhook and event trigger adapters for exposing workflows as HTTP endpoints.
+ * Framework-agnostic handlers that work with Express, Hono, Fastify, etc.
+ */
+/**
+ * Generic HTTP request representation.
+ * Abstracts away framework-specific request objects.
+ */
+interface WebhookRequest<Body = unknown> {
+    /** HTTP method (GET, POST, PUT, DELETE, etc.) */
+    method: string;
+    /** Request path (e.g., "/api/checkout") */
+    path: string;
+    /** Request headers */
+    headers: Record<string, string | string[] | undefined>;
+    /** Parsed request body (JSON) */
+    body: Body;
+    /** Query parameters */
+    query: Record<string, string | string[] | undefined>;
+    /** Path parameters (e.g., { id: "123" }) */
+    params: Record<string, string>;
+    /** Raw request object from framework (for advanced use cases) */
+    raw?: unknown;
+}
+/**
+ * Generic HTTP response representation.
+ */
+interface WebhookResponse<T = unknown> {
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Response body (will be JSON serialized) */
+    body: T;
+}
+/**
+ * Error response body structure.
+ */
+interface ErrorResponseBody {
+    error: {
+        type: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * Input validation result.
+ */
+type ValidationResult<T, E = string> = Result<T, E>;
+/**
+ * Standard validation error type.
+ */
+interface ValidationError {
+    type: "VALIDATION_ERROR";
+    message: string;
+    field?: string;
+    details?: unknown;
+}
+/**
+ * Type guard for ValidationError.
+ */
+declare function isValidationError(e: unknown): e is ValidationError;
+/**
+ * Configuration for creating a webhook handler.
+ *
+ * @template TInput - The validated input type
+ * @template TOutput - The workflow output type
+ * @template TError - The workflow error type
+ * @template TBody - The raw request body type
+ * @template TUnexpected - The workflow's unexpected error type (default UnexpectedError)
+ */
+interface WebhookHandlerConfig<TInput, TOutput, TError, TBody = unknown, TUnexpected = UnexpectedError> {
+    /**
+     * Validate and transform the incoming request.
+     * Return ok(input) to proceed, or err(validationError) to reject.
+     *
+     * @param req - The incoming request
+     * @returns Validated input or validation error
+     */
+    validateInput: (req: WebhookRequest<TBody>) => ValidationResult<TInput, ValidationError> | Promise<ValidationResult<TInput, ValidationError>>;
+    /**
+     * Map workflow result to HTTP response.
+     * Called for both success and error cases.
+     *
+     * @param result - The workflow result (error union is TError | TUnexpected)
+     * @param req - The original request (for context)
+     * @returns HTTP response
+     */
+    mapResult: (result: Result<TOutput, TError | TUnexpected>, req: WebhookRequest<TBody>) => WebhookResponse;
+    /**
+     * Optional: Map validation errors to HTTP response.
+     * Defaults to 400 Bad Request with error details.
+     *
+     * @param error - The validation error
+     * @param req - The original request
+     * @returns HTTP response
+     */
+    mapValidationError?: (error: ValidationError, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+    /**
+     * Optional: Handle unexpected errors during request processing.
+     * Defaults to 500 Internal Server Error.
+     *
+     * @param error - The unexpected error
+     * @param req - The original request
+     * @returns HTTP response
+     */
+    mapUnexpectedError?: (error: unknown, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+    /**
+     * Optional: Request middleware.
+     * Transform or enrich the request before validation.
+     *
+     * @param req - The incoming request
+     * @returns Transformed request
+     */
+    beforeValidation?: (req: WebhookRequest<TBody>) => WebhookRequest<TBody> | Promise<WebhookRequest<TBody>>;
+    /**
+     * Optional: Response middleware.
+     * Transform the response before sending.
+     *
+     * @param response - The response to send
+     * @param req - The original request
+     * @returns Transformed response
+     */
+    afterResponse?: (response: WebhookResponse, req: WebhookRequest<TBody>) => WebhookResponse | Promise<WebhookResponse>;
+}
+/**
+ * A webhook handler function that processes requests.
+ */
+type WebhookHandler<TBody = unknown> = (req: WebhookRequest<TBody>) => Promise<WebhookResponse>;
+/**
+ * Default validation error mapper.
+ * Returns 400 Bad Request with error details.
+ */
+declare function defaultValidationErrorMapper(error: ValidationError): WebhookResponse<ErrorResponseBody>;
+/**
+ * Default unexpected error mapper.
+ * Returns 500 Internal Server Error.
+ */
+declare function defaultUnexpectedErrorMapper(error: unknown): WebhookResponse<ErrorResponseBody>;
+/**
+ * Create a webhook handler for a workflow.
+ *
+ * This factory creates an HTTP handler function that:
+ * 1. Validates the incoming request
+ * 2. Executes the workflow with the validated input
+ * 3. Maps the result to an HTTP response
+ *
+ * The handler is framework-agnostic and returns a standard response object.
+ * Use framework adapters (createExpressHandler, createHonoHandler, etc.) to
+ * integrate with specific frameworks.
+ *
+ * @template TInput - The validated input type passed to the workflow
+ * @template TOutput - The workflow output type
+ * @template TError - The workflow error type
+ * @template TBody - The raw request body type
+ * @template TDeps - The workflow dependencies type
+ *
+ * @param workflow - The workflow function to execute
+ * @param workflowFn - The workflow body function ({ step, deps, args }) => output
+ * @param config - Handler configuration
+ * @returns A webhook handler function
+ *
+ * @example
+ * ```typescript
+ * const checkoutWorkflow = createWorkflow('checkout', { chargeCard, sendEmail });
+ *
+ * const handler = createWebhookHandler(
+ *   checkoutWorkflow,
+ *   async ({ step, deps, args: input }) => {
+ *     const charge = await step('chargeCard', () => deps.chargeCard(input.amount));
+ *     await step('sendEmail', () => deps.sendEmail(input.email, charge.receiptUrl));
+ *     return { chargeId: charge.id };
+ *   },
+ *   {
+ *     validateInput: (req) => {
+ *       const { amount, email } = req.body;
+ *       if (!amount || !email) {
+ *         return err({ type: 'VALIDATION_ERROR', message: 'Missing required fields' });
+ *       }
+ *       return ok({ amount, email });
+ *     },
+ *     mapResult: (result) => {
+ *       if (result.ok) {
+ *         return { status: 200, body: result.value };
+ *       }
+ *       if (result.error === 'CARD_DECLINED') {
+ *         return { status: 402, body: { error: { type: 'CARD_DECLINED' } } };
+ *       }
+ *       return { status: 500, body: { error: { type: 'UNKNOWN' } } };
+ *     },
+ *   }
+ * );
+ *
+ * // Use with Express
+ * app.post('/checkout', async (req, res) => {
+ *   const response = await handler(toWebhookRequest(req));
+ *   res.status(response.status).json(response.body);
+ * });
+ * ```
+ */
+declare function createWebhookHandler<TInput, TOutput, TError, TUnexpected, TBody = unknown, TDeps = unknown>(workflow: Workflow<TError, TUnexpected, TDeps>, workflowFn: (context: {
+    step: RunStep<TError | TUnexpected>;
+    deps: TDeps;
+    args: TInput;
+}) => TOutput | Promise<TOutput>, config: WebhookHandlerConfig<TInput, TOutput, TError, TBody, TUnexpected>): WebhookHandler<TBody>;
+declare function createWebhookHandler<TInput, TOutput, TError, TBody = unknown, TDeps = unknown>(workflow: Workflow<TError, UnexpectedError, TDeps>, workflowFn: (context: {
+    step: RunStep<TError | UnexpectedError>;
+    deps: TDeps;
+    args: TInput;
+}) => TOutput | Promise<TOutput>, config: WebhookHandlerConfig<TInput, TOutput, TError, TBody, UnexpectedError>): WebhookHandler<TBody>;
+/**
+ * Configuration for a simple webhook handler without workflow.
+ * Use with createSimpleHandler for endpoints that don't need step orchestration.
+ *
+ * @template TInput - Validated input type
+ * @template TOutput - Handler success output type
+ * @template TError - Handler error type
+ * @template TBody - Raw request body type
+ */
+interface SimpleHandlerConfig<TInput, TOutput, TError, TBody = unknown> {
+    /** Validate and transform the incoming request; return ok(input) or err(ValidationError). */
+    validateInput: (req: WebhookRequest<TBody>) => ValidationResult<TInput, ValidationError> | Promise<ValidationResult<TInput, ValidationError>>;
+    /** Execute the business logic; return Result. */
+    handler: (input: TInput, req: WebhookRequest<TBody>) => AsyncResult<TOutput, TError>;
+    /** Map the handler result to an HTTP response. */
+    mapResult: (result: Result<TOutput, TError>, req: WebhookRequest<TBody>) => WebhookResponse;
+    /** Optional: map validation errors to response. Defaults to 400 with error details. */
+    mapValidationError?: (error: ValidationError, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+    /** Optional: handle unexpected errors. Defaults to 500. */
+    mapUnexpectedError?: (error: unknown, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+}
+/**
+ * Create a simple webhook handler without workflow orchestration.
+ * Useful for simple endpoints that don't need step-based error handling.
+ *
+ * @example
+ * ```typescript
+ * const handler = createSimpleHandler({
+ *   validateInput: (req) => {
+ *     const { id } = req.params;
+ *     if (!id) return err({ type: 'VALIDATION_ERROR', message: 'Missing id' });
+ *     return ok({ id });
+ *   },
+ *   handler: async ({ id }) => {
+ *     const user = await db.findUser(id);
+ *     return user ? ok(user) : err('NOT_FOUND' as const);
+ *   },
+ *   mapResult: (result) => {
+ *     if (result.ok) return { status: 200, body: result.value };
+ *     return { status: 404, body: { error: { type: 'NOT_FOUND' } } };
+ *   },
+ * });
+ * ```
+ */
+declare function createSimpleHandler<TInput, TOutput, TError, TBody = unknown>(config: SimpleHandlerConfig<TInput, TOutput, TError, TBody>): WebhookHandler<TBody>;
+/**
+ * Standard error mapping configuration.
+ */
+interface ErrorMapping<TError> {
+    /** The error value to match */
+    error: TError;
+    /** HTTP status code for this error */
+    status: number;
+    /** Optional custom message */
+    message?: string;
+}
+/**
+ * Create a result mapper from error mappings.
+ * Provides a declarative way to map workflow errors to HTTP responses.
+ *
+ * @param mappings - Array of error mappings
+ * @param defaultStatus - Default status for unmapped errors (default: 500)
+ * @returns A mapResult function for use in handler config
+ *
+ * @example
+ * ```typescript
+ * const mapResult = createResultMapper<CheckoutOutput, CheckoutError>([
+ *   { error: 'NOT_FOUND', status: 404, message: 'Resource not found' },
+ *   { error: 'CARD_DECLINED', status: 402, message: 'Payment failed' },
+ *   { error: 'RATE_LIMITED', status: 429, message: 'Too many requests' },
+ * ]);
+ *
+ * const handler = createWebhookHandler(workflow, workflowFn, {
+ *   validateInput,
+ *   mapResult,
+ * });
+ * ```
+ */
+declare function createResultMapper<TOutput, TError>(mappings: ErrorMapping<TError>[], options?: {
+    defaultStatus?: number;
+    successStatus?: number;
+}): (result: Result<TOutput, TError | UnexpectedError>) => WebhookResponse;
+/**
+ * Express-style request object (minimal interface).
+ */
+interface ExpressLikeRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    body: unknown;
+    query: Record<string, string | string[] | undefined>;
+    params: Record<string, string>;
+}
+/**
+ * Express-style response object (minimal interface).
+ */
+interface ExpressLikeResponse {
+    status(code: number): ExpressLikeResponse;
+    set(headers: Record<string, string>): ExpressLikeResponse;
+    json(body: unknown): void;
+}
+/**
+ * Convert an Express-like request to WebhookRequest.
+ *
+ * @param req - Express-like request object
+ * @returns WebhookRequest
+ *
+ * @example
+ * ```typescript
+ * app.post('/checkout', async (req, res) => {
+ *   const webhookReq = toWebhookRequest(req);
+ *   const response = await handler(webhookReq);
+ *   res.status(response.status).json(response.body);
+ * });
+ * ```
+ */
+declare function toWebhookRequest<TBody = unknown>(req: ExpressLikeRequest): WebhookRequest<TBody>;
+/**
+ * Send a WebhookResponse using an Express-like response object.
+ *
+ * @param res - Express-like response object
+ * @param response - WebhookResponse to send
+ *
+ * @example
+ * ```typescript
+ * app.post('/checkout', async (req, res) => {
+ *   const response = await handler(toWebhookRequest(req));
+ *   sendWebhookResponse(res, response);
+ * });
+ * ```
+ */
+declare function sendWebhookResponse(res: ExpressLikeResponse, response: WebhookResponse): void;
+/**
+ * Create an Express-compatible middleware from a webhook handler.
+ *
+ * @param handler - Webhook handler function
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const handler = createWebhookHandler(workflow, workflowFn, config);
+ * const middleware = createExpressHandler(handler);
+ * app.post('/checkout', middleware);
+ * ```
+ */
+declare function createExpressHandler<TBody = unknown>(handler: WebhookHandler<TBody>): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<void>;
+/**
+ * Create a validation error.
+ *
+ * @param message - Error message
+ * @param field - Optional field name
+ * @param details - Optional additional details
+ * @returns ValidationError
+ */
+declare function validationError(message: string, field?: string, details?: unknown): ValidationError;
+/**
+ * Create a required field validator.
+ *
+ * @param fields - Field names to validate
+ * @returns Validation function
+ *
+ * @example
+ * ```typescript
+ * const validateRequired = requireFields(['email', 'password']);
+ *
+ * const validateInput = (req) => {
+ *   const result = validateRequired(req.body);
+ *   if (!result.ok) return result;
+ *   return ok(req.body as LoginInput);
+ * };
+ * ```
+ */
+declare function requireFields(fields: string[]): (body: Record<string, unknown>) => ValidationResult<void, ValidationError>;
+/**
+ * Compose multiple validators into a single validator.
+ *
+ * @param validators - Validators to compose
+ * @returns Combined validator function
+ *
+ * @example
+ * ```typescript
+ * const validate = composeValidators(
+ *   requireFields(['email', 'password']),
+ *   validateEmailFormat,
+ *   validatePasswordStrength
+ * );
+ * ```
+ */
+declare function composeValidators<T>(...validators: Array<(input: T) => ValidationResult<void, ValidationError>>): (input: T) => ValidationResult<void, ValidationError>;
+/**
+ * Generic event message for queue-based triggers.
+ */
+interface EventMessage<T = unknown> {
+    /** Unique message ID */
+    id: string;
+    /** Event type/name */
+    type: string;
+    /** Event payload */
+    payload: T;
+    /** Event metadata */
+    metadata?: {
+        timestamp?: number;
+        source?: string;
+        correlationId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Result of processing an event.
+ */
+interface EventProcessingResult {
+    /** Whether the event was processed successfully */
+    success: boolean;
+    /** Should the message be acknowledged (removed from queue)? */
+    ack: boolean;
+    /** Optional error details */
+    error?: {
+        type: string;
+        message?: string;
+        retryable?: boolean;
+    };
+}
+/**
+ * Configuration for event trigger handlers.
+ */
+interface EventTriggerConfig<TPayload, TOutput, TError, TUnexpected = UnexpectedError> {
+    /** Validate the event payload */
+    validatePayload: (event: EventMessage<TPayload>) => ValidationResult<TPayload, ValidationError>;
+    /** Map workflow result to processing result */
+    mapResult: (result: Result<TOutput, TError | TUnexpected>, event: EventMessage<TPayload>) => EventProcessingResult;
+    /** Optional: Determine if error is retryable */
+    isRetryable?: (error: TError | TUnexpected) => boolean;
+}
+/**
+ * Event handler function type.
+ */
+type EventHandler<TPayload = unknown> = (event: EventMessage<TPayload>) => Promise<EventProcessingResult>;
+/**
+ * Create an event handler for queue-based triggers.
+ *
+ * @example
+ * ```typescript
+ * const handler = createEventHandler(
+ *   checkoutWorkflow,
+ *   async ({ step, deps, args: payload }) => {
+ *     const charge = await step('chargeCard', () => deps.chargeCard(payload.amount));
+ *     return { chargeId: charge.id };
+ *   },
+ *   {
+ *     validatePayload: (event) => {
+ *       if (!event.payload.amount) {
+ *         return err({ type: 'VALIDATION_ERROR', message: 'Missing amount' });
+ *       }
+ *       return ok(event.payload);
+ *     },
+ *     mapResult: (result) => ({
+ *       success: result.ok,
+ *       ack: result.ok || !isRetryableError(result.error),
+ *       error: result.ok ? undefined : { type: String(result.error) },
+ *     }),
+ *   }
+ * );
+ *
+ * // Use with SQS, RabbitMQ, etc.
+ * queue.consume(async (message) => {
+ *   const result = await handler(message);
+ *   if (result.ack) await message.ack();
+ *   else await message.nack();
+ * });
+ * ```
+ */
+declare function createEventHandler<TPayload, TOutput, TError, TDeps = unknown, TUnexpected = UnexpectedError>(workflow: Workflow<TError, TUnexpected, TDeps>, workflowFn: (context: {
+    step: RunStep<TError | TUnexpected>;
+    deps: TDeps;
+    args: TPayload;
+}) => TOutput | Promise<TOutput>, config: EventTriggerConfig<TPayload, TOutput, TError, TUnexpected>): EventHandler<TPayload>;
+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 };