Categorygithub.com/JSYoo5B/chain
modulepackage
1.0.0
Repository: https://github.com/jsyoo5b/chain.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
5
Dependents
0
Files
448 SLOC

# README

Chain: A Flexible Action-Pipeline Library

The chain package provides a flexible framework for building and executing sequential workflows (pipelines) of actions. It allows you to define a series of steps, each represented by an Action, which processes inputs and produces outputs. The package supports conditional branching, customizable execution paths, and error handling, enabling complex workflows with minimal boilerplate.

Features

  • Action and Pipeline Composition
    Create modular, reusable units of work (Action) and orchestrate them into robust workflows using Pipeline.

  • DAG-based Execution Plans
    Ensure predictable execution and robust validation with built-in cycle detection to enforce acyclic workflows.

  • Nested Pipelines
    Use pipelines as actions within other pipelines, enabling modular and hierarchical workflow designs.

  • Conditional Branching
    Support for Success, Failure, Abort and custom direction-based branching within your execution flows.

  • AggregateAction Support
    Simplify the orchestration of complex workflows by combining Actions or Pipelines of different types into a unified control flow using AggregateAction.

Getting Started

Installation

To install the chain package, use the following command:

go get github.com/JSYoo5B/chain

Key Concepts

Action

An Action represents a single task in the pipeline. Each action can process input data and return output or an error.

type Action[T any] interface {
    Name() string
    Run(ctx context.Context, input T) (output T, err error)
}

BranchAction

A BranchAction extends Action and supports conditional branching. It can change the execution flow based on the results of the action, allowing for multiple execution paths.

type BranchAction[T any] interface {
    Name() string
    Run(ctx context.Context, input T) (output T, err error)
    Directions() []string
    NextDirection(ctx context.Context, output T) (direction string, err error)
}

Pipeline

A Pipeline is a sequence of Actions executed in order. It orchestrates the flow of data between actions and handles branching, success, error, and abort conditions.

ActionPlan

An ActionPlan is a map that associates a direction (e.g., success, error, abort) with the next Action to execute, defining the flow of a pipeline.

type ActionPlan[T any] map[string]Action[T]

Examples

Practical examples for using the chain package will be added in future updates. Stay tuned!

# Functions

DefaultPlan returns a standard ActionPlan with valid next actions for Success and Error, and Termination for Abort.
DefaultPlanWithAbort returns an ActionPlan with valid next actions for Success, Error, and Abort.
NewAggregateAction creates an Action that works with a composite data structure (T), where T is a complex type (e.g., a struct with multiple fields) and U is the data type that the Action operates on.
NewPipeline creates a new Pipeline by taking a series of Actions as its members.
NewSimpleAction creates a new Action with a custom Run function, which can be a pure function or closure.
NewSimpleBranchAction creates a new BranchAction with customizable directions.
SuccessOnlyPlan returns an ActionPlan where only a success direction has a valid next action, and Error and Abort both lead to termination.
Terminate explicitly ends execution in a Pipeline by returning nil.
TerminationPlan returns an ActionPlan with all directions leading to termination immediately, providing a clear indication of termination rather than using nil.

# Constants

Abort represents the direction indicating that the pipeline execution should be aborted immediately.
Error represents the direction indicating that an error occurred, and the pipeline should handle it accordingly.
Success represents the direction indicating that the action completed successfully and the pipeline should continue.

# Structs

Pipeline represents a sequence of Actions that are executed in a structured flow.

# Interfaces

Action is the basic unit of execution in a package.
BranchAction is an interface for actions that control branching in the execution flow of a Pipeline.

# Type aliases

ActionPlan represents a map that associates a direction (Success, Error, Abort, and other custom branching directions) with the next Action to execute.
AggregateGetter extracts a subpart (U) from a composite data structure (T).
AggregateSetter updates a composite data structure (T) with a new subpart (U).
BranchFunc represents the signature for the function that defines the branching logic for a BranchAction in the package.
RunFunc defines the signature of a function used to implement an Action's execution logic.