stepdaddy

⚠️ Warning: I do not recommend to use this package within production as this is more of an experiment that I took to pair soon to be released Cloudflare Artifacts, and Cloudflare Workflows. It works as per the confines of my limited tests, but there are (and should be) better ways to do idempotent retires within CF Workflows.

Git-backed idempotency records for external side effectful activities inside Cloudflare Workflows.

Workflows already retries failed step.do() callbacks and caches successful step output. Stepdaddy adds what is missing for one external provider call inside a retryable step:

• reuse the committed provider result on retry
• reject a changed request for the same key
• stop for reconciliation when the outcome is unknown

Note: Stepdaddy does not provide exactly-once execution. Provider safety still depends on provider idempotency keys, reconciliation, or failing closed.

Install

bun add stepdaddy
pnpm add stepdaddy

Quick Start

import { createStepdaddy, defineExternalCall } from "stepdaddy";
import { cloudflare } from "stepdaddy/cloudflare";

const stepdaddy = createStepdaddy({ adapter: cloudflare(env.ARTIFACTS_BINDING) });

const createPaymentIntent = defineExternalCall<ChargeInput, PaymentIntent>({
  name: "stripe.payment_intent.create",
  recovery: "idempotent-call",
  execute: async ({ request, key }) => {
    const response = await fetch("https://api.stripe.com/v1/payment_intents", {
      method: "POST",
      headers: {
        authorization: `Bearer ${env.STRIPE_SECRET}`,
        "content-type": "application/x-www-form-urlencoded",
        "idempotency-key": key,
      },
      body: new URLSearchParams({
        customer: request.customerId,
        amount: String(request.amount),
        currency: request.currency,
      }),
    });

    if (!response.ok) throw new Error(`Stripe failed with HTTP ${response.status}`);
    const body = (await response.json()) as PaymentIntent;
    return { id: body.id, status: body.status };
  },
});

await step.do("charge customer", async (ctx) => {
  const intent = await stepdaddy.call(createPaymentIntent, {
    workflow: event,
    step: ctx,
    key: `wf:${event.instanceId}:charge-customer`,
    request: { customerId, amount, currency },
  });

  return { paymentIntentId: intent.id };
});

Stepdaddy records each side-effect boundary as Git history. For example, if a Workflow creates a Stripe payment intent, crashes after Stripe accepts it, and then retries with the same idempotency key, the run history shows exactly what happened:

* <sha>  (HEAD -> main) stepdaddy: stripe.invoice.create attempt 1 committed
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Step: create invoice #1
| External-Id: in_123
| Status: open
| Record: committed.json
|
* <sha>  stepdaddy: stripe.invoice.create attempt 1 started
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Step: create invoice #1
| Record: attempts/001-started.json
|
* <sha>  stepdaddy: init workflow run
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Record: .stepd/run.json
|
* <sha>  stepdaddy: stripe.payment_intent.create attempt 2 committed
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Step: charge customer #1
| External-Id: pi_123
| Status: succeeded idempotency-replay
| Record: committed.json
|
* <sha>  stepdaddy: stripe.payment_intent.create attempt 2 started
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Step: charge customer #1
| Record: attempts/002-started.json
|
* <sha>  stepdaddy: stripe.payment_intent.create attempt 1 error
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Step: charge customer #1
| Record: attempts/001-error.json
|
* <sha>  stepdaddy: stripe.payment_intent.create attempt 1 started
| Workflow: charge-customer-workflow
| Instance: <workflow-instance-id>
| Step: charge customer #1
| Record: attempts/001-started.json

stepdaddy.call(...) returns the provider result directly.

Mental Model

1. key identifies exactly one external side effect and must be stable across retries. Never include attempt numbers, timestamps, or randomness.
2. request and result must be JSON-serializable. The request digest uses JSON.stringify, so build request objects deterministically.
3. Return expected provider outcomes as values so they are stored and reused. Throw only for infrastructure or unexpected failures.
4. Redact secrets. Stepdaddy stores exactly what execute and summary return.

Retry Behavior

What happens when a step retries stepdaddy.call(...) with the same key:

