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

peowly

v1.3.2

Published

meow inspired parseArgs() based CLI parser with help text helpers

Downloads

141,189

Readme

npm version npm downloads neostandard javascript style Module type: ESM Types in JS Follow @voxpelli@mastodon.social

meow inspired parseArgs() based CLI parser. Also contains help text helpers

Usage

Simple

const { flags } = peowly({
  options: {
    fix: {
      description: 'Fixes stuff',
      type: 'boolean',
    },
  },
});

Example

See example/basic.js

API

peowly()

peowly(options): { flags, input, remainderArgs, showHelp }

Meta Options

  • description - string | false - a description that will be prefixed to the help text (defaults to pkg.description, deactivated by false)
  • examples - see HelpMessageInfo
  • help - string - the help text to show on --help, preferably generated with formatHelpMessage() (defaults to being rendered with formatHelpMessage() using available data)
  • indent - see HelpMessageInfo
  • name - string - the name of the CLI command. Used by a couple of other defaults. (defaults to the first key in pkg.bin and else to pkg.name)
  • pkg - PackageJsonLike - a package.json which some meta data can be derived from
  • processTitle - string | false - sets the process.title to this (defaults to name, deactivated by false)
  • usage - see HelpMessageInfo
  • version - string - the version to show on --version (defaults to pkg.version)

Parser Options

  • args - string[] - same as for parseArgs() (defaults to process.argv with execPath and filename removed)
  • options - Flags - superset of that of parseArgs(). Every option / flag is expected to have a description string property in addition to what parseArgs() require and they may have a listGroup string property as well
  • returnRemainderArgs - boolean - if set, then all parts of args that doesn't match a flag in options will be returned as remainderArgs, which can eg. be forwarded to another parser

formatHelpMessage()

formatHelpMessage(name: string, info?: HelpMessageInfo): string

Arguments

  • name - string - the name of the CLI command

HelpMessageInfo

  • aliases - HelpListBasic - list of help items to join with commands but with group name defaulting to 'Aliases' and other group names being prefixed with ' Aliases'
  • commands - HelpListBasic - list of help items to add prior to the flags list and with a default group name of 'Commands'
  • examples - (string | { prefix?: string, suffix?: string })[] - will be added as examples on individual lines prefixed with $ ${name} or, if provided as prefix and suffix, then the prefix will go inbetween $ and the name and the suffix after that, separated by spaces
  • flags - HelpList - the flags to output in the help, compatible with Flags
  • indent - number - the number of spaces to indent the help text with (defaults to 2)
  • noDefaultFlags - boolean - excludes the default flags from the help text
  • usage - string - what, if anything, that follows the $ ${name} in 'Usage' headline in the initial help text

Types

import type { AnyFlag } from 'peowly';

interface HelpListBasicItem {
  listGroup?: string;
  description: string;
}

type HelpListItem = AnyFlag | HelpListBasicItem;

type HelpListBasic = Record<string, HelpListBasicItem>;

type HelpList = Record<string, HelpListItem | string>;

defaultFlags

Contains the definition of the two default flags --help and --version.

formatHelpList()

Most of the time you should use formatHelpMessage() instead.

function formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string

Arguments

  • list - HelpList - the list that represents the flags, see types in formatHelpMessage()
  • indent - number - how far to indent the list

HelpListOptions

  • fixedPadName - boolean - when set, padName will be treated as a fixed rather than minimum padding
  • keyPrefix - string - a prefix for the name
  • padName - number - the minimum padding between names and descriptions
  • shortFlagPrefix - string - a prefix for a shortFlag (defaults to '-')

formatFlagList()

function formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string

Same as formatHelpList() but with the keyPrefix option defaulting to '--'.

formatGroupedHelpList()

formatGroupedHelpList(list: HelpList, indent: number, options?: HelpListGroupOptions): string

Similar to formatHelpList() but prints help items grouped and has some additional options to support it in that.

HelpListGroupOptions

Same as HelpListOptions but with these additional options:

  • alignWithinGroups - boolean - when set (and unless fixedPadName is set) the padding between name and description will be calculated within each group instead of across all groups
  • defaultGroupName - string - the default group name where all items that have no explicit group belonging will be placed (defaults to 'Default')
  • defaultGroupOrderFirst - boolean - if set the default group is added at the start rather than at the end

formatGroupedFlagList()

formatGroupedFlagList(list: HelpList, indent: number, options?: HelpListGroupOptions): string

Same as formatGroupedHelpList() but with the keyPrefix option defaulting to '--' and defaultGroup defaulting to 'Options'.

Similar modules

  • argsclopts - also concerned with generating help texts for parseArgs()
  • meow - a more full fledged alternative and name inspiration (p as in parseArgs, eow as in meow, ly to avoid being perceived as a typejacking)
  • meow-with-subcommands - a companion module to meow that provides the same help functionality as this module
  • peowly-commands - a companion module to this module that makes it on par with meow-with-subcommands

See also

  • parseArgs() - the node.js API this module is built around. Available since v18.3.0 and v16.17.0, non-experimental since v20.0.0.