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
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 {
}
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(){
}
}
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(){
}
@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 {
@Job(every(30).mins)
async recurring(){
}
@Job('0 30 7 ? * 1-5')
async wakeMeUp(){
}
@Job(new Date(2020, 1, 1, 0, 0, 0))
async newYearsEve(){
}
}
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){
}
}
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";
export interface ExampleApp extends CorePlugin { }
@App()
export class ExampleApp {
@usesPlugins(CorePlugin)
}
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 {
}
Development
- Clone the repository and cd into project.
- Run
npm install
to install all the dependencies. - Execute
npm run build
to build the project. - Run
npm run start
to start developing.