SolidActions SDK

Lightweight durable workflows for TypeScript.

What is SolidActions?

SolidActions provides lightweight durable workflows built on top of an HTTP API backend. Instead of managing your own workflow orchestrator or task queue system, you can use SolidActions to add durable workflows and queues to your program in just a few lines of code.

This SDK uses HTTP API calls to communicate with a SolidActions backend server (such as Laravel) that implements the workflow persistence API.

Features

• 💾 Durable Workflows - Checkpoint workflow state to automatically resume from failures
• 📒 Durable Queues - Run tasks in the background with guaranteed completion
• 📅 Durable Scheduling - Schedule workflows with cron syntax or durable sleep
• 📫 Durable Notifications - Pause workflows until signals/notifications arrive
• ⚙️ Workflow Management - Query, cancel, resume, or restart workflows programmatically

Installation

npm install @solidactions/sdk

Quick Start

import { SolidActions } from '@solidactions/sdk';

// Register workflow steps
async function stepOne() {
  SolidActions.logger.info('Step one completed!');
}

async function stepTwo() {
  SolidActions.logger.info('Step two completed!');
}

// Register the workflow
async function workflowFunction() {
  await SolidActions.runStep(stepOne);
  await SolidActions.runStep(stepTwo);
}
const workflow = SolidActions.registerWorkflow(workflowFunction);

Configuration

Configure via environment variables:

SOLIDACTIONS_API_URL=https://your-backend.com/api
SOLIDACTIONS_API_KEY=your-api-key

Or in code:

import { SolidActions } from '@solidactions/sdk';

SolidActions.setConfig({
  name: 'my-app',
  api: {
    url: process.env.SOLIDACTIONS_API_URL!,
    key: process.env.SOLIDACTIONS_API_KEY!,
  },
});

await SolidActions.launch();

Or use a config file (solidactions-config.yaml):

name: my-app
api:
  url: https://your-api-backend.com
  key: ${SOLIDACTIONS_API_KEY}

Durable Workflows

Workflows checkpoint their state so they can resume from the last completed step after any failure:

async function paymentWorkflow(orderId: string) {
  // Step 1: Reserve inventory
  await SolidActions.runStep(() => reserveInventory(orderId));

  // Step 2: Process payment (if this fails, we resume from step 2)
  await SolidActions.runStep(() => processPayment(orderId));

  // Step 3: Ship order
  await SolidActions.runStep(() => shipOrder(orderId));
}
const workflow = SolidActions.registerWorkflow(paymentWorkflow);

Durable Queues

Run tasks in the background with guaranteed completion:

import { SolidActions, WorkflowQueue } from '@solidactions/sdk';

const queue = new WorkflowQueue('background_tasks');

async function processTask(task: Task) {
  // Process the task...
}
const taskWorkflow = SolidActions.registerWorkflow(processTask);

// Enqueue work
await SolidActions.startWorkflow(taskWorkflow, { queueName: queue.name })(task);

Durable Sleep

Sleep for any duration (even days) - workflows resume exactly when the sleep ends:

async function reminderWorkflow(email: string) {
  await SolidActions.runStep(() => sendConfirmationEmail(email));
  await SolidActions.sleep(86400000); // Sleep 24 hours
  await SolidActions.runStep(() => sendReminderEmail(email));
}

Signals and Events

Wait for external signals or emit events:

async function approvalWorkflow(requestId: string) {
  // Wait for approval signal (with timeout)
  const approved = await SolidActions.recv<boolean>('approval', 3600);

  if (approved) {
    await SolidActions.runStep(() => processApproval(requestId));
  }
}

Client API

Use the client to manage workflows programmatically:

import { SolidActionsClient } from '@solidactions/sdk';

const client = SolidActionsClient.create();

// List workflows
const workflows = await client.listWorkflows({
  status: 'ERROR',
  startTime: '2025-04-22T03:00:00Z',
});

// Cancel or resume workflows
await client.cancelWorkflow(workflowId);
await client.resumeWorkflow(workflowId);

Deploying Workflows

Use the @solidactions/cli to deploy your workflows:

npm install -g @solidactions/cli

# Authenticate
solidactions init <api-key>

# Deploy your project
solidactions deploy <project-name> <path>

The CLI handles project creation, source upload, Docker builds, environment variables, and scheduling. See the CLI repo for full documentation.

Documentation

See docs/sdk-reference.md for comprehensive SDK documentation including:

• Lifecycle: SolidActions.run(), setConfig()/launch()/shutdown(), getInput()
• Workflows: registration, determinism rules, IDs and idempotency, timeouts, child workflows
• Steps: runStep(), configurable retries, parallel execution with Promise.allSettled()
• Durable primitives: sleep(), now(), randomUUID()
• Communication: send()/recv() messaging, setEvent()/getEvent() events, streaming, respond()
• Workflow handles and management: listWorkflows(), cancelWorkflow(), forkWorkflow()
• SolidActionsClient: standalone HTTP client for external workflow queries
• Configuration, custom serialization, testing, and error classes
• Recovery and versioning