npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

commands-x

v0.0.1

Published

Elegant command-line interface (CLI) development tool

Downloads

13

Readme

Commands-x

NPM Version License

English | 简体中文

Elegant command-line interface (CLI) development tool, providing a set of features and utilities to simplify the process of creating command-line applications

Features

  • Zero dependencies
  • Sub-commands support
  • Strongly typed arguments
  • Auto generated usage and version
  • Fast and lightweight arguments parser

Install

npm install commands-x --save-dev

Quick Start

The simplest way to create a CLI application:

Create a file: simple.ts

import { runCommand } from 'commands-x'

runCommand({
  meta: {
    name: 'simple',
    version: '0.0.1',
    description: 'simple description...'
  },
  args: {
    firstName: {
      type: 'positional',
      description: 'Your first name',
      isRequired: true
    },
    lastName: {
      type: 'positional',
      description: 'Your last name'
    },
    nickName: {
      type: 'string',
      description: 'Your nick name',
      alias: 'n'
    },
    age: {
      type: 'number',
      description: 'Your age',
      alias: 'a'
    },
    isDeveloper: {
      type: 'boolean',
      description: 'You are developer or not?',
      alias: 'd',
      defaultValue: false
    }
  },
  main: (context) => {
    //
    // In development, type hints are provided
    //
    // context: {
    //   // Parsed command-line input arguments
    //   argv: {
    //     end: string[],
    //     unknown: Record<string, boolean | number | string>,
    //     positional: string[]
    //   }
    //   // Parsed user-defined arguments
    //   args: {
    //     firstName: string
    //     lastName: string | undefined
    //     nickName: string | undefined
    //     age: number | undefined
    //     isDeveloper: boolean
    //   }
    // }
    //
    console.log(context)
  }
})

Run the script to see it in action:

$ tsx examples/simple John Doe -n John -a 26 -d

{
  argv: { end: [], unknown: {}, positional: [] },
  args: {
    nickName: 'John',
    age: 26,
    isDeveloper: true,
    firstName: 'John',
    lastName: 'Doe'
  }
}

By default, errors are captured, formatted, and printed to the console:

$ tsx examples/simple

Error: Missing required argument: first-name
  at parse (src/parser.ts:169:17)
  at matchCommand (src/command.ts:35:31)
  at runCommand (src/command.ts:114:28)

By default, --help or -h is used to show usage:

$ tsx examples/simple -h

simple v0.0.1 - simple description...

USAGE

  simple [options] <first-name> [last-name]

ARGUMENTS

  first-name          (required)        Your first name
  last-name                             Your last name

OPTIONS

  -n, --nick-name                       Your nick name
  -a, --age                             Your age
  -d, --is-developer  (default: false)  You are developer or not?

By default, --version or -v is used to show version:

$ tsx examples/simple -v
v0.0.1

You can control the above default behavior by passing configuration parameters.

If you want to disable:

runCommand(
  {
    ...
  },
  {
    handleError: false,
    handleUsage: false,
    handleVersion: false
  }
)

If you want to customize handling:

runCommand(
  {
    ...
  },
  {
    handleError: (error) => { ... },
    handleUsage: (command, { argv }) => { ... },
    handleVersion: (command, { argv }) => { ... }
  }
)

Examples

Utils

defineCommand

A type helper for defining commands.

matchCommand

Matches commands and return an array containing matched command objects and parsed command-line input arguments objects. The first element is the main-command, and the second element is the selected sub-command.

runCommand

Runs commands with auto generated usage/version help and graceful error handling by default.

showVersion

Generates version and prints to the console.

showUsage

Generates usage and prints to the console.

parse

Parses command-line input arguments and convert them into an easily usable data structure based on user-defined arguments specifications.

License

MIT License © 2023-PRESENT 13OnTheCode