chrono-forge

ChronoForge

ChronoForge is an open-source framework designed to streamline the creation and management of workflows using Temporal.io in TypeScript. By providing a rich set of decorators, a robust workflow execution engine, and integrated state management, ChronoForge simplifies the development of complex workflows. The framework is ideal for building scalable, maintainable workflows that require intricate state management, dynamic branching, and robust error handling.

"Those who say it cannot be done should stop interrupting the people doing it."

Documentation

For detailed documentation on all features and usage, please refer to the following:

• StatefulWorkflow Documentation: Comprehensive guide on using the StatefulWorkflowClass.
• Workflow Documentation: Detailed documentation on the base Workflow class and its features.
• Entities Documentation: Guide on managing normalized state within workflows.

Table of Contents

1. Introduction to ChronoForge
2. Installation
3. Getting Started
   • Workflow Example
   • Stateful Workflow Example
4. Core Concepts and Features
   • Workflow Class
   • StatefulWorkflow Class
5. Detailed Feature Documentation
   • Workflow Class Features
   • StatefulWorkflow Class Features
6. Decorators Overview
   • List of Decorators
   • Detailed Documentation and Examples for @ChronoFlow
7. Advanced Topics
   • Handling Circular Workflow Relationships
   • Security and API Token Management
8. API Reference and Technical Specifications
9. Testing and Validation
10. Contributing
11. License

Introduction to ChronoForge

ChronoForge enhances Temporal's workflow engine by providing developers with a set of tools and abstractions to manage complex workflows in a declarative and flexible way. Whether you're building a system that handles hierarchical task management, real-time data synchronization, or a robust microservice orchestration platform, ChronoForge provides the building blocks necessary to manage stateful workflows effectively.

ChronoForge consists of two primary classes:

• Workflow Class: The foundational class that provides core features for handling signals, queries, error management, and lifecycle hooks.
• StatefulWorkflow Class: An extension of the Workflow class, adding powerful state management capabilities, automatic child workflow orchestration, dynamic subscription handling, and more.

For a quick introduction, see the Overview documentation, which provides a high-level overview of the Workflow class and its role in the ChronoForge framework.

Installation

To get started with ChronoForge, install it via npm or yarn:

npm install chrono-forge

Or with yarn:

yarn add chrono-forge

ChronoForge requires Node.js 14 or later and integrates seamlessly with Temporal.io's TypeScript SDK.

Getting Started

ChronoForge offers a streamlined approach to creating both basic and stateful workflows. Below are examples demonstrating the use of the framework’s features.

Workflow Example

A basic workflow in ChronoForge utilizes the @ChronoFlow decorator along with various step and signal decorators to define its logic:

import { ChronoFlow, Workflow } from 'chrono-forge';

@ChronoFlow()
export class SimpleWorkflow extends Workflow {
  protected async execute() {
    console.log('Executing workflow...');
  }
}

export default SimpleWorkflow;

Stateful Workflow Example

ChronoForge also supports stateful workflows that manage normalized state across executions:

import { StatefulWorkflow, Property, Signal, Query, Before, Hook, ContinueAsNew } from 'chrono-forge';
import schemas, { MyEntity } from "@schemas"

@ChronoFlow({
  schema: MyEntity,
  schemas,
})
class MyStatefulWorkflow extends StatefulWorkflow {
  protected maxIterations = 10000;
  protected continueAsNew = true;

  @Property() // Wires up "custom" query to get the value, and "custom" signal to set the value
  protected custom: string = "my custom value";

  @Query()
  public getStateValue(key: string): any {
    return this.state[key];
  }

  @Signal()
  public updateStateValue(key: string, value: any): void {
    this.state[key] = value;
  }

  @On("someSignal")
  async handleSomeSignal(data: any) {
    this.log.debug(`someSignal event fired! with ${data}...`);
  }

  @Before("processState")
  async beforeExecuteAndProcessingNewState(newState: EntitiesState) {
    this.log.info(`Hooked in before processing new state to do something...`);
  }

  @Before("execute")
  async beforeExecute() {
    this.log.info('Before execution hook.');
  }

  protected async execute() {
    console.log('Executing stateful workflow with normalized state...');
  }

  @Hook({ after: 'execute' })
  async afterExecution() {
    this.log.info('After execution hook.');
  }
}

export default MyStatefulWorkflow;

src/schema/index.ts

import { SchemaManager } from '../SchemaManager';

const schemaManager = SchemaManager.getInstance();
schemaManager.setSchemas({
  MyEntity: {
    idAttribute: 'id',
    myOtherEntity: ['MyOtherEntity']
  },
  MyOtherEntity: {
    idAttribute: 'id',
    myEntity: 'MyEntity'
  }
});

const schemas = schemaManager.getSchemas();
const { MyEntity, MyOtherEntity } = schemas;
export { MyEntity, MyOtherEntity };
export default schemas;

In this example, MyStatefulWorkflow handles normalized state using the normalizr library, allowing for complex state management across multiple executions.

Core Concepts and Features

Workflow Class

The Workflow class serves as the base class for defining Temporal workflows in ChronoForge. It provides essential features such as signal and query handling, error management with decorators, and lifecycle hooks for executing custom logic at different stages of workflow execution. The Workflow class is designed to be extended, allowing developers to define workflows that leverage Temporal's capabilities while integrating ChronoForge's advanced features.

• Signal Handling: Real-time communication with running workflows using the @Signal decorator. For details, see Signal Handling.
• Query Handling: Retrieve workflow state or computed values using the @Query decorator. Learn more in Query Handling.
• Error Handling: Robust error management using the @OnError decorator to define custom error handlers. Detailed examples are provided in Error Handling with @OnError.
• Lifecycle Hooks: Inject custom logic before or after specific methods using the @Hook decorator. See Lifecycle Management Hooks for more information.
• Execution Control: Manage the workflow execution lifecycle with methods like execute, which allow workflows to be paused, resumed, or terminated. For insights into managing long-running workflows, see Execution Control and Flow Management.

