@bernierllc/temporal-workflow-ui

Thin domain-specific wrapper around @bernierllc/generic-workflow-ui for Temporal workflows.

Installation

npm install @bernierllc/temporal-workflow-ui

Phase 1: Core Types & Adapters

This package is currently in Phase 1, providing foundational types, adapters, and validation for Temporal workflows. Components will be added in Phase 2.

What's Included (Phase 1)

• ✅ Type Definitions - Complete TypeScript types for Temporal workflows
• ✅ Adapters - Bidirectional conversion between Temporal, Generic, and JSON formats
• ✅ Validation - Comprehensive validation functions for workflows, stages, and transitions
• ⏳ Components - Coming in Phase 2

Usage

Type Definitions

import {
  TemporalWorkflow,
  TemporalWorkflowStage,
  TemporalWorkflowTransition,
  TemporalActivityMetadata,
  TemporalAgentMetadata,
} from '@bernierllc/temporal-workflow-ui';

// Define a Temporal workflow
const workflow: TemporalWorkflow = {
  id: 'wf-1',
  name: 'Data Processing Workflow',
  description: 'Process and analyze data',
  stages: [
    {
      id: 'trigger-1',
      name: 'Manual Trigger',
      order: 0,
      type: 'trigger',
      metadata: {
        nodeType: 'trigger',
        triggerType: 'manual',
      },
    },
    {
      id: 'activity-1',
      name: 'Fetch Data',
      order: 1,
      type: 'activity',
      metadata: {
        nodeType: 'activity',
        activityName: 'fetchDataActivity',
        taskQueue: 'data-processing',
        retryPolicy: {
          maximumAttempts: 3,
          backoffCoefficient: 2,
          initialInterval: 1000,
        },
        timeout: {
          startToCloseTimeout: 30000,
        },
      },
    },
    {
      id: 'agent-1',
      name: 'AI Analyzer',
      order: 2,
      type: 'agent',
      metadata: {
        nodeType: 'agent',
        agentPromptId: 'analyzer-prompt-123',
        agentName: 'Data Analyzer',
        taskQueue: 'ai-processing',
        modelProvider: 'openai',
        modelName: 'gpt-4',
        temperature: 0.7,
      },
    },
  ],
  transitions: [
    {
      id: 'trans-1',
      from: 'trigger-1',
      to: 'activity-1',
    },
    {
      id: 'trans-2',
      from: 'activity-1',
      to: 'agent-1',
      condition: 'result.status === "success"',
      metadata: {
        label: 'On Success',
      },
    },
  ],
  defaultTaskQueue: 'default',
  workflowTimeout: 300000,
};

Adapters

Temporal ↔ Generic Conversion

import { temporalToGeneric, genericToTemporal } from '@bernierllc/temporal-workflow-ui';

// Convert Temporal workflow to Generic workflow
const genericWorkflow = temporalToGeneric(workflow);

// Use with generic-workflow-ui components
import { GenericWorkflowStepper } from '@bernierllc/generic-workflow-ui';
<GenericWorkflowStepper workflow={genericWorkflow} />;

// Convert back to Temporal
const temporalWorkflow = genericToTemporal(genericWorkflow);

Temporal ↔ JSON Conversion

import { temporalWorkflowToJSON, jsonToTemporalWorkflow } from '@bernierllc/temporal-workflow-ui';

// Export workflow to JSON (n8n-style)
const jsonDefinition = temporalWorkflowToJSON(workflow);

// Save to file
fs.writeFileSync('workflow.json', JSON.stringify(jsonDefinition, null, 2));

// Import from JSON
const loadedWorkflow = jsonToTemporalWorkflow(jsonDefinition);

Validation

import { validateTemporalWorkflow, validateTaskQueue, validateRetryPolicy } from '@bernierllc/temporal-workflow-ui';

// Validate complete workflow
const result = validateTemporalWorkflow(workflow);

if (!result.valid) {
  console.error('Validation errors:');
  result.errors.forEach(error => {
    console.error(`- ${error.message}`, {
      stageId: error.stageId,
      field: error.field,
      severity: error.severity,
    });
  });
}

// Validate task queue
const taskQueueResult = validateTaskQueue({
  id: 'queue-1',
  name: 'processing-queue',
  workerCount: 5,
});

