Define a pipeline (Typescript)

Syntax flavors 🍦

You can either use an Object declaration or a less verbose syntax with the provided helpers functions. Those easy on the eye syntaxes have been greatly inspired by Vue Option and Composition APIs.

They are meant to be used together to improve readability where it is needed.

Object API

TIP

The Option API is considered stable because it is unlikely to change future updates. It has become complete enough to allow creation of every pipeline a man can dream of with mindfull combination of a small set of options.

Simply import the Config interface for fast type-checking and define your pipelines in an Object syntax.

//pipelight.ts
import type { Config } from "https://deno.land/x/pipelight/mod.ts";

const config: Config = {
  pipelines: [
    {
      name: "test",
      steps: [
        {
          name: "build",
          commands: ["pnpm install", "pnpm build"]
        }
      ],
      triggers: [
        {
          branches: ["master", "dev"],
          actions: ["pre-push", "pre-commit"]
        }
      ]
    }
  ]
};
export default config;

export type Config = {
  pipelines?: Pipeline[];
};

Helpers API

The Composition API is built on top of the Option API. It is a group of functions, class and methods that:

• shorten the pipeline definition;
• enable fine-grained modularity.

This syntax is the result of helpers adoption.

Simply import the provided common helper functions.

//pipelight.ts
import { pipeline, step } from "https://deno.land/x/pipelight/mod.ts";

const my_pipe = pipeline("test", () => [
  step("build", () => ["pnpm install"])
]).trigger({
  branches: ["master", "dev"],
  actions: ["pre-push", "pre-commit"]
});

export default {
  pipelines: [my_pipe]
};

The only rule

Pipelight only restricting rule is that a configuration file has to default export an Object of type Config. In other words, your config file must contain a line like this:

//pipelight.ts
export default config: Config;

Everything else that happens inside this script is up to you.

With such a wide rule, the pipeline definition process gives way to creativity and imagination.

Where this freedom can be really enjoyable, it might sometimes be frustrating. That is why you are provided with some empirical guidelines, patterns and helpers to speed up your pipeline creation.

Thus you remain free in your creation process, but you are not helpless.

Types in depth

You can see the complete type definition on DenoLand.

There is some options that are discussed further in the documentation but that you can already explore by going through the self documented deno documentation

A pipeline is an object that has an array of steps, optional triggers for automatic execution, and optional global fallbacks for out-of-flow step execution.

export interface Pipeline {
  name: string;
  steps: StepOrParallel[];
  triggers?: Trigger[];
  // Execution flow ptions
  options?: PipelineOpts;
  // Fallbacks
  on_started?: StepOrParallel[];
  on_failure?: StepOrParallel[];
  on_success?: StepOrParallel[];
  on_abortion?: StepOrParallel[];
}

export interface PipelineOpts {
  attach?: boolean;
  log_level?: LogLevel | string;
}

A step is an object that has an array of commands, an optional execution mode and optional fallbacks for more specific out of the flow step execution.

export type Step = {
  name: string;
  commands: string[];
  // Execution flow ptions
  options?: StepOpts;
  // Fallbacks
  on_started?: StepOrParallel[];
  on_failure?: StepOrParallel[];
  on_success?: StepOrParallel[];
  on_abortion?: StepOrParallel[];
};

export interface StepOpts {
  mode?: Mode | string;
}