Executions & HTTPLocal SDK

Local SDK

createLocalSdk<Router>(runtime, options?) creates an SDK that reads and writes execution records directly against a runtime. Use it in API servers, CLI commands, or background jobs that run in the same process as the dispatcher or share the same SQLite database file.

The local SDK only admits and updates execution records – it does not run workflow code. A running ExecutionDispatcher attached to the same runtime must be active for admitted executions to progress.

Creating and using the SDK

Pass your workflow Router type as a type parameter to createLocalSdk so TypeScript checks workflowId, params, and triggerAndWait return types without importing workflow code into every caller:

import pino from "pino";
import { ExecutionDispatcher, createLocalSdk } from "@notation/durable";
import { createWorkflowInvoker } from "@notation/durable/worker";
import type { Router } from "../workflows/router";
import { runtime } from "./runtime";

const logger = pino({ level: "warn" });

export const invoker = createWorkflowInvoker({
  workerPath: new URL("./worker.ts", import.meta.url).href,
  logger,
});

export const dispatcher = new ExecutionDispatcher(runtime, {
  invoker,
  logger,
});

export const sdk = createLocalSdk<Router>(runtime, { invoker });
import { sdk } from "../durable/client";

export async function startExport(accountId: string, month: string) {
  const { executionId } = await sdk.trigger({
    workflowId: "export-report",
    executionId: `export:${accountId}:${month}`,
    idempotent: true,
    params: { accountId, month },
  });

  return executionId;
}

export async function getExport(executionId: string) {
  const execution = await sdk.poll(executionId);
  if (!execution) return { status: "not-found" };

  if (execution.status === "completed") {
    const { url } = execution.result as { url: string };
    return { status: "ready", url };
  }

  return { status: execution.status };
}

export async function runExportNow(accountId: string, month: string) {
  return sdk.triggerAndWait({
    workflowId: "export-report",
    params: { accountId, month },
  });
}

export async function cancelExport(executionId: string) {
  return sdk.cancel(executionId, { reason: "cancelled by user" });
}

Options

OptionBehavior
invokerWakes in-process waits immediately when the local dispatcher finishes an execution
pollIntervalSets how often wait reads the execution record in milliseconds

pollInterval defaults to 25 milliseconds and throws RangeError if it is not a finite number greater than zero.

In-process invoker fast path

When an ExecutionDispatcher runs in the same process, passing { invoker } connects wait and triggerAndWait to the invoker's completion notifications so they read the execution record as soon as an outcome is written instead of waiting for the next pollInterval tick.

Passing invoker is strictly an optimization. Outcomes always come from the durable execution record, so omitting invoker – or waiting on an execution delivered by another process – produces the same result at the next pollInterval read.

Methods

The local SDK implements ExecutionObserver & ExecutionControl along with trigger and triggerAndWait:

MethodRole
triggerAdmits an execution and returns TriggerAck
triggerAndWaitAdmits an execution and resolves with its typed return value
pollReads the current ExecutionView once
waitWaits for a terminal outcome, timeout, or AbortSignal
listPages through ExecutionView records newest first
cancelRecords a graceful or forced cancellation request