The comprehensive breakdown of the Workflow class features can be found in the Workflow Class Features section.

StatefulWorkflow Class

The StatefulWorkflow class extends the Workflow class by introducing advanced state management capabilities and automatic orchestration of child workflows. This class is ideal for workflows that require managing complex states, such as nested workflows, dynamic data loading, and API integration.

• State Management: Manage and normalize workflow state using schemas. For an in-depth guide, see State Management and Data Normalization.
• Child Workflow Management: Automatically manage child workflows' lifecycles. Details can be found in Child Workflow Lifecycle Management.
• Dynamic Subscription Handling: Dynamically handle subscriptions to state changes within workflows. For more information, refer to Dynamic Subscription Handling.
• Error Handling and Recovery: Error management strategies for complex workflows are discussed in Error Handling with @OnError.

A complete overview of the StatefulWorkflow class and its features is available in the StatefulWorkflow Class Features section.

Detailed Feature Documentation

Workflow Class Features

The Workflow class offers various features to streamline the development of Temporal workflows. Each feature is designed to address common workflow development challenges such as error handling, state management, and inter-workflow communication.

• Signal Handling
• Query Handling
• Execution Control and Flow Management
• Error Handling with @OnError
• Lifecycle Management Hooks
• Decorators Overview

For a complete list of decorators provided by the Workflow class and their usage, see the Decorators Provided by Workflow.ts.

StatefulWorkflow Class Features

The StatefulWorkflow class extends the functionality provided by the Workflow class by adding advanced state management, automatic child workflow orchestration, and dynamic subscription handling capabilities. This class is particularly useful for building complex, stateful workflows that require a high degree of flexibility and scalability.

• State Management and Data Normalization
• Child Workflow Lifecycle Management
• Dynamic Data Loading and API Integration
• Handling Circular Workflow Relationships
• Security and API Token Management

Decorators Overview

ChronoForge uses a series of decorators to define and manage various aspects of workflows, such as signals, queries, hooks, and error handling. These decorators simplify the process of extending workflows and ensure consistency across different parts of the workflow system.

List of Decorators

1. @ChronoFlow Decorator:
   Used to register a class as a Temporal workflow within ChronoForge. This decorator manages setup tasks, ensures correct initialization, and binds signals, queries, and hooks.

   • Read more about @ChronoFlow

2. @Signal Decorator:
   Defines signal handlers for real-time communication with running workflows.

   • Read more about @Signal

3. @Query Decorator:
   Specifies query handlers for retrieving workflow state or computed values.

   • Read more about @Query

4. @Hook Decorator:
   (Speculative) Used for method interception to inject custom logic before and after methods in a workflow.

   • Read more about @Hook

5. @OnError Decorator:
   Enables custom error handling logic for specific methods or globally across the workflow.

   • Read more about @OnError

6. @On Decorator:
   Binds methods to specific events, optionally filtered by workflow type or child workflow events, allowing for fine-grained event handling within workflows.

   • Read more about @On

Detailed Documentation and Examples for @ChronoFlow

• Introduction to ChronoForge and Decorators: To understand the overall role of decorators in ChronoForge and how @ChronoFlow fits into the workflow development process, refer to the Introduction to StatefulWorkflow documentation.

• Creating a Workflow with @ChronoFlow: The Getting Started Guide provides step-by-step instructions on how to create a basic workflow using the @ChronoFlow decorator. It covers how to define a class as a workflow and set up initial signals and queries.

• Advanced Usage and Complete Example: For an advanced example that demonstrates the @ChronoFlow decorator's full capabilities, see the Complete Usage Example. This example shows how to combine signals, queries, error handling, and hooks to build a robust workflow that handles complex interactions and state management.

Advanced Topics

Handling Circular Workflow Relationships

ChronoForge offers advanced features for managing circular relationships between workflows, ensuring that circular dependencies do not cause infinite loops or state conflicts. This is particularly important when dealing with parent-child workflow relationships and bidirectional subscriptions.

• To learn more, see Handling Circular Workflow Relationships.

Security and API Token Management

Security is a critical aspect of workflow management, especially when dealing with dynamic data loading and external API integrations. ChronoForge provides built-in support for managing API tokens and securing workflows.

• For a detailed overview, see Security and API Token Management.

API Reference and Technical Specifications

ChronoForge's API is built around decorators and workflow classes that provide a rich set of features for managing workflows. Developers can extend these classes and utilize decorators to customize workflows for their specific use cases.

• The API Reference and Technical Specifications section contains links to all relevant technical documentation files, including:
  • Workflow Class Overview
  • StatefulWorkflow Class Overview
  • All Decorators and Their Usage
  • Complete Usage Example demonstrating a comprehensive workflow setup using all features.

Testing and Validation

ChronoForge includes a suite of test cases to validate the behavior of workflows and ensure that features like bi-directional subscriptions, error handling, and state synchronization work as expected.

• For detailed test cases and examples, refer to:
  • Workflow Class Tests
  • StatefulWorkflow Class Tests

These test files demonstrate how to use the ChronoForge framework in various scenarios, including setting up workflows, handling signals, managing errors, and more.

Contributing

We welcome contributions from the community! Whether you’re fixing bugs, adding new features, or improving documentation, your contributions are valued. Please refer to our Contributing Guidelines for more details.

License

ChronoForge is licensed under the MIT License. See the LICENSE file for more details.