State from the previous attempt	Behavior
Result committed, same request digest	Returns the stored result; execute does not run
Result committed, different request digest	Throws SIDE_EFFECT_CONFLICT; execute does not run
Attempt started, no result recorded	Follows the recovery policy
No record	Runs execute normally

Other failure cases:

• Storage fails before the started record is persisted: Stepdaddy throws and execute does not run.
• execute succeeds but the result cannot be persisted: Stepdaddy throws SIDE_EFFECT_STORAGE_FAILED; the next retry follows the recovery policy.
• execute throws: Stepdaddy records the attempt error when possible and rethrows the original error, leaving Workflows retry config in charge.

API

createStepdaddy(options): Stepdaddy

Option	Type	Description
adapter	StepdaddyAdapter	Storage adapter. See Adapters.

defineExternalCall<Request, Result>(spec): ExternalCall<Request, Result>

Field	Type	Required	Description
name	string	yes	Stable identifier for the provider operation, e.g. "stripe.payment_intent.create".
recovery	ExternalCallRecovery	yes	What to do when a previous attempt started but recorded no result. See Recovery.
execute	(ctx) => Promise<Result>	yes	Performs the provider call. Receives { request, key, workflow, step, attempt }.
request	Standard Schema	no	Validates the request before any record is written.
result	Standard Schema	no	Validates the result before it is stored.
summary	(ctx) => Record<string, unknown>	no	Compact audit fields stored with the result. Receives the execute context plus result.

stepdaddy.call(externalCall, context): Promise<Result>

Field	Type	Description
workflow	WorkflowEvent-like	The Workflow event; provides instanceId and workflowName.
step	WorkflowStepContext-like	The step.do() callback context.
key	string	Stable idempotency key for this side effect.
request	Request	The provider request payload.

Recovery

type ExternalCallRecovery<Request, Result> =
  | "idempotent-call"
  | "fail-closed"
  | { reconcile: (ctx: ReconcileContext<Request>) => Promise<ReconcileResult<Result>> };

Policy	Behavior
"idempotent-call"	Repeats execute with the same key and request. Only safe when the provider enforces idempotency for that key, such as Stripe Idempotency-Key.
"fail-closed"	Throws SIDE_EFFECT_AMBIGUOUS instead of repeating the provider call.
{ reconcile }	Looks up provider state (external ID, marker, webhook state). { status: "found", result } stores and returns the result. not_found and inconclusive throw SIDE_EFFECT_AMBIGUOUS; absence is not treated as safe to retry.

Errors

All failures are StepdaddyError with a code:

Code	Meaning
INVALID_EXTERNAL_CALL	Bad spec or call input, including schema validation failures.
SIDE_EFFECT_CONFLICT	Same key reused with a different request digest.
SIDE_EFFECT_AMBIGUOUS	Outcome unknown and the policy refuses to repeat the call.
SIDE_EFFECT_STORAGE_FAILED	The result could not be persisted after execute succeeded.
SIDE_EFFECT_RECONCILE_FAILED	The reconcile function itself threw.

Convert SIDE_EFFECT_AMBIGUOUS to Cloudflare NonRetryableError when the Workflow should stop for operator reconciliation.

Adapters

import { cloudflare } from "stepdaddy/cloudflare";
import { memory } from "stepdaddy/memory";
import { local } from "stepdaddy/local";
import { remote } from "stepdaddy/remote";

createStepdaddy({ adapter: cloudflare(env.ARTIFACTS_BINDING) });
createStepdaddy({ adapter: memory() });
createStepdaddy({ adapter: local({ root: "/tmp/stepdaddy" }) });
createStepdaddy({ adapter: remote({ url, token }) });

Stored Records

Per key, Stepdaddy stores compact JSON records under .stepd/: the request digest, one started/error record per attempt, and committed.json holding the result, the optional summary, and status: "committed" | "reconciled". Storage is an implementation detail; your Workflow returns its normal domain output.

When Not to Use Stepdaddy

• Read-only or non side-effectful repeatable work: just use step.do().
• Provider idempotency key alone is enough: call the provider directly.
• Files and large blobs: use R2.
• Compensation after a later step fails: use Workflows rollback.
• Webhook-driven progression: use waitForEvent.