Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@fivethree/billy-core

Package Overview
Dependencies
Maintainers
2
Versions
72
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@fivethree/billy-core

cli plugin system core.

  • 0.16.1
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
17
increased by88.89%
Maintainers
2
Weekly downloads
 
Created
Source

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
ParameterTypeDescriptionDefault value
namestringName of the App, used for help.Name of the annotated Class
descriptionstringDescription for your appnull
allowUnknownOptionsbooleanWhether to allow unknown Parameters while parsing the commandfalse

Commands

@Command(options: stringCommandOptions)

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
ParameterTypeDescriptionDefault value
aliasstringDefines an alias for the Command.null
descriptionstringDescription 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
ParameterTypeDescriptionDefault value
namestringThe name of the parameternull
descriptionstringDescription of the parameter that will be used when prompting the user for inputnull
optionalstringSpecify 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
HookDescription
beforeAllCalled right before the initial @Command, @Job or @Webhook is executed
beforeEachCalled before every @Command, @Job or @Webhook in the program
afterEachCalled after every @Command, @Job or @Webhook in the program
afterAllCalled right after the last @Command, @Job or @Webhook has been executed
onErrorCalled when an error occures while executing the app. The annotated method receives the Error as a paramenter
onStartUse 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
ParameterTypeDescription
namestringname of the current command
descriptionstringdescription of the current command
directorystringinstall directory of the app
workingDirectorystringcurrent working directory
apiCoreApiCoreApi instance
CoreApi

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

ParameterTypeDescription
schedulerSchedulerScheduler api instance
webhooksWebHookWebHook api instance
MethodParametersReturnsDescription
promptLaneAndRunPromise<void>show the command selection screen
getHistoryHistoryEntry[]Get the current HistoryEntry list
addToHistoryHistoryEntry[]Add one or multiple HistoryEntry instances
getLatestHistoryEntryLatestEntry
printHistoryprint 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.

Keywords

FAQs

Package last updated on 30 Aug 2019

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc