@rickosborne/clamp

Yet another command-line parameter handling tool.

Built on:

• @rickosborne/typical for types
• @rickosborne/guard for guards
• @rickosborne/foundation for basic data structures and algorithms
• @rickosborne/term for console/terminal tools.

Usage

Install via your favorite package manager.

Each package supports CommonJS require, ESM import, and TypeScript usage.

You also have a choice: barrel imports or direct imports.

Barrel imports mean you're going to require/import everything from the same package-level namespace:

// CommonJS
const { isPlainObject, isListOf } = require("@rickosborne/guard");
// ESM / TypeScript
import { isPlainObject, isListOf } from "@rickosborne/guard";

Implications:

• Nice and simple.
• Your build system needs to do tree-shaking well ... or you'll end up adding the entire package even if you only import two functions.

The other option is to use direct imports:

// CommonJS
const { isPlainObject } = require("@rickosborne/guard/is-object");
const { isListOf } = require("@rickosborne/guard/is-list-of");
// ESM / TypeScript
import { isPlainObject } from "@rickosborne/guard/is-object.js";
import { isListOf } from "@rickosborne/guard/is-list-of.js";

Implications:

• You (probably) don't have to worry about tree-shaking as your build (likely) ends up with only the functions you need.

If you're using a modern build system, there aren't any strong reasons to prefer one way over the other. It's really just down to your personal preference.

A quick note about file extensions

Do you need to use file extensions? And if so, which extensions?

Honestly ... this is a dumpster fire question. It really comes down to your own setup and configuration.

Within each package itself:

• The CommonJS files all have .cjs extensions.
• The ESM files all have .mjs extensions.
• Node subpath exports have been set up to send .js imports to the .cjs (via require) or .mjs (via import) files, depending on your setup.

So, in theory, the only extension which won't work would be .ts because the source isn't included.

If you run into a problem with a particular configuration, file a GitHub issue with:

• Your tsconfig.json's module, moduleResolution, and target settings.
• Your package.json's type and imports settings.
• An example of another package which imports correctly for you.

License

This package is licensed as CC-BY-NC-SA-4.0 unless otherwise noted. That is, Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

---

API

Functions

commandParams

commandParams: <Spec extends CommandParamsSpec>(spec: Spec, { args, ignoreUnknown, onError, }?: {
    args?: string[];
    ignoreUnknown?: boolean;
    onError?: (error: Error) => void;
}) => CommandParamsReturn<Spec>

Parse the (maybe-given) command-line arguments according to the given param specs and construct a return type of the converted values.

TypeAliases

BooleanCommandParam

type BooleanCommandParam = CommandParamBase & {
    falses?: string[];
    falseText?: string;
    parse?: (this: void, text: string, param: BooleanCommandParam) => boolean;
    placeholder?: undefined;
    trues?: string[];
    trueText?: string;
    type: typeof Boolean;
};

A command-line parameter which will be converted to a Boolean.

CommandParam

type CommandParam = StringCommandParam | NumberCommandParam | BooleanCommandParam | FileCommandParam | DateCommandParam;

One of the built-in param types.

CommandParamBase

type CommandParamBase = Either<CommandParamWithNames, PositionalCommandParam> & Partial<OptionalParam> & Partial<RepeatedParam> & DescribedParam;

Mixin for any type of command-line parameter.

CommandParamParser

type CommandParamParser<Param extends CommandParam, Return> = (text: string, param: Param) => Return;

A parser function for a specific type of param.

CommandParamReturn

type CommandParamReturn<Param extends CommandParam> = Param extends HasCommandParamParser<Param, infer Return> ? IfRepeated<Param, Return> : Param["type"] extends typeof Boolean ? IfOptional<Param, IfRepeated<Param, boolean>> : Param["type"] extends typeof Date ? IfOptional<Param, IfRepeated<Param, Date>> : Param["type"] extends typeof Number ? IfOptional<Param, IfRepeated<Param, number>> : Param["type"] extends "file" ? IfOptional<Param, IfRepeated<Param, FileArg>> : Param["type"] extends typeof String ? IfOptional<Param, IfRepeated<Param, string>> : undefined extends Param["type"] ? IfOptional<Param, IfRepeated<Param, string>> : never;

Computed return type for a param.

CommandParamsReturn

type CommandParamsReturn<Params extends object> = {
    [K in keyof Params]: Params[K] extends CommandParam ? CommandParamReturn<Params[K]> : never;
};

Computed return (Record) type for a Record of params.

DateCommandParam

type DateCommandParam = CommandParamBase & ParseLocalDateConfig & {
    maximum?: Date;
    minimum?: Date;
    parse?: (this: void, text: string, param: DateCommandParam) => Date;
    type: typeof Date;
};

Command-line parameter which can accept a date (and optionally time) value.

DescribedParam

type DescribedParam = {
    help?: string;
    placeholder?: string;
};

Mixin of properties which can be used to build --help text.

FileArg

type FileArg = {
    filePath: string;
    stats: Stats | undefined;
};

File argument resolved from a file command-line parameter.

FileCommandParam

type FileCommandParam = CommandParamBase & {
    existing?: boolean;
    parse?: (this: void, text: string, param: FileCommandParam) => FileArg;
    path?: string;
    type: "file";
};

A command-line parameter which references a file.

NumberCommandParam

type NumberCommandParam = CommandParamBase & {
    integer?: boolean;
    maximum?: number;
    minimum?: number;
    parse?: (this: void, text: string, param: NumberCommandParam) => number;
    radix?: number;
    type: typeof Number;
};

A parameter which should be converted into a number.

PositionalCommandParam

type PositionalCommandParam = {
    positional: true;
};

A parameter which accepts positional values.

StringCommandParam

type StringCommandParam = CommandParamBase & {
    parse?: (this: void, text: string, param: StringCommandParam) => string;
    trim?: boolean;
    type?: typeof String;
};

A parameter which accepts a text value.