@fivethree/billy-core
cli plugin system core.
Last updated 9 months ago by garygrossgarten .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @fivethree/billy-core 
SYNC missed versions from official npm registry.

Billy

???? Declarative and intuitive cli apps in seconds.

npm: version npm: license

Edit @fivethree/billy-app

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 { 
    // 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.

Current Tags

  • 0.18.0                                ...           latest (9 months ago)

72 Versions

  • 0.18.0                                ...           9 months ago
  • 0.17.0                                ...           9 months ago
  • 0.16.1                                ...           9 months ago
  • 0.16.0                                ...           9 months ago
  • 0.15.4                                ...           9 months ago
  • 0.15.3                                ...           9 months ago
  • 0.15.2                                ...           9 months ago
  • 0.15.1                                ...           a year ago
  • 0.15.0                                ...           a year ago
  • 0.14.4                                ...           a year ago
  • 0.14.3                                ...           a year ago
  • 0.14.2                                ...           a year ago
  • 0.14.1                                ...           a year ago
  • 0.14.0                                ...           a year ago
  • 0.13.1                                ...           a year ago
  • 0.13.0                                ...           a year ago
  • 0.12.5                                ...           a year ago
  • 0.12.4                                ...           a year ago
  • 0.12.3                                ...           a year ago
  • 0.12.2                                ...           a year ago
  • 0.12.1                                ...           a year ago
  • 0.12.0                                ...           a year ago
  • 0.11.0                                ...           a year ago
  • 0.10.1                                ...           a year ago
  • 0.10.0                                ...           a year ago
  • 0.9.6                                ...           a year ago
  • 0.9.5                                ...           a year ago
  • 0.9.4                                ...           a year ago
  • 0.9.3                                ...           a year ago
  • 0.9.2                                ...           a year ago
  • 0.9.1                                ...           a year ago
  • 0.9.0                                ...           a year ago
  • 0.8.2                                ...           a year ago
  • 0.8.1                                ...           a year ago
  • 0.8.0                                ...           a year ago
  • 0.7.1                                ...           a year ago
  • 0.7.0                                ...           a year ago
  • 0.6.4                                ...           a year ago
  • 0.6.3                                ...           a year ago
  • 0.6.2                                ...           a year ago
  • 0.6.1                                ...           a year ago
  • 0.6.0                                ...           a year ago
  • 0.5.4                                ...           a year ago
  • 0.5.3                                ...           a year ago
  • 0.5.2                                ...           a year ago
  • 0.5.1                                ...           a year ago
  • 0.5.0                                ...           a year ago
  • 0.4.0                                ...           a year ago
  • 0.3.15                                ...           a year ago
  • 0.3.14                                ...           a year ago
  • 0.3.13                                ...           a year ago
  • 0.3.12                                ...           a year ago
  • 0.3.11                                ...           a year ago
  • 0.3.10                                ...           a year ago
  • 0.3.9                                ...           a year ago
  • 0.3.8                                ...           a year ago
  • 0.3.7                                ...           a year ago
  • 0.3.6                                ...           a year ago
  • 0.3.5                                ...           a year ago
  • 0.3.4                                ...           a year ago
  • 0.3.3                                ...           a year ago
  • 0.3.2                                ...           a year ago
  • 0.3.1                                ...           a year ago
  • 0.3.0                                ...           a year ago
  • 0.1.0                                ...           a year ago
  • 0.0.7                                ...           a year ago
  • 0.0.6                                ...           a year ago
  • 0.0.5                                ...           a year ago
  • 0.0.4                                ...           a year ago
  • 0.0.3                                ...           a year ago
  • 0.0.2                                ...           a year ago
  • 0.0.1                                ...           a year ago

Copyright 2014 - 2016 © taobao.org |