Function proxyActivities

Creates a typed proxy for calling activity functions with durable execution, automatic retry, and deterministic replay. This is the primary way to invoke side-effectful code (HTTP calls, database writes, file I/O) from within a workflow function.

Activities execute on a separate worker process via message queue, isolating side effects from the deterministic workflow function. Each proxied call is assigned a unique execution index, and on replay the stored result is returned without re-executing the activity.

Routing

• Default: Activities route to {workflowTaskQueue}-activity.
• Explicit taskQueue: Activities route to {taskQueue}-activity, enabling shared/global activity worker pools across workflows.

Retry Policy

Option	Default	Description
maximumAttempts	50	Max retries before the activity is marked as failed
backoffCoefficient	2	Exponential backoff multiplier
maximumInterval	'5m'	Cap on delay between retries
throwOnError	true	Throw on activity failure (set false to return the error)

Examples

import { Durable } from '@hotmeshio/hotmesh';
import * as activities from './activities';

// Standard pattern: register and proxy activities inline
export async function orderWorkflow(orderId: string): Promise<string> {
  const { validateOrder, chargePayment, sendConfirmation } =
    Durable.workflow.proxyActivities<typeof activities>({
      activities,
      retry: {
        maximumAttempts: 3,
        backoffCoefficient: 2,
        maximumInterval: '30s',
      },
    });

  await validateOrder(orderId);
  const receipt = await chargePayment(orderId);
  await sendConfirmation(orderId, receipt);
  return receipt;
}
Copy

// Remote activities: reference a pre-registered worker pool by taskQueue
interface PaymentActivities {
  processPayment: (amount: number) => Promise<string>;
  refundPayment: (txId: string) => Promise<void>;
}

export async function refundWorkflow(txId: string): Promise<void> {
  const { refundPayment } =
    Durable.workflow.proxyActivities<PaymentActivities>({
      taskQueue: 'payments',
      retry: { maximumAttempts: 5 },
    });

  await refundPayment(txId);
}
Copy

// Interceptor with shared activity pool
const auditInterceptor: WorkflowInboundCallsInterceptor = {
  async execute(ctx, next) {
    const { auditLog } = Durable.workflow.proxyActivities<{
      auditLog: (id: string, action: string) => Promise<void>;
    }>({
      taskQueue: 'shared-audit',
      retry: { maximumAttempts: 3 },
    });

    await auditLog(ctx.get('workflowId'), 'started');
    const result = await next();
    await auditLog(ctx.get('workflowId'), 'completed');
    return result;
  },
};
Copy

// Graceful error handling (no throw)
const { riskyOperation } = Durable.workflow.proxyActivities<typeof activities>({
  activities,
  retry: { maximumAttempts: 1, throwOnError: false },
});

const result = await riskyOperation();
if (result instanceof Error) {
  // handle gracefully
}
Copy

Long-running activities execute exactly once

startToCloseTimeout bounds an activity's run and is honored for long work (a 30–120s batch loop is a supported shape: poll → reconcile → act, one durable checkpoint per call). While the activity runs, the consumer heartbeats its stream reservation at half the base window, so the message stays leased for the full run — however long — and is redelivered to another worker only when the owning consumer crashes and stops heartbeating. The collation ledger then guarantees any redelivered message settles as a duplicate before re-executing the activity. With a securedWorker connection (SECURITY DEFINER stored-proc mode), lease extension is unavailable and an activity must finish within the adaptive reservation window instead.