chrono-forge

ChronoForge

ChronoForge is an open-source framework built on top of Temporal.io for creating powerful, flexible, and maintainable workflows in TypeScript. It leverages decorators and a robust workflow execution engine to simplify the definition and management of complex workflows, integrating features such as dynamic branching, detailed error handling, and integrated tracing with OpenTelemetry. ChronoForge aims to make it easier for developers to build workflows that are both scalable and easy to manage.

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

Table of Contents

1. Introduction
2. Installation
3. Getting Started
   • Basic Workflow Example
   • Stateful Workflow Example
4. Features
   • Decorators
   • Workflow Execution Engine
   • State Management
   • Error Handling and Tracing
   • Dynamic Workflow Creation
5. Documentation
6. Contributing
7. License

Introduction

ChronoForge enhances Temporal.io by providing a framework that simplifies the creation and management of workflows through a rich set of features. Whether you need to create simple workflows or manage intricate, nested workflows with complex state management and dynamic execution paths, ChronoForge provides the tools you need.

Installation

To install ChronoForge, you can use npm or yarn:

npm install chrono-forge

Or with yarn:

yarn add chrono-forge

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

Getting Started

ChronoForge makes it easy to get started with creating and managing workflows. Below are examples of how to use the framework to build both basic and stateful workflows.

Basic Workflow Example

Here is a simple example of a Temporal workflow using ChronoForge:

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

@ChronoFlow()
class SimpleWorkflow extends Workflow {
  
  @Step({ name: 'start' })
  async start() {
    console.log('Workflow started');
  }

  @Step({ name: 'process', after: 'start' })
  async process() {
    console.log('Processing data...');
    // Perform processing logic here
  }

  @Step({ name: 'complete', after: 'process' })
  async complete() {
    console.log('Workflow completed');
  }

  protected async execute() {
    // Core workflow execution logic
  }
}

Stateful Workflow Example

ChronoForge also supports stateful workflows that manage and track their state across executions:

import { StatefulWorkflowClass, Signal, Query } from 'chrono-forge';

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

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

  protected async execute() {
    console.log('Executing stateful workflow...');
    // Workflow logic that utilizes the state
  }
}

Features

Decorators

ChronoForge utilizes decorators to simplify workflow creation. Key decorators include:

• @ChronoFlow: Marks a class as a Temporal workflow.
• @Step: Defines a method as a step within a workflow.
• @Signal: Defines a method as a signal handler.
• @Query: Defines a method as a query handler.

Workflow Execution Engine

The workflow execution engine ensures that all steps in a workflow are executed in the correct order based on defined dependencies and conditions. It supports dynamic branching, allowing workflows to adapt based on runtime data.

State Management

Stateful workflows in ChronoForge can manage complex states across multiple executions. The state management system allows querying and updating state, managing child workflows, and automatically handling state transitions.

Error Handling and Tracing

ChronoForge integrates with OpenTelemetry for tracing, providing detailed logs of workflow execution. It also includes robust error handling mechanisms, ensuring workflows can recover from failures or continue as new instances when needed.

Dynamic Workflow Creation

ChronoForge supports dynamic workflow creation, allowing workflows to be defined and executed based on runtime conditions. This feature is particularly useful for workflows with complex branching or dynamic paths.

Documentation

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

• StatefulWorkflowClass Documentation
• WorkflowClass Documentation

Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, or improvements to the documentation, your input is valuable. Please refer to our Contributing Guidelines for more information on how to get involved.

License

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