mantissa23 / ace

Node.js framework for creating command line applications

Ace

Node.js framework for creating command line applications. Used by AdonisJs

Table of contents

• Usage
• Displaying help
• Decorators
  • args.string
  • args.spread
  • flags.boolean
  • flags.string
  • flags.array

Usage

Install the package from npm registry as follows:

npm i @adonisjs/ace

# yarn
yarn add @adonisjs/ace

And then use it as follows:

import {
  Kernel,
  BaseCommand,
  args,
  flags
} from '@adonisjs/ace'

import { Ioc } from '@adonisjs/fold'
import { Application } from '@adonisjs/application/build/standalone'

class Make extends BaseCommand {
  @args.string()
  public resource: string

  @args.string()
  public name: string

  @flags.boolean()
  public overwrite: boolean
  
  public static commandName = 'make'
  public static description = 'Make a new resource'
  
  // called when the command is executed
  async handle () {
    console.log(this.name)
    console.log(this.resource)
    console.log(this.overwrite)
  }  
}

const application = new Application(__dirname, new Ioc(), {}, {})
const kernel = new Kernel(app)
kernel.register([Make]) 

kernel.handle(process.argv.splice(2))

Displaying help

Ace doesn't hijack any flags or commands to display the help. You are free to decide when and how to show the help screen.

import { Kernel, BaseCommand } from '@adonisjs/ace'

import { Ioc } from '@adonisjs/fold'
import { Application } from '@adonisjs/application/build/standalone'

const application = new Application(__dirname, new Ioc(), {}, {})
const kernel = new Kernel(app)

kernel.flag('help', (value, options, command) => {
  if (!value) {
    return
  }

  /**
   * When a command is not defined, then it will show
   * help for all the commands
   */
  Kernel.printHelp(command)
  process.exit(0)
})

kernel.handle(process.argv.splice(2))

Decorators

The module comes with ES6 decorators to define arguments and flags for a given command.

args.string

Define an argument. To make the argument optional, you can set the required property to false

args.string({ required: false })

You can also define the argument description as follows:

args.string({ description: 'The resource type to create' })

args.spread

Argument that receives all of the remaining values passed as arguments to a given command. Think of it as a spread operator in Javascript.

class Make extends BaseCommand {
  @args.spread({ description: 'One or more files' })
  public files: string[]
}

flags.boolean

Define a flag that accepts a boolean value.

flags.string

Define a flag that accepts a string value.

flags.array

Define a flag that accepts an array of values.

You can also define description for a flag, similar to the arg. Also, a flag can define aliases and the default values.

class Make extends BaseCommand {

  flags.string({
    alias: 'r',
    description: 'The resource name',
    default: 'controller',
  })
  resource: string
}

MIT License, see the included MIT file.