Outcomes

What each result status means and how to handle it.

kaji.execute() resolves with an ExecutionResult:

type ExecutionResult<Result> =
  | { status: "succeeded"; result: Result; evidence: ExecutionEvidence }
  | {
      status: "denied" | "rejected" | "failed" | "cancelled";
      error: unknown;
      evidence: ExecutionEvidence;
    }
  | { status: "unknown"; error: unknown; evidence: ExecutionEvidence };

Statuses

  • succeeded: the action ran and returned result. Use the result.
  • denied: authorize did not return true, or threw. The action did not run. Show a permission error.
  • rejected: approval was required and not given. The action did not run. Ask for approval or show an error.
  • failed: a definite failure, either a reused key with different input, a knownFailure(), or an unexpected internal error before the action started. Handle the error, and retry only if it is safe.
  • cancelled: cancelled before the action started. Nothing ran. If the cancellation came before Kaji claimed the request, nothing is saved and you can retry with the same idempotencyKey. If it came after, Kaji saves cancelled, and the same key returns it again: use a new key.
  • unknown: the action started but Kaji cannot tell whether it finished. Check the provider before retrying.

failed does not say whether a retry would work. That depends on your application.

Unknown

You get unknown when:

  • execute throws or rejects after it starts, because the side effect may already have happened.
  • The request is aborted and execute then rejects.
  • Kaji cannot save the final result to the store.
  • An identical request was already in progress, and this call stopped waiting for it (its signal aborted or timeoutMs elapsed). The original may still complete. Retry with the same key to read its result.

Do not retry blindly, and do not treat unknown as failed. Use outcome.evidence and your provider’s records to find out what happened. Sending the same request again returns the saved unknown and does not run the action again. (A call that stopped waiting is different: nothing was saved for it, and retrying returns the original’s real result once it finishes.) Start a new request, with a new idempotencyKey, only after you know it is safe.

Known failures

Throw knownFailure(cause) from execute when you know the action did not take effect, for example when the provider rejected the request before doing anything. Kaji returns failed.

execute: async (input, context) => {
  try {
    return await provider.refund(input, {
      idempotencyKey: context.idempotencyKey,
      signal: context.signal,
    });
  } catch (cause) {
    if (providerRejectedBeforeCommit(cause)) throw knownFailure(cause);
    throw cause;
  }
},

Kaji never guesses this from an error type or message.

Request errors

kaji.execute() rejects, with no status, when the request cannot start at all: an empty principalId or idempotencyKey, input that fails validation (InvalidInputError), input Kaji cannot fingerprint (UnfingerprintableValueError), or a store that fails to claim the request (KajiConfigurationError).

Handling

const outcome = await kaji.execute(refundPayment, request);

switch (outcome.status) {
  case "succeeded":
    return showReceipt(outcome.result);
  case "denied":
    return showPermissionError(outcome.error);
  case "rejected":
    return showApprovalError(outcome.error);
  case "failed":
    return handleFailure(outcome.error);
  case "cancelled":
    return showCancelled(outcome.error);
  case "unknown":
    return checkWithProvider(outcome.evidence);
}