awaitly 2.0.0 → 3.0.0

package/dist/saga.d.cts

@@ -0,0 +1,162 @@
+import { R as Result, A as AsyncResult } from './index-ICmfQi08.cjs';
+import { W as Workflow, c as AnyResultFn, f as WorkflowOptions, E as ErrorsOfDeps } from './types-C9Y71dua.cjs';
+import { U as UnexpectedError } from './errors-sDSeaZBO.cjs';
+import './types-d8q8iQlk.cjs';
+import '@standard-schema/spec';
+
+/**
+ * Saga / Compensation Pattern
+ *
+ * Compensation is a first-class step option on every workflow. Pass `{ compensate }`
+ * to any step and the workflow will run compensations in reverse order if anything
+ * downstream fails.
+ *
+ * `createSagaWorkflow` is a thin alias for `createWorkflow` whose result error union
+ * also includes `SagaCompensationError` — useful when you know you'll be using
+ * compensation and want the type system to remind you.
+ *
+ * @example
+ * ```typescript
+ * import { createSagaWorkflow, isSagaCompensationError } from 'awaitly/saga';
+ *
+ * const checkout = createSagaWorkflow('checkout', {
+ *   reserveInventory, releaseInventory,
+ *   chargeCard, refundPayment,
+ *   sendEmail,
+ * });
+ *
+ * const result = await checkout.run(async ({ step, deps }) => {
+ *   const r = await step('reserve', () => deps.reserveInventory(items), {
+ *     compensate: (r) => deps.releaseInventory(r.id),
+ *   });
+ *   const p = await step('charge', () => deps.chargeCard(amount), {
+ *     compensate: (p) => deps.refundPayment(p.id),
+ *   });
+ *   await step('notify', () => deps.sendEmail(userId));
+ *   return { r, p };
+ * });
+ *
+ * if (!result.ok && isSagaCompensationError(result.error)) {
+ *   // result.error.originalError    — what triggered the rollback
+ *   // result.error.compensationErrors — which cleanups failed
+ * }
+ * ```
+ */
+
+/** A compensation action to run on rollback. */
+type CompensationAction<T> = (value: T) => void | Promise<void>;
+/** Options for a saga step (kept for back-compat — `compensate` lives on `StepOptions`). */
+interface SagaStepOptions<T> {
+    compensate?: CompensationAction<T>;
+}
+/**
+ * @deprecated Use `WorkflowOptions` from `awaitly/workflow`. Kept as an alias for back-compat.
+ */
+type SagaWorkflowOptions<E> = {
+    onError?: (error: E | UnexpectedError | SagaCompensationError, stepName?: string) => void;
+    onEvent?: (event: unknown) => void;
+    throwOnCompensationFailure?: boolean;
+};
+/** Error returned when one or more compensation actions fail. */
+interface SagaCompensationError {
+    type: "SAGA_COMPENSATION_ERROR";
+    /** The original error that triggered the rollback. */
+    originalError: unknown;
+    /** Errors from failed compensation actions. */
+    compensationErrors: Array<{
+        stepName?: string;
+        error: unknown;
+    }>;
+}
+/** Type guard for SagaCompensationError. */
+declare function isSagaCompensationError(error: unknown): error is SagaCompensationError;
+/**
+ * A `Workflow` whose result error union includes `SagaCompensationError`.
+ * Identical to `Workflow` at runtime — only the static type is widened.
+ */
+type SagaWorkflow<E, U = UnexpectedError, Deps = unknown, C = void> = Workflow<E | SagaCompensationError, U, Deps, C>;
+/**
+ * Create a workflow that uses compensation. Identical to `createWorkflow` —
+ * only the result type is widened to include `SagaCompensationError`.
+ *
+ * Prefer this when you intend to use `step(..., { compensate })` so the type
+ * system reminds you to handle the SAGA_COMPENSATION_ERROR case.
+ *
+ * @example
+ * ```typescript
+ * const saga = createSagaWorkflow('checkout', { reserve, release, charge, refund });
+ *
+ * const result = await saga.run(async ({ step, deps }) => {
+ *   const r = await step('reserve', () => deps.reserve(...), {
+ *     compensate: (r) => deps.release(r.id),
+ *   });
+ *   await step('charge', () => deps.charge(...), {
+ *     compensate: (p) => deps.refund(p.id),
+ *   });
+ *   return r;
+ * });
+ * ```
+ */
+declare function createSagaWorkflow<const Deps extends Readonly<Record<string, AnyResultFn>>, U = UnexpectedError, C = void>(workflowName: string, deps: Deps, options?: WorkflowOptions<ErrorsOfDeps<Deps>, U, C>): SagaWorkflow<ErrorsOfDeps<Deps>, U, Deps, C>;
+/** Saga events emitted by `runSaga` for observability. */
+type SagaEvent = {
+    type: "saga_start";
+    sagaId: string;
+    ts: number;
+} | {
+    type: "saga_success";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+} | {
+    type: "saga_error";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+    error: unknown;
+} | {
+    type: "saga_compensation_start";
+    sagaId: string;
+    ts: number;
+    stepCount: number;
+} | {
+    type: "saga_compensation_step";
+    sagaId: string;
+    stepName?: string;
+    ts: number;
+    success: boolean;
+    error?: unknown;
+} | {
+    type: "saga_compensation_end";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+    success: boolean;
+    failedCount: number;
+};
+type SagaResult<T, E> = Result<T, E | UnexpectedError | SagaCompensationError, unknown>;
+/** Saga step function — like RunStep but every step takes an optional compensate. */
+interface SagaStep<E = unknown> {
+    <T, StepE extends E, StepC = unknown>(name: string, operation: () => Result<T, StepE, StepC> | AsyncResult<T, StepE, StepC>, options?: SagaStepOptions<T>): Promise<T>;
+    try: <T, Err extends E>(name: string, operation: () => T | Promise<T>, options: {
+        error: Err;
+        compensate?: CompensationAction<T>;
+    } | {
+        onError: (cause: unknown) => Err;
+        compensate?: CompensationAction<T>;
+    }) => Promise<T>;
+}
+/**
+ * Run a saga with explicit error typing — for cases where you don't have a
+ * deps object to infer errors from. Most users should reach for
+ * `createSagaWorkflow` (or just `createWorkflow` with `step({ compensate })`).
+ */
+declare function runSaga<T, E>(fn: (context: {
+    step: SagaStep<E>;
+}) => Promise<T>, options?: {
+    onError?: (error: E | UnexpectedError | SagaCompensationError) => void;
+    onEvent?: (event: SagaEvent) => void;
+    throwOnCompensationFailure?: boolean;
+}): Promise<SagaResult<T, E>>;
+
+export { type CompensationAction, type SagaCompensationError, type SagaEvent, type SagaResult, type SagaStep, type SagaStepOptions, type SagaWorkflow, type SagaWorkflowOptions, createSagaWorkflow, isSagaCompensationError, runSaga };

