awaitly 1.31.1 → 1.32.0

package/dist/errors-entry-CMH73Eym.d.cts

@@ -0,0 +1,339 @@
+import { TaggedErrorConstructor } from './tagged-error.cjs';
+
+/**
+ * awaitly/errors
+ *
+ * Pre-built error types for common failure scenarios.
+ * Uses TaggedError for type-safe exhaustive matching.
+ *
+ * @example
+ * ```typescript
+ * import { TimeoutError, RetryExhaustedError, RateLimitError, CircuitOpenError } from 'awaitly/errors';
+ *
+ * // Create errors
+ * const timeout = new TimeoutError({ operation: 'fetchUser', ms: 5000 });
+ * const retryFailed = new RetryExhaustedError({ operation: 'sendEmail', attempts: 3 });
+ *
+ * // Pattern match
+ * TaggedError.match(error, {
+ *   TimeoutError: (e) => `${e.operation} timed out after ${e.ms}ms`,
+ *   RetryExhaustedError: (e) => `${e.operation} failed after ${e.attempts} attempts`,
+ *   RateLimitError: (e) => `Rate limit exceeded, retry after ${e.retryAfterMs}ms`,
+ *   CircuitOpenError: (e) => `Circuit ${e.circuitName} is open`,
+ * });
+ * ```
+ */
+/**
+ * Factory function to create tagged error classes with default values.
+ *
+ * This is a convenience wrapper around TaggedError that allows specifying
+ * default property values for error types.
+ *
+ * @example
+ * ```typescript
+ * // Define custom error with defaults
+ * const NetworkError = makeError('NetworkError', {
+ *   defaults: { retryable: true },
+ *   message: (p) => `Network error: ${p.reason}`,
+ * });
+ *
+ * class MyNetworkError extends NetworkError<{ reason: string; code?: number }> {}
+ *
+ * const error = new MyNetworkError({ reason: 'Connection refused' });
+ * // error.retryable === true (from defaults)
+ * ```
+ */
+declare function makeError<Tag extends string>(tag: Tag, options?: {
+    message?: (props: Record<string, unknown>) => string;
+    defaults?: Record<string, unknown>;
+}): {
+    new (props?: Record<string, unknown>): {
+        readonly [x: string]: unknown;
+        readonly _tag: Tag;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare const TimeoutError_base: TaggedErrorConstructor<"TimeoutError", {
+    /** Name of the operation that timed out */
+    operation?: string;
+    /** Timeout duration in milliseconds */
+    ms: number;
+}>;
+/**
+ * Error thrown when an operation times out.
+ *
+ * @example
+ * ```typescript
+ * const error = new TimeoutError({
+ *   operation: 'fetchUser',
+ *   ms: 5000,
+ * });
+ * console.log(error.message); // "TimeoutError: fetchUser timed out after 5000ms"
+ * ```
+ */
+declare class TimeoutError extends TimeoutError_base {
+}
+declare const RetryExhaustedError_base: TaggedErrorConstructor<"RetryExhaustedError", {
+    /** Name of the operation that failed */
+    operation?: string;
+    /** Total number of retry attempts made */
+    attempts: number;
+    /** The last error encountered before giving up */
+    lastError?: unknown;
+}>;
+/**
+ * Error thrown when all retry attempts are exhausted.
+ *
+ * @example
+ * ```typescript
+ * const error = new RetryExhaustedError({
+ *   operation: 'sendEmail',
+ *   attempts: 3,
+ *   lastError: originalError,
+ * });
+ * console.log(error.message); // "RetryExhaustedError: sendEmail failed after 3 attempts"
+ * ```
+ */
+declare class RetryExhaustedError extends RetryExhaustedError_base {
+}
+declare const RateLimitError_base: TaggedErrorConstructor<"RateLimitError", {
+    /** Name of the rate limiter that was exceeded */
+    limiterName?: string;
+    /** Time in milliseconds until the rate limit resets */
+    retryAfterMs?: number;
+}>;
+/**
+ * Error thrown when a rate limit is exceeded.
+ *
+ * @example
+ * ```typescript
+ * const error = new RateLimitError({
+ *   limiterName: 'api-calls',
+ *   retryAfterMs: 1000,
+ * });
+ * console.log(error.message); // "RateLimitError: Rate limit exceeded for api-calls"
+ * ```
+ */
+declare class RateLimitError extends RateLimitError_base {
+}
+declare const CircuitBreakerOpenError_base: TaggedErrorConstructor<"CircuitBreakerOpenError", {
+    /** Name of the circuit breaker */
+    circuitName: string;
+    /** Current state of the circuit */
+    state?: "OPEN" | "HALF_OPEN";
+    /** Time in milliseconds until the circuit may close */
+    retryAfterMs?: number;
+}>;
+/**
+ * Error thrown when a circuit breaker is open.
+ *
+ * @example
+ * ```typescript
+ * const error = new CircuitBreakerOpenError({
+ *   circuitName: 'payment-api',
+ *   state: 'OPEN',
+ *   retryAfterMs: 30000,
+ * });
+ * console.log(error.message); // "CircuitBreakerOpenError: Circuit payment-api is OPEN"
+ * ```
+ */
+declare class CircuitBreakerOpenError extends CircuitBreakerOpenError_base {
+}
+declare const ValidationError_base: TaggedErrorConstructor<"ValidationError", {
+    /** Field that failed validation */
+    field: string;
+    /** Reason for validation failure */
+    reason: string;
+    /** Raw value that failed validation */
+    value?: unknown;
+}>;
+/**
+ * Error thrown when validation fails.
+ *
+ * @example
+ * ```typescript
+ * const error = new ValidationError({
+ *   field: 'email',
+ *   reason: 'Invalid email format',
+ * });
+ * console.log(error.message); // "ValidationError: Invalid email - Invalid email format"
+ * ```
+ */
+declare class ValidationError extends ValidationError_base {
+}
+declare const NotFoundError_base: TaggedErrorConstructor<"NotFoundError", {
+    /** Type of resource that was not found */
+    resource: string;
+    /** Identifier of the missing resource */
+    id?: string;
+}>;
+/**
+ * Error thrown when a resource is not found.
+ *
+ * @example
+ * ```typescript
+ * const error = new NotFoundError({
+ *   resource: 'User',
+ *   id: '123',
+ * });
+ * console.log(error.message); // "NotFoundError: User with id 123 not found"
+ * ```
+ */
+declare class NotFoundError extends NotFoundError_base {
+}
+declare const UnauthorizedError_base: TaggedErrorConstructor<"UnauthorizedError", {
+    /** Action that was attempted */
+    action?: string;
+    /** Resource that was being accessed */
+    resource?: string;
+    /** Reason for denial */
+    reason?: string;
+}>;
+/**
+ * Error thrown when access is denied.
+ *
+ * @example
+ * ```typescript
+ * const error = new UnauthorizedError({
+ *   action: 'delete',
+ *   resource: 'User',
+ * });
+ * console.log(error.message); // "UnauthorizedError: Not authorized to delete User"
+ * ```
+ */
+declare class UnauthorizedError extends UnauthorizedError_base {
+}
+declare const NetworkError_base: TaggedErrorConstructor<"NetworkError", {
+    /** URL that was being accessed */
+    url?: string;
+    /** Reason for the network failure */
+    reason: string;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+}>;
+/**
+ * Error thrown for network-related failures.
+ *
+ * @example
+ * ```typescript
+ * const error = new NetworkError({
+ *   url: 'https://api.example.com/users',
+ *   reason: 'Connection refused',
+ *   retryable: true,
+ * });
+ * ```
+ */
+declare class NetworkError extends NetworkError_base {
+}
+declare const CompensationError_base: TaggedErrorConstructor<"CompensationError", {
+    /** Step that triggered compensation */
+    step: string;
+    /** The original error that caused compensation */
+    originalError?: unknown;
+    /** Error that occurred during compensation */
+    compensationError?: unknown;
+}>;
+/**
+ * Error thrown when a saga compensation fails.
+ *
+ * @example
+ * ```typescript
+ * const error = new CompensationError({
+ *   step: 'chargeCard',
+ *   originalError: paymentError,
+ *   compensationError: refundError,
+ * });
+ * ```
+ */
+declare class CompensationError extends CompensationError_base {
+}
+declare const UnexpectedError_base: TaggedErrorConstructor<"UnexpectedError", {
+    /** The original thrown value or cancellation error */
+    cause?: unknown;
+}>;
+/**
+ * Default error type for uncaught exceptions and cancellation in workflows.
+ * This is the default `U` type when `catchUnexpected` is not provided.
+ *
+ * @example
+ * ```typescript
+ * // Automatically used as the default — no need to pass catchUnexpected:
+ * const workflow = createWorkflow("checkout", { chargeCard, sendEmail });
+ *
+ * // Equivalent to:
+ * const workflow = createWorkflow("checkout", { chargeCard, sendEmail }, {
+ *   catchUnexpected: (cause) => new UnexpectedError({ cause }),
+ * });
+ * ```
+ */
+declare class UnexpectedError extends UnexpectedError_base {
+}
+/**
+ * Union of all pre-built error types.
+ * Useful for exhaustive pattern matching.
+ *
+ * @example
+ * ```typescript
+ * function handleError(error: AwaitlyError): string {
+ *   return TaggedError.match(error, {
+ *     TimeoutError: (e) => `Timeout: ${e.ms}ms`,
+ *     RetryExhaustedError: (e) => `Retries: ${e.attempts}`,
+ *     RateLimitError: (e) => `Rate limited`,
+ *     CircuitBreakerOpenError: (e) => `Circuit open: ${e.circuitName}`,
+ *     ValidationError: (e) => `Invalid: ${e.field}`,
+ *     NotFoundError: (e) => `Not found: ${e.resource}`,
+ *     UnauthorizedError: (e) => `Unauthorized`,
+ *     NetworkError: (e) => `Network: ${e.reason}`,
+ *     CompensationError: (e) => `Compensation failed: ${e.step}`,
+ *   });
+ * }
+ * ```
+ */
+type AwaitlyError = TimeoutError | RetryExhaustedError | RateLimitError | CircuitBreakerOpenError | ValidationError | NotFoundError | UnauthorizedError | NetworkError | CompensationError;
+/**
+ * Check if an error is a TimeoutError.
+ */
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+/**
+ * Check if an error is a RetryExhaustedError.
+ */
+declare function isRetryExhaustedError(error: unknown): error is RetryExhaustedError;
+/**
+ * Check if an error is a RateLimitError.
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Check if an error is a CircuitBreakerOpenError.
+ */
+declare function isCircuitBreakerOpenError(error: unknown): error is CircuitBreakerOpenError;
+/**
+ * Check if an error is a ValidationError.
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Check if an error is a NotFoundError.
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Check if an error is an UnauthorizedError.
+ */
+declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+/**
+ * Check if an error is a NetworkError.
+ */
+declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Check if an error is a CompensationError.
+ */
+declare function isCompensationError(error: unknown): error is CompensationError;
+/**
+ * Check if an error is any AwaitlyError.
+ */
+declare function isAwaitlyError(error: unknown): error is AwaitlyError;
+
+export { type AwaitlyError as A, CircuitBreakerOpenError as C, NetworkError as N, RateLimitError as R, TimeoutError as T, UnexpectedError as U, ValidationError as V, CompensationError as a, NotFoundError as b, RetryExhaustedError as c, UnauthorizedError as d, isCircuitBreakerOpenError as e, isCompensationError as f, isNetworkError as g, isNotFoundError as h, isAwaitlyError as i, isRateLimitError as j, isRetryExhaustedError as k, isTimeoutError as l, isUnauthorizedError as m, isValidationError as n, makeError as o };

package/dist/errors-entry-DOt5UUl4.d.ts

@@ -0,0 +1,339 @@
+import { TaggedErrorConstructor } from './tagged-error.js';
+
+/**
+ * awaitly/errors
+ *
+ * Pre-built error types for common failure scenarios.
+ * Uses TaggedError for type-safe exhaustive matching.
+ *
+ * @example
+ * ```typescript
+ * import { TimeoutError, RetryExhaustedError, RateLimitError, CircuitOpenError } from 'awaitly/errors';
+ *
+ * // Create errors
+ * const timeout = new TimeoutError({ operation: 'fetchUser', ms: 5000 });
+ * const retryFailed = new RetryExhaustedError({ operation: 'sendEmail', attempts: 3 });
+ *
+ * // Pattern match
+ * TaggedError.match(error, {
+ *   TimeoutError: (e) => `${e.operation} timed out after ${e.ms}ms`,
+ *   RetryExhaustedError: (e) => `${e.operation} failed after ${e.attempts} attempts`,
+ *   RateLimitError: (e) => `Rate limit exceeded, retry after ${e.retryAfterMs}ms`,
+ *   CircuitOpenError: (e) => `Circuit ${e.circuitName} is open`,
+ * });
+ * ```
+ */
+/**
+ * Factory function to create tagged error classes with default values.
+ *
+ * This is a convenience wrapper around TaggedError that allows specifying
+ * default property values for error types.
+ *
+ * @example
+ * ```typescript
+ * // Define custom error with defaults
+ * const NetworkError = makeError('NetworkError', {
+ *   defaults: { retryable: true },
+ *   message: (p) => `Network error: ${p.reason}`,
+ * });
+ *
+ * class MyNetworkError extends NetworkError<{ reason: string; code?: number }> {}
+ *
+ * const error = new MyNetworkError({ reason: 'Connection refused' });
+ * // error.retryable === true (from defaults)
+ * ```
+ */
+declare function makeError<Tag extends string>(tag: Tag, options?: {
+    message?: (props: Record<string, unknown>) => string;
+    defaults?: Record<string, unknown>;
+}): {
+    new (props?: Record<string, unknown>): {
+        readonly [x: string]: unknown;
+        readonly _tag: Tag;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare const TimeoutError_base: TaggedErrorConstructor<"TimeoutError", {
+    /** Name of the operation that timed out */
+    operation?: string;
+    /** Timeout duration in milliseconds */
+    ms: number;
+}>;
+/**
+ * Error thrown when an operation times out.
+ *
+ * @example
+ * ```typescript
+ * const error = new TimeoutError({
+ *   operation: 'fetchUser',
+ *   ms: 5000,
+ * });
+ * console.log(error.message); // "TimeoutError: fetchUser timed out after 5000ms"
+ * ```
+ */
+declare class TimeoutError extends TimeoutError_base {
+}
+declare const RetryExhaustedError_base: TaggedErrorConstructor<"RetryExhaustedError", {
+    /** Name of the operation that failed */
+    operation?: string;
+    /** Total number of retry attempts made */
+    attempts: number;
+    /** The last error encountered before giving up */
+    lastError?: unknown;
+}>;
+/**
+ * Error thrown when all retry attempts are exhausted.
+ *
+ * @example
+ * ```typescript
+ * const error = new RetryExhaustedError({
+ *   operation: 'sendEmail',
+ *   attempts: 3,
+ *   lastError: originalError,
+ * });
+ * console.log(error.message); // "RetryExhaustedError: sendEmail failed after 3 attempts"
+ * ```
+ */
+declare class RetryExhaustedError extends RetryExhaustedError_base {
+}
+declare const RateLimitError_base: TaggedErrorConstructor<"RateLimitError", {
+    /** Name of the rate limiter that was exceeded */
+    limiterName?: string;
+    /** Time in milliseconds until the rate limit resets */
+    retryAfterMs?: number;
+}>;
+/**
+ * Error thrown when a rate limit is exceeded.
+ *
+ * @example
+ * ```typescript
+ * const error = new RateLimitError({
+ *   limiterName: 'api-calls',
+ *   retryAfterMs: 1000,
+ * });
+ * console.log(error.message); // "RateLimitError: Rate limit exceeded for api-calls"
+ * ```
+ */
+declare class RateLimitError extends RateLimitError_base {
+}
+declare const CircuitBreakerOpenError_base: TaggedErrorConstructor<"CircuitBreakerOpenError", {
+    /** Name of the circuit breaker */
+    circuitName: string;
+    /** Current state of the circuit */
+    state?: "OPEN" | "HALF_OPEN";
+    /** Time in milliseconds until the circuit may close */
+    retryAfterMs?: number;
+}>;
+/**
+ * Error thrown when a circuit breaker is open.
+ *
+ * @example
+ * ```typescript
+ * const error = new CircuitBreakerOpenError({
+ *   circuitName: 'payment-api',
+ *   state: 'OPEN',
+ *   retryAfterMs: 30000,
+ * });
+ * console.log(error.message); // "CircuitBreakerOpenError: Circuit payment-api is OPEN"
+ * ```
+ */
+declare class CircuitBreakerOpenError extends CircuitBreakerOpenError_base {
+}
+declare const ValidationError_base: TaggedErrorConstructor<"ValidationError", {
+    /** Field that failed validation */
+    field: string;
+    /** Reason for validation failure */
+    reason: string;
+    /** Raw value that failed validation */
+    value?: unknown;
+}>;
+/**
+ * Error thrown when validation fails.
+ *
+ * @example
+ * ```typescript
+ * const error = new ValidationError({
+ *   field: 'email',
+ *   reason: 'Invalid email format',
+ * });
+ * console.log(error.message); // "ValidationError: Invalid email - Invalid email format"
+ * ```
+ */
+declare class ValidationError extends ValidationError_base {
+}
+declare const NotFoundError_base: TaggedErrorConstructor<"NotFoundError", {
+    /** Type of resource that was not found */
+    resource: string;
+    /** Identifier of the missing resource */
+    id?: string;
+}>;
+/**
+ * Error thrown when a resource is not found.
+ *
+ * @example
+ * ```typescript
+ * const error = new NotFoundError({
+ *   resource: 'User',
+ *   id: '123',
+ * });
+ * console.log(error.message); // "NotFoundError: User with id 123 not found"
+ * ```
+ */
+declare class NotFoundError extends NotFoundError_base {
+}
+declare const UnauthorizedError_base: TaggedErrorConstructor<"UnauthorizedError", {
+    /** Action that was attempted */
+    action?: string;
+    /** Resource that was being accessed */
+    resource?: string;
+    /** Reason for denial */
+    reason?: string;
+}>;
+/**
+ * Error thrown when access is denied.
+ *
+ * @example
+ * ```typescript
+ * const error = new UnauthorizedError({
+ *   action: 'delete',
+ *   resource: 'User',
+ * });
+ * console.log(error.message); // "UnauthorizedError: Not authorized to delete User"
+ * ```
+ */
+declare class UnauthorizedError extends UnauthorizedError_base {
+}
+declare const NetworkError_base: TaggedErrorConstructor<"NetworkError", {
+    /** URL that was being accessed */
+    url?: string;
+    /** Reason for the network failure */
+    reason: string;
+    /** Whether this error is retryable */
+    retryable?: boolean;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+}>;
+/**
+ * Error thrown for network-related failures.
+ *
+ * @example
+ * ```typescript
+ * const error = new NetworkError({
+ *   url: 'https://api.example.com/users',
+ *   reason: 'Connection refused',
+ *   retryable: true,
+ * });
+ * ```
+ */
+declare class NetworkError extends NetworkError_base {
+}
+declare const CompensationError_base: TaggedErrorConstructor<"CompensationError", {
+    /** Step that triggered compensation */
+    step: string;
+    /** The original error that caused compensation */
+    originalError?: unknown;
+    /** Error that occurred during compensation */
+    compensationError?: unknown;
+}>;
+/**
+ * Error thrown when a saga compensation fails.
+ *
+ * @example
+ * ```typescript
+ * const error = new CompensationError({
+ *   step: 'chargeCard',
+ *   originalError: paymentError,
+ *   compensationError: refundError,
+ * });
+ * ```
+ */
+declare class CompensationError extends CompensationError_base {
+}
+declare const UnexpectedError_base: TaggedErrorConstructor<"UnexpectedError", {
+    /** The original thrown value or cancellation error */
+    cause?: unknown;
+}>;
+/**
+ * Default error type for uncaught exceptions and cancellation in workflows.
+ * This is the default `U` type when `catchUnexpected` is not provided.
+ *
+ * @example
+ * ```typescript
+ * // Automatically used as the default — no need to pass catchUnexpected:
+ * const workflow = createWorkflow("checkout", { chargeCard, sendEmail });
+ *
+ * // Equivalent to:
+ * const workflow = createWorkflow("checkout", { chargeCard, sendEmail }, {
+ *   catchUnexpected: (cause) => new UnexpectedError({ cause }),
+ * });
+ * ```
+ */
+declare class UnexpectedError extends UnexpectedError_base {
+}
+/**
+ * Union of all pre-built error types.
+ * Useful for exhaustive pattern matching.
+ *
+ * @example
+ * ```typescript
+ * function handleError(error: AwaitlyError): string {
+ *   return TaggedError.match(error, {
+ *     TimeoutError: (e) => `Timeout: ${e.ms}ms`,
+ *     RetryExhaustedError: (e) => `Retries: ${e.attempts}`,
+ *     RateLimitError: (e) => `Rate limited`,
+ *     CircuitBreakerOpenError: (e) => `Circuit open: ${e.circuitName}`,
+ *     ValidationError: (e) => `Invalid: ${e.field}`,
+ *     NotFoundError: (e) => `Not found: ${e.resource}`,
+ *     UnauthorizedError: (e) => `Unauthorized`,
+ *     NetworkError: (e) => `Network: ${e.reason}`,
+ *     CompensationError: (e) => `Compensation failed: ${e.step}`,
+ *   });
+ * }
+ * ```
+ */
+type AwaitlyError = TimeoutError | RetryExhaustedError | RateLimitError | CircuitBreakerOpenError | ValidationError | NotFoundError | UnauthorizedError | NetworkError | CompensationError;
+/**
+ * Check if an error is a TimeoutError.
+ */
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+/**
+ * Check if an error is a RetryExhaustedError.
+ */
+declare function isRetryExhaustedError(error: unknown): error is RetryExhaustedError;
+/**
+ * Check if an error is a RateLimitError.
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Check if an error is a CircuitBreakerOpenError.
+ */
+declare function isCircuitBreakerOpenError(error: unknown): error is CircuitBreakerOpenError;
+/**
+ * Check if an error is a ValidationError.
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Check if an error is a NotFoundError.
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Check if an error is an UnauthorizedError.
+ */
+declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+/**
+ * Check if an error is a NetworkError.
+ */
+declare function isNetworkError(error: unknown): error is NetworkError;
+/**
+ * Check if an error is a CompensationError.
+ */
+declare function isCompensationError(error: unknown): error is CompensationError;
+/**
+ * Check if an error is any AwaitlyError.
+ */
+declare function isAwaitlyError(error: unknown): error is AwaitlyError;
+
+export { type AwaitlyError as A, CircuitBreakerOpenError as C, NetworkError as N, RateLimitError as R, TimeoutError as T, UnexpectedError as U, ValidationError as V, CompensationError as a, NotFoundError as b, RetryExhaustedError as c, UnauthorizedError as d, isCircuitBreakerOpenError as e, isCompensationError as f, isNetworkError as g, isNotFoundError as h, isAwaitlyError as i, isRateLimitError as j, isRetryExhaustedError as k, isTimeoutError as l, isUnauthorizedError as m, isValidationError as n, makeError as o };