// Validate retry policy
const retryPolicyResult = validateRetryPolicy({
  maximumAttempts: 3,
  backoffCoefficient: 2,
  initialInterval: 1000,
  maximumInterval: 60000,
});

Validation Rules

The validator enforces these rules:

Workflow-Level:

• ✅ Workflow must have a name
• ✅ Workflow must have at least one trigger node
• ✅ All stage IDs must be unique
• ✅ All transition IDs must be unique
• ✅ All transitions must reference valid stages
• ✅ No circular dependencies in workflow transitions
• ✅ All stages must have names
• ✅ All signal names must be unique (v1.1.0)
• ✅ All query names must be unique (v1.1.0)
• ✅ All work queue names must be unique (v1.1.0)
• ✅ No circular dependencies in blockUntil (v1.1.0)

Node-Level:

• ✅ Activities must have activityName and taskQueue
• ✅ Agents must have agentPromptId, agentName, and taskQueue
• ✅ Signals must have signalName
• ✅ Triggers must have triggerType
• ✅ Queries must have queryName (v1.1.0)
• ✅ Scheduled workflows must have workflowName, taskQueue, and valid cronExpression (v1.1.0)
• ✅ Work queues must have queueId, queueName, signalName, and queryName (v1.1.0)
• ✅ Child workflows with blockUntil must reference existing stages (v1.1.0)
• ✅ Retry policy values must be valid
• ✅ Timeout values must be valid

New in v1.1.0

Query Nodes

Query nodes enable parent-child workflow communication:

{
  id: 'query-1',
  name: 'Check Parent Status',
  order: 3,
  type: 'query',
  metadata: {
    nodeType: 'query',
    queryName: 'getParentStatus',
    queryType: 'send',
    targetWorkflowId: 'parent-workflow-123',
    returnType: 'WorkflowStatus',
    timeout: 5000,
  },
}

Scheduled Workflow Nodes

Schedule child workflows to run on a cron schedule:

{
  id: 'scheduled-1',
  name: 'Daily Report Generator',
  order: 4,
  type: 'scheduled-workflow',
  metadata: {
    nodeType: 'scheduled-workflow',
    workflowName: 'generateDailyReport',
    taskQueue: 'reporting-queue',
    cronExpression: '0 9 * * *', // Every day at 9 AM
    timezone: 'America/New_York',
    parameters: {
      reportType: 'daily',
      recipients: ['[email protected]'],
    },
  },
}

Work Queue Nodes

Coordinate work queues with signal/query patterns:

{
  id: 'queue-1',
  name: 'High Priority Tasks',
  order: 5,
  type: 'work-queue',
  metadata: {
    nodeType: 'work-queue',
    queueId: 'high-priority-queue',
    queueName: 'highPriorityTasks',
    signalName: 'addHighPriorityTask',
    queryName: 'getQueueStatus',
    maxSize: 100,
    priority: 10,
    taskQueue: 'worker-queue',
  },
}

Enhanced Child Workflow Metadata

Child workflows now support parent communication and dependency blocking:

{
  id: 'child-1',
  name: 'Data Processor',
  order: 6,
  type: 'child-workflow',
  metadata: {
    nodeType: 'child-workflow',
    workflowName: 'processDataWorkflow',
    taskQueue: 'processing-queue',
    // Signal back to parent when done
    signalToParent: {
      signalName: 'notifyParent',
      autoCreate: true,
      queueName: 'notifications',
    },
    // Query parent for configuration
    queryParent: {
      queryName: 'getProcessingConfig',
      queueName: 'config-requests',
    },
    // Wait for other child workflows to complete
    blockUntil: ['child-fetch-data', 'child-validate'],
  },
}

Workflow-Level Arrays

Workflows can now define signals, queries, and work queues at the top level:

const workflow: TemporalWorkflow = {
  id: 'wf-1',
  name: 'Advanced Workflow',
  stages: [...],
  transitions: [...],
  // Define signals that child workflows can use
  signals: [
    {
      id: 'sig-1',
      name: 'notifyProgress',
      parameters: { progress: 'number' },
      autoGenerated: false
    },
  ],
  // Define queries for parent-child communication
  queries: [
    {
      id: 'q-1',
      name: 'getStatus',
      returnType: 'WorkflowStatus',
      autoGenerated: false
    },
  ],
  // Define work queues for coordination
  workQueues: [
    {
      id: 'wq-1',
      name: 'taskQueue',
      signalName: 'addTask',
      queryName: 'getQueueStatus',
      maxSize: 50,
      priority: 5,
    },
  ],
};

