Billy

🍔 Declarative and intuitive cli apps in seconds.

Basic Example

import { App, Command } from "@fivethree/billy-core";

@App()
export class ExampleApp {

    @Command('The only thing it really does is output Hello World!')
    async hello() {
        console.log('Hello World!')
    }

}

Features

• 🎂Super declarative code - Creating commands is as easy as annotating a method.
• ⏲ Schedule commands or listen for a webhook.
• 💁 Automatically prompts the user for missing parameters.
• 📋 Help and version command out of the box.
• 🧩 Easy and extensible plugin system using Typescript Mixins.

Table of contents

• Getting Started
  • Installation
  • Project Scaffolding
  • Build
  • Run the app
  • Use the library without the cli
• Documentation
  • App
  • Commands
  • Parameters
  • Action
  • Hooks
  • Jobs
  • Webhooks
  • Context
• Plugins
• Development

Getting Started

Installation

If you want you can use the cli.

npm i -g @fivethree/billy-cli

Project Scaffolding

To scaffold a new project run

billy create --app my-app

You can also run npx @fivethree/billy-cli create --app my-app to scaffold a project.

Alternatively you can clone the App and Plugin starters.

Build

In your project directory run billy build or npm run build to build the app.

Run the app

To execute a command either run billy run or node . <command> [<args>].

Billy-CLI Documentation

Use the library without the cli

Install the library in your typescript project.

npm i @fivethree/billy-core

Use it in your index.ts file.

Documentation

App

@App(options?: AppOptions)

The @App Decorator makes the class handle all kind of commands and methods you specify.

import { App } from "@fivethree/billy-core";

@App({
    name: "MyApp",
    description: "Example App",
    allowUnknownOptions: false
})
export class ExampleApp { 
    // specify methods here
}

AppOptions

| Parameter | Type | Description | Default value | | ------------------- | ------- | ------------------------------------------------------------- | --------------------------- | | name | string | Name of the App, used for help. | Name of the annotated Class | | description | string | Description for your app | null | | allowUnknownOptions | boolean | Whether to allow unknown Parameters while parsing the command | false |

Commands

@Command(options: string | CommandOptions)

Annotate a method in your App with the @Command Decorator to make it executable via the command line.

import { App, Command } from "@fivethree/billy-core";

@App()
export class ExampleApp { 
    @Command({
        alias: "speak",
        descriptions: "Prints hello world to the console."
    })
    async hello(){
        // code to execute when running the hello command
    }
}

CommandOptions

| Parameter | Type | Description | Default value | | ----------- | ------ | --------------------------------- | ------------- | | alias | string | Defines an alias for the Command. | null | | description | string | Description for your Command. | null |

Parameters

@param(options: ParamOptions)

Inject a parameter into a @Command.

import { App, param, Command, ParamOptions } from "@fivethree/billy-core";

const nameParam: ParamOptions = {
    name: 'name',
    description: 'Enter the name to greet'
}

@App()
export class ExampleApp { 

    @Command('command with parameter')
    async hello(@param(nameParam) name:string){
        console.log(`hello ${name}`);
    }
}

The name attribute can now be passed to the command by running billy hello --name Gary. Parameters are non-optional by default. If the parameter is undefined, the user will be prompted for input. If you want to specify an optional parameter, you can set the optional option in ParamOptions to true.

ParamOptions

| Parameter | Type | Description | Default value | | ----------- | ------ | -------------------------------------------------------------------------------- | ------------- | | name | string | The name of the parameter | null | | description | string | Description of the parameter that will be used when prompting the user for input | null | | optional | string | Specify that the parameter is optional (prompting will be skipped) | false |

Action

@Action(description: string)

Methods annotated with @Action will register an entry to the history upon execution inside a @Command.

import { App, Action, Command } from "@fivethree/billy-core";

@App()
export class ExampleApp { 

    @Action('my action')
    async action(){
        // your code here
    }

    @Command('Execute the action')
    async execute(){
        await this.action();
    }
}

Hooks

@Hook(hook: HookName)

Hooks can be used to intercept the running app.

import { App, Hook, afterAll, context, Context } from "@fivethree/billy-core";

@App()
export class ExampleApp { 

