npm

chrono-forge
TypeScript icon, indicating that this package has built-in type declarations

1.3.44 • Public • Published

ChronoForge Test Suite

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:

Table of Contents

  1. Introduction to ChronoForge
  2. Installation
  3. Getting Started
  4. Core Concepts and Features
  5. Detailed Feature Documentation
  6. Decorators Overview
  7. Advanced Topics
  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.

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.

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.

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.

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

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

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

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

  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.

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.

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.

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.

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.

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.

Package Sidebar

Install

npm i chrono-forge

Weekly Downloads

499

Version

1.3.44

License

MIT

Unpacked Size

358 kB

Total Files

203

Last publish

Collaborators

  • pilsy