API Reference

Types

Core Types

• TemporalWorkflow - Complete workflow definition
• TemporalWorkflowStage - Individual workflow stage
• TemporalWorkflowTransition - Transition between stages
• TemporalNodeType - Node type union ('activity' | 'agent' | 'signal' | 'query' | 'scheduled-workflow' | 'work-queue' | etc.)

Metadata Types

• TemporalActivityMetadata - Activity-specific metadata
• TemporalAgentMetadata - Agent-specific metadata
• TemporalSignalMetadata - Signal-specific metadata
• TemporalTriggerMetadata - Trigger-specific metadata
• TemporalChildWorkflowMetadata - Child workflow metadata (enhanced in v1.1.0)
• TemporalParallelMetadata - Parallel execution metadata
• TemporalConditionMetadata - Conditional branching metadata
• TemporalQueryMetadata - Query operations metadata (new in v1.1.0)
• TemporalScheduledWorkflowMetadata - Cron-scheduled workflows (new in v1.1.0)
• TemporalWorkQueueMetadata - Work queue coordinator (new in v1.1.0)
• TemporalRetryPolicy - Retry configuration
• TemporalTimeout - Timeout configuration
• TaskQueue - Task queue definition

Execution Types

• TemporalWorkflowExecution - Workflow execution state
• TemporalWorkflowExecutionStatus - Execution status enum
• TemporalStageExecutionStatus - Stage execution status enum
• TemporalWorkflowEvent - Workflow event in history

Validation Types

• ValidationResult - Validation result with errors
• ValidationError - Individual validation error
• ValidationSeverity - Error severity ('error' | 'warning')

Adapters

• temporalToGeneric(workflow) - Convert Temporal → Generic
• genericToTemporal(workflow) - Convert Generic → Temporal
• temporalWorkflowToJSON(workflow) - Convert Temporal → JSON
• jsonToTemporalWorkflow(json) - Convert JSON → Temporal

Validation Functions

• validateTemporalWorkflow(workflow) - Validate complete workflow
• validateStage(stage) - Validate individual stage
• validateTransition(transition) - Validate individual transition
• validateTaskQueue(taskQueue) - Validate task queue
• validateRetryPolicy(policy) - Validate retry policy

Design Philosophy

This package follows a thin wrapper philosophy:

• Minimal Abstraction - Delegates to @bernierllc/generic-workflow-ui for UI components
• Type Safety First - Full TypeScript support with strict mode
• Lossless Conversion - Bidirectional adapters preserve all data
• Domain-Specific - Temporal-specific types and validation
• Flexible - Access underlying generic components when needed

Integration Status

• Logger: not-applicable
• Docs-Suite: ready
• NeverHub: not-applicable

Roadmap

Phase 1 (Current) ✅

• ✅ Type definitions
• ✅ Adapters (Temporal ↔ Generic ↔ JSON)
• ✅ Validation functions
• ✅ Comprehensive tests (85%+ coverage)

Phase 2 (Next)

• ⏳ TemporalWorkflowBuilder - Visual workflow builder
• ⏳ TemporalWorkflowStepper - Progress visualization
• ⏳ TemporalActivityCard - Activity detail display
• ⏳ TemporalAgentCard - Agent detail display
• ⏳ TemporalComponentPalette - Drag-and-drop palette
• ⏳ TemporalPropertyPanel - Property editor
• ⏳ TemporalTaskQueueSelector - Task queue selector
• ⏳ TemporalRetryPolicyEditor - Retry policy editor
• ⏳ TemporalTimeoutEditor - Timeout editor

Phase 3 (Future)

• ⏳ TemporalWorkflowTimeline - Execution history
• ⏳ TemporalWorkflowExecutionPanel - Complete monitoring panel
• ⏳ useTemporalWorkflow - Workflow state hook
• ⏳ useTemporalExecution - Execution monitoring hook

Contributing

This package is part of the BernierLLC tools monorepo. See the root README for development guidelines.

License

Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

See Also

• @bernierllc/generic-workflow-ui - Generic workflow UI components
• Temporal Documentation - Official Temporal docs