    @Hook(afterAll)
    async afterAll(){
        console.log('the app finished! 🏁')
    }
}

HookName

| Hook | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | beforeAll | Called right before the initial @Command, @Job or @Webhook is executed | | beforeEach | Called before every @Command, @Job or @Webhook in the program | | afterEach | Called after every @Command, @Job or @Webhook in the program | | afterAll | Called right after the last @Command, @Job or @Webhook has been executed | | onError | Called when an error occures while executing the app. The annotated method receives the Error as a paramenter | | onStart | Use the onStart Hook to override the default behaviour of the app when running the app without specifying a command (Lane Selection screen) |

Jobs

@Job(rule: string | any)

Schedule the execution of a command by annotating a method with the @Job Decorator. You need to specify a rule to let the job know when to run it. You have multiple options to define the rule. We currently use node-schedule under the hood, so visit their node-schedule Docs.

A few basic examples are provided below:

import { App, Job, every } from "@fivethree/billy-core";

@App()
export class ExampleApp { 

    // use the billy-core api
    @Job(every(30).mins)
    async recurring(){
        // runs every 30 mins
    }

    // specified using cron format
    @Job('0 30 7 ? * 1-5')
    async wakeMeUp(){
        // runs every weekday at 7:30 am
    }

    // using Date
    @Job(new Date(2020, 1, 1, 0, 0, 0))
    async newYearsEve(){
        // happy new year 2020
    }
}

Webhooks

@Webhook(path: string)

To make a method executable via a webhook annotate it with the @Webhook Decorator. Once the webhook is being called, the specified method will be run with the request body as a parameter.

import { App, Webhook } from "@fivethree/billy-core";

@App()
export class ExampleApp { 

    @Webhook('/webhook')
    async myWebhook(body: any){
        // your code here
    }
}

Context

@context()

The context can be injected into every type of method. The Context object contains the API to control the running app. Additionally, the Context can be used to manage the scheduler and the webhook server.

import { App, Command, context, Context } from "@fivethree/billy-core";

@App()
export class ExampleApp { 

    @Command('command with context')
    async hello(@context() ctx:Context){
        ctx.api.printHistory();
    }
}

Context

| Parameter | Type | Description | | ---------------- | ------- | ---------------------------------- | | name | string | name of the current command | | description | string | description of the current command | | directory | string | install directory of the app | | workingDirectory | string | current working directory | | api | CoreApi | CoreApi instance |

CoreApi

The CoreApi can be used to configure schedulers, webhooks and the history. Also you can start the command selection screen from here.

| Parameter | Type | Description | | --------- | --------- | ---------------------- | | scheduler | Scheduler | Scheduler api instance | | webhooks | WebHook | WebHook api instance |

| Method | Parameters | Returns | Description | | --------------------- | -------------- | --------------- | ------------------------------------------ | | promptLaneAndRun | | Promise<void> | show the command selection screen | | getHistory | | HistoryEntry[] | Get the current HistoryEntry list | | addToHistory | HistoryEntry[] | | Add one or multiple HistoryEntry instances | | getLatestHistoryEntry | | LatestEntry | | | printHistory | | | print the current history to console |

Plugins

You can build your own billy plugin and use it in the app.

Basic Example

import { App, usesPlugins } from "@fivethree/billy-core";
import { CorePlugin } from "@fivethree/billy-plugin-core";

// we need this line for intellisense
export interface ExampleApp extends CorePlugin { }

@App()
export class ExampleApp {
    @usesPlugins(CorePlugin)

    // Use Plugin Commands, Jobs, Actions,...here
    // multiple plugins: @usesPlugins(Plugin, OtherPlugin)

}

The app will inherit all the Commands and Actions, making them available both in your code and via the command line.

@Plugin(description: string)

The @Plugin Decorator is used to annotate a class as a plugin. Every @App can be a plugin. Just switch @App to @Plugin and move the @ƒivethree/billy-core dependency to the devDependencies array in the package.json.

import { Plugin } from "@fivethree/billy-core";

@Plugin('my example plugin')
export class ExamplePlugin { 
    // specify methods here
}

Development

1. Clone the repository and cd into project.
2. Run npm install to install all the dependencies.
3. Execute npm run build to build the project.
4. Run npm run start to start developing.