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."
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.
- Introduction to ChronoForge
- Installation
- Getting Started
- Core Concepts and Features
- Detailed Feature Documentation
- Decorators Overview
- Advanced Topics
- API Reference and Technical Specifications
- Testing and Validation
- Contributing
- License
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.
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.
ChronoForge offers a streamlined approach to creating both basic and stateful workflows. Below are examples demonstrating the use of the framework’s features.
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;
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.
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.
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.
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.
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
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.
-
@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. -
@Signal
Decorator:
Defines signal handlers for real-time communication with running workflows. -
@Query
Decorator:
Specifies query handlers for retrieving workflow state or computed values. -
@Hook
Decorator:
(Speculative) Used for method interception to inject custom logic before and after methods in a workflow. -
@OnError
Decorator:
Enables custom error handling logic for specific methods or globally across the workflow. -
@On
Decorator:
Binds methods to specific events, optionally filtered by workflow type or child workflow events, allowing for fine-grained event handling within workflows.
-
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.
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 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.
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.
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:
These test files demonstrate how to use the ChronoForge framework in various scenarios, including setting up workflows, handling signals, managing errors, and more.
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.
ChronoForge is licensed under the MIT License. See the LICENSE file for more details.