package/dist/saga.d.ts

@@ -0,0 +1,162 @@
+import { R as Result, A as AsyncResult } from './index-Cv4K_3sZ.js';
+import { W as Workflow, c as AnyResultFn, f as WorkflowOptions, E as ErrorsOfDeps } from './types-BDTxgKKc.js';
+import { U as UnexpectedError } from './errors-sDSeaZBO.js';
+import './types-sObbY4mX.js';
+import '@standard-schema/spec';
+
+/**
+ * Saga / Compensation Pattern
+ *
+ * Compensation is a first-class step option on every workflow. Pass `{ compensate }`
+ * to any step and the workflow will run compensations in reverse order if anything
+ * downstream fails.
+ *
+ * `createSagaWorkflow` is a thin alias for `createWorkflow` whose result error union
+ * also includes `SagaCompensationError` — useful when you know you'll be using
+ * compensation and want the type system to remind you.
+ *
+ * @example
+ * ```typescript
+ * import { createSagaWorkflow, isSagaCompensationError } from 'awaitly/saga';
+ *
+ * const checkout = createSagaWorkflow('checkout', {
+ *   reserveInventory, releaseInventory,
+ *   chargeCard, refundPayment,
+ *   sendEmail,
+ * });
+ *
+ * const result = await checkout.run(async ({ step, deps }) => {
+ *   const r = await step('reserve', () => deps.reserveInventory(items), {
+ *     compensate: (r) => deps.releaseInventory(r.id),
+ *   });
+ *   const p = await step('charge', () => deps.chargeCard(amount), {
+ *     compensate: (p) => deps.refundPayment(p.id),
+ *   });
+ *   await step('notify', () => deps.sendEmail(userId));
+ *   return { r, p };
+ * });
+ *
+ * if (!result.ok && isSagaCompensationError(result.error)) {
+ *   // result.error.originalError    — what triggered the rollback
+ *   // result.error.compensationErrors — which cleanups failed
+ * }
+ * ```
+ */
+
+/** A compensation action to run on rollback. */
+type CompensationAction<T> = (value: T) => void | Promise<void>;
+/** Options for a saga step (kept for back-compat — `compensate` lives on `StepOptions`). */
+interface SagaStepOptions<T> {
+    compensate?: CompensationAction<T>;
+}
+/**
+ * @deprecated Use `WorkflowOptions` from `awaitly/workflow`. Kept as an alias for back-compat.
+ */
+type SagaWorkflowOptions<E> = {
+    onError?: (error: E | UnexpectedError | SagaCompensationError, stepName?: string) => void;
+    onEvent?: (event: unknown) => void;
+    throwOnCompensationFailure?: boolean;
+};
+/** Error returned when one or more compensation actions fail. */
+interface SagaCompensationError {
+    type: "SAGA_COMPENSATION_ERROR";
+    /** The original error that triggered the rollback. */
+    originalError: unknown;
+    /** Errors from failed compensation actions. */
+    compensationErrors: Array<{
+        stepName?: string;
+        error: unknown;
+    }>;
+}
+/** Type guard for SagaCompensationError. */
+declare function isSagaCompensationError(error: unknown): error is SagaCompensationError;
+/**
+ * A `Workflow` whose result error union includes `SagaCompensationError`.
+ * Identical to `Workflow` at runtime — only the static type is widened.
+ */
+type SagaWorkflow<E, U = UnexpectedError, Deps = unknown, C = void> = Workflow<E | SagaCompensationError, U, Deps, C>;
+/**
+ * Create a workflow that uses compensation. Identical to `createWorkflow` —
+ * only the result type is widened to include `SagaCompensationError`.
+ *
+ * Prefer this when you intend to use `step(..., { compensate })` so the type
+ * system reminds you to handle the SAGA_COMPENSATION_ERROR case.
+ *
+ * @example
+ * ```typescript
+ * const saga = createSagaWorkflow('checkout', { reserve, release, charge, refund });
+ *
+ * const result = await saga.run(async ({ step, deps }) => {
+ *   const r = await step('reserve', () => deps.reserve(...), {
+ *     compensate: (r) => deps.release(r.id),
+ *   });
+ *   await step('charge', () => deps.charge(...), {
+ *     compensate: (p) => deps.refund(p.id),
+ *   });
+ *   return r;
+ * });
+ * ```
+ */
+declare function createSagaWorkflow<const Deps extends Readonly<Record<string, AnyResultFn>>, U = UnexpectedError, C = void>(workflowName: string, deps: Deps, options?: WorkflowOptions<ErrorsOfDeps<Deps>, U, C>): SagaWorkflow<ErrorsOfDeps<Deps>, U, Deps, C>;
+/** Saga events emitted by `runSaga` for observability. */
+type SagaEvent = {
+    type: "saga_start";
+    sagaId: string;
+    ts: number;
+} | {
+    type: "saga_success";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+} | {
+    type: "saga_error";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+    error: unknown;
+} | {
+    type: "saga_compensation_start";
+    sagaId: string;
+    ts: number;
+    stepCount: number;
+} | {
+    type: "saga_compensation_step";
+    sagaId: string;
+    stepName?: string;
+    ts: number;
+    success: boolean;
+    error?: unknown;
+} | {
+    type: "saga_compensation_end";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+    success: boolean;
+    failedCount: number;
+};
+type SagaResult<T, E> = Result<T, E | UnexpectedError | SagaCompensationError, unknown>;
+/** Saga step function — like RunStep but every step takes an optional compensate. */
+interface SagaStep<E = unknown> {
+    <T, StepE extends E, StepC = unknown>(name: string, operation: () => Result<T, StepE, StepC> | AsyncResult<T, StepE, StepC>, options?: SagaStepOptions<T>): Promise<T>;
+    try: <T, Err extends E>(name: string, operation: () => T | Promise<T>, options: {
+        error: Err;
+        compensate?: CompensationAction<T>;
+    } | {
+        onError: (cause: unknown) => Err;
+        compensate?: CompensationAction<T>;
+    }) => Promise<T>;
+}
+/**
+ * Run a saga with explicit error typing — for cases where you don't have a
+ * deps object to infer errors from. Most users should reach for
+ * `createSagaWorkflow` (or just `createWorkflow` with `step({ compensate })`).
+ */
+declare function runSaga<T, E>(fn: (context: {
+    step: SagaStep<E>;
+}) => Promise<T>, options?: {
+    onError?: (error: E | UnexpectedError | SagaCompensationError) => void;
+    onEvent?: (event: SagaEvent) => void;
+    throwOnCompensationFailure?: boolean;
+}): Promise<SagaResult<T, E>>;
+
+export { type CompensationAction, type SagaCompensationError, type SagaEvent, type SagaResult, type SagaStep, type SagaStepOptions, type SagaWorkflow, type SagaWorkflowOptions, createSagaWorkflow, isSagaCompensationError, runSaga };