Signal API Reference
This document provides a reference for the Signal API in ZoopFlow, covering core interfaces, helper functions, and middleware components.
Core Interfaces
SignalDefinition<TPayload>
Defines a signal with its ID, schema, and handler.
interface SignalDefinition<TPayload = unknown> {
/**
* Unique identifier for the signal in the format "namespace.name"
*/
id: string;
/**
* Human-readable description of the signal
*/
description?: string;
/**
* JSON Schema for validating the signal payload
*/
payloadSchema: JSONSchema7;
/**
* Whether to validate the payload against the schema
* Default: true
*/
validatePayload?: boolean;
/**
* Function that handles the signal
*/
handler: SignalHandler<TPayload>;
/**
* Custom metadata for the signal
*/
metadata?: Record<string, unknown>;
}SignalHandler<TPayload>
The function that processes a signal payload.
type SignalHandler<TPayload = unknown> = (
payload: TPayload,
context: SignalContext
) => Promise<void>;SignalRegistry
Manages signal definitions and dispatches signals to handlers.
interface SignalRegistry {
registerSignal<TPayload>(signal: SignalDefinition<TPayload>): void;
getSignal(signalId: string): SignalDefinition<unknown> | undefined;
isSignalRegistered(signalId: string): boolean;
getAllSignals(): SignalDefinition<unknown>[];
getRegisteredSignalIds(): string[];
processSignal(signalId: string, payload: unknown, context: SignalContext): Promise<void>;
unregisterSignal(signalId: string): boolean;
clear(): void;
}SignalContext
The execution environment for signal handlers.
interface SignalContext {
// Readonly properties
readonly signalId: string;
readonly flowId: string;
readonly executionId: string;
readonly workflowId?: string;
readonly runId?: string;
readonly metadata: SignalExecutionMetadata;
readonly history: SignalHistoryEntry[];
// State management
getState(): Record<string, unknown>;
getStateValue<T = unknown>(key: string): T | undefined;
setState(updates: Record<string, unknown>): Promise<void>;
setStateValue(key: string, value: unknown): Promise<void>;
// Execution tracking
log(message: string, metadata?: Record<string, unknown>): void;
addHistoryEntry(type: 'received' | 'started' | 'checkpoint' | 'completed' | 'failed',
details?: Record<string, unknown>): void;
createCheckpoint(metadata?: Record<string, unknown>): Promise<string>;
complete(details?: Record<string, unknown>): Promise<void>;
fail(reason: string, details?: Record<string, unknown>): Promise<void>;
}SignalMiddleware
Middleware for processing signals before, after, or when errors occur.
interface SignalMiddleware {
/**
* Called before a signal handler is executed
* @returns Potentially transformed payload
*/
before?(signalId: string, payload: unknown, context: SignalContext): Promise<unknown>;
/**
* Called after a signal handler has been executed successfully
*/
after?(signalId: string, payload: unknown, context: SignalContext): Promise<void>;
/**
* Called when a signal handler throws an error
*/
error?(signalId: string, error: Error, payload: unknown, context: SignalContext): Promise<void>;
}SignalManager
Coordinates signal processing with middleware support.
class SignalManager {
constructor(
registry: SignalRegistry,
options?: {
queueSignalsUntilInitialized?: boolean;
middleware?: SignalMiddleware[];
}
);
// Process a signal
processSignal(signalId: string, payload: unknown, context: SignalContext): Promise<void>;
// Queue a signal for later processing
queueSignal(signalId: string, payload: unknown, context: SignalContext): void;
// Mark the manager as initialized and process queued signals
markInitialized(): Promise<void>;
// Check if manager is initialized
isInitialized(): boolean;
// Process all queued signals
processQueuedSignals(): Promise<void>;
// Add middleware
addMiddleware(middleware: SignalMiddleware): void;
}Helper Functions
defineSignal<TPayload>(options)
Creates a typed signal definition with validation.
function defineSignal<TPayload = unknown>(options: {
namespace: string;
name: string;
description?: string;
payloadSchema: JSONSchema7;
validatePayload?: boolean;
handler: SignalHandler<TPayload>;
metadata?: Record<string, unknown>;
}): SignalDefinition<TPayload>;registerSignal<TPayload>(signal)
Registers a signal with the global registry.
function registerSignal<TPayload>(signal: SignalDefinition<TPayload>): void;versionedSignal<TPayload>(signal, version, options)
Makes a signal handler version-aware for safe evolution.
function versionedSignal<TPayload>(
originalSignal: SignalDefinition<TPayload>,
version: number,
options: {
changeId: string;
handler: SignalHandler<TPayload>;
metadata?: Record<string, unknown>;
}
): SignalDefinition<TPayload>;createSignalHandler<TPayload>(options)
Creates a standalone signal handler function.
function createSignalHandler<TPayload = unknown>(options: {
validator?: (payload: TPayload, context: SignalContext) => Promise<boolean>;
handler: SignalHandler<TPayload>;
onError?: (error: Error, payload: TPayload, context: SignalContext) => Promise<void>;
}): SignalHandler<TPayload>;withMiddleware<TPayload>(handler, middleware)
Wraps a signal handler with custom middleware.
function withMiddleware<TPayload = unknown>(
handler: SignalHandler<TPayload>,
middleware: SignalMiddleware
): SignalHandler<TPayload>;createCheckpoint(context, metadata)
Creates a checkpoint in the signal execution history.
function createCheckpoint(
context: SignalContext,
metadata?: Record<string, unknown>
): Promise<string>;processSignal<TPayload>(signal, payload, context)
Processes a signal with its handler, including validation.
function processSignal<TPayload = unknown>(
signal: SignalDefinition<TPayload>,
payload: unknown,
context: SignalContext
): Promise<void>;Middleware
Built-in Middleware
createLoggingMiddleware(options)
Creates a middleware for logging signal processing.
function createLoggingMiddleware(options?: {
logLevel?: 'debug' | 'info' | 'warn' | 'error';
includePayload?: boolean;
includeState?: boolean;
}): SignalMiddleware;createValidationMiddleware(options)
Creates a middleware for validating payloads.
function createValidationMiddleware(options?: {
strict?: boolean;
additionalValidators?: Record<string, (payload: unknown) => Promise<boolean>>;
}): SignalMiddleware;Custom Middleware Example
const loggingMiddleware: SignalMiddleware = {
before: async (signalId, payload, context) => {
console.log(`Processing signal: ${signalId}`, { payload });
return payload; // Return the payload unmodified
},
after: async (signalId, payload, context) => {
console.log(`Signal completed: ${signalId}`);
},
error: async (signalId, error, payload, context) => {
console.error(`Error processing signal: ${signalId}`, { error });
// Rethrow the error to propagate it
throw error;
}
};Temporal Integration
registerTemporalFlowControlSignals(flowId, executionId, temporalContext)
Registers standard flow control signals with Temporal.
function registerTemporalFlowControlSignals(
flowId: string,
executionId: string,
temporalContext: TemporalWorkflowContext
): void;createTemporalSignalContext(options)
Creates a signal context that works with Temporal.
function createTemporalSignalContext(options: {
signalId: string;
flowId: string;
executionId: string;
workflowId: string;
runId: string;
temporalContext: TemporalWorkflowContext;
metadata?: Record<string, unknown>;
}): SignalContext;Standard Signal Handlers
handlePauseSignal(payload, context)
Handles workflow pause operations.
function handlePauseSignal(
payload: { reason?: string },
context: SignalContext
): Promise<void>;handleResumeSignal(payload, context)
Handles workflow resume operations.
function handleResumeSignal(
payload: { reason?: string },
context: SignalContext
): Promise<void>;handleCancelSignal(payload, context)
Handles workflow cancellation.
function handleCancelSignal(
payload: { reason?: string },
context: SignalContext
): Promise<void>;handleUpdateSignal(payload, context)
Handles workflow state updates.
function handleUpdateSignal(
payload: { updates: Record<string, unknown> },
context: SignalContext
): Promise<void>;For more information on using signals in workflows, see the Signal Handling documentation.