Capstan is a framework for running a series of actions with pre-checks and
post-checks. It defines three main classes: Command
, Action
, and
Controller
.
Capstan's goal is to reduce the human labor and errors involved in safety checks when performing major changes to complex systems such as infrastructure, while being generic enough to be used in any environment.
See examples for a full example.
To use this framework, you will create instances of the Command
, Check
,
Action
, and Controller
classes, and then call the run()
method of the
Controller
instance.
For example:
import { Action, Check, Command, Controller } from "./main.ts";
// Define commands
const Command = new Command({
name: "My Command",
fn: async () => {
console.log("Executing my command...");
// Perform some operation
return true;
},
});
// Define checks
const PreCheck = new Check({
name: "My Pre-check",
fn: async () => {
console.log("Checking pre-condition...");
// Perform some check and return true if the command should run
return true;
},
});
const PostCheck = new Check({
name: "My Post-check",
fn: async () => {
console.log("Checking post-condition...");
// Perform some check and return true if checks are successful
return true;
},
});
// Define an action
const ExampleAction = new Action({
name: "My Action",
command: Command,
preChecks: [PreCheck],
postChecks: [PostCheck],
failFast: true,
});
// Create a controller and run the action
const controller = new Controller({
actions: [ExampleAction],
});
await controller.run();
In this example, we define a command (myCommand
), two checks (myPreCheck
and
myPostCheck
), and an action (myAction
) that includes the command and checks.
We then create a Controller
instance with the action and call its run()
method to execute the action.
The Command
class represents a single command or task to be executed. It has
two properties:
name
: A string representing the name of the command.fn
: A function that returns a Promise, which is the actual command to be executed.
The Check
class extends the Command
class and is used to define pre-checks
and post-checks for an action.
The Action
class represents a single action that consists of pre-checks, a
command, and post-checks. It has the following properties:
preChecks
: An array ofCheck
objects representing the pre-checks to be executed before the command.command
: ACommand
object representing the main command to be executed.postChecks
: An array ofCheck
objects representing the post-checks to be executed after the command.name
: A string representing the name of the action.failFast
: A boolean indicating whether the action should stop executing if any pre-check or post-check fails.
The Action
class has two main methods:
-
runChecks(checks: Check[])
: This method executes an array of checks and returns an object containing a booleanproceed
property indicating whether all checks passed, and aresults
array containing the results of each check. -
run()
: This method executes the entire action. It first runs the pre-checks, then the main command, and finally the post-checks. If any pre-check or post-check fails andfailFast
is set totrue
, the action stops executing.
The Controller
class manages the execution of multiple actions. It has the
following property:
actions
: An array ofAction
objects representing the actions to be executed.
The Controller
class has a single method:
run()
: This method iterates over theactions
array and executes each action using therun()
method of theAction
class. If an action fails, an error is logged to the console.