State Machine Manager

This library provides a flexible and robust state machine implementation designed for backend applications. It is particularly useful for managing complex workflows

Installation

To install the library, use npm:

Basic Concepts

States

States represent the various conditions that your system can be in. They can be defined as strings or numbers.

Events

Events trigger transitions between states. They can also be defined as strings or numbers.

Context

Context is an optional object that can store any additional information needed for transitions.

Transitions

Transitions define the allowed movements between states, triggered by events. They can have associated actions and guards.

Transition History

The state machine tracks the history of state transitions, including retry counts and reasons for transitions.

Usage

enum WithdrawalStates {
  REQUESTED = "REQUESTED",
  VALIDATING = "VALIDATING",
  APPROVED = "APPROVED",
  REJECTED = "REJECTED",
}

enum WithdrawalEvents {
  VALIDATE = "VALIDATE",
  APPROVE = "APPROVE",
  REJECT = "REJECT",
}

const withdrawalStateMachineConfig = new StateMachineConfig<WithdrawalStates, WithdrawalEvents, Context>();

Object.values(WithdrawalStates).forEach(state => withdrawalStateMachineConfig.addState(state));

withdrawalStateMachineConfig.setInitialStates([WithdrawalStates.REQUESTED]);
withdrawalStateMachineConfig.setFinalStates([WithdrawalStates.APPROVED, WithdrawalStates.REJECTED]);

withdrawalStateMachineConfig.addTransition({
  source: WithdrawalStates.REQUESTED,
  target: WithdrawalStates.VALIDATING,
  event: WithdrawalEvents.VALIDATE,
});

withdrawalStateMachineConfig.addTransition({
  source: WithdrawalStates.VALIDATING,
  target: WithdrawalStates.APPROVED,
  event: WithdrawalEvents.APPROVE,
});

withdrawalStateMachineConfig.addTransition({
  source: WithdrawalStates.VALIDATING,
  target: WithdrawalStates.REJECTED,
  event: WithdrawalEvents.REJECT,
});

const withdrawalInitialState = WithdrawalStates.REQUESTED;
const withdrawalTransitionHistory: TransitionHistory = {
  currentState: {
    state: withdrawalInitialState,
    startTime: new Date().toISOString(),
  },
  history: [],
  retryCounts: {},
};

const withdrawalStateMachine = new StateMachine(withdrawalStateMachineConfig, withdrawalInitialState, withdrawalTransitionHistory);

withdrawalStateMachine.sendEvent(WithdrawalEvents.VALIDATE);
console.log(withdrawalStateMachine.getCurrentState()); // VALIDATING

withdrawalStateMachine.sendEvent(WithdrawalEvents.APPROVE);
console.log(withdrawalStateMachine.getCurrentState()); // APPROVED

console.log(withdrawalStateMachine.getTransitionHistory());

Conclusion

This state machine library provides a structured and flexible way to manage complex workflows, in your backend applications. With easy-to-define states, events, and transitions, you can ensure your processes are robust and maintainable.