minus-h/lib/index.d.ts

Add help generation to APIs created with Node's util.parseArgs function

import { LineWrap } from '@cto.af/linewrap';
import type { Writable } from 'node:stream';
import { parseArgs } from 'node:util';
type LineWrapOptions = ConstructorParameters<typeof LineWrap>[0];
/**
 * This is copied in from
 * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/e858f398c44ef759a64dd49854fd3470e6b65731/types/node/util.d.ts#L1254
 *
 * The original types there do not export enough of the intermediate types so
 * that the new properties can be grafted on more easily than this.
 */
export interface ParseArgsOptionConfig {
    /**
     * Type of argument.
     */
    type: 'boolean' | 'string';
    /**
     * Whether this option can be provided multiple times.
     * If `true`, all values will be collected in an array.
     * If `false`, values for the option are last-wins.
     * @default false.
     */
    multiple?: boolean | undefined;
    /**
     * A single character alias for the option.
     */
    short?: string | undefined;
    /**
     * The default option value when it is not set by args.
     * It must be of the same type as the the `type` property.
     * When `multiple` is `true`, it must be an array.
     * @since v18.11.0
     */
    default?: boolean[] | string[] | boolean | string | undefined;
    /**
     * Description of the argument, for generating help text.
     * @since minus-h
     */
    description?: string | undefined;
    /**
     * If the type is 'string, what should the argument be called in the
     * documentation?
     * @since minus-h
     */
    argumentName?: string | undefined;
    /**
     * If type is string, and choices is specified, the value must be one of
     * these choices.
     * @since minus-h
     */
    choices?: string[] | undefined;
}
/**
 * Copied here because ParseArgsOptionsConfig isn't public in utils.d.ts.
 */
export interface ParseArgsOptionsConfig {
    [longOption: string]: ParseArgsOptionConfig;
}
/**
 * The configuration for the arg parser, augmented with descriptions of
 * the arguments.
 */
export interface ParseArgsConfig {
    /**
     * Array of argument strings.
     */
    args?: string[] | undefined;
    /**
     * Used to describe arguments known to the parser.
     */
    options?: ParseArgsOptionsConfig | undefined;
    /**
     * Should an error be thrown when unknown arguments are encountered, or when
     * arguments are passed that do not match the `type` configured in
     * `options`.
     * @default true
     */
    strict?: boolean | undefined;
    /**
     * Whether this command accepts positional arguments.
     */
    allowPositionals?: boolean | undefined;
    /**
     * Return the parsed tokens. This is useful for extending the built-in
     * behavior, from adding additional checks through to reprocessing the
     * tokens in different ways.
     * @default false
     */
    tokens?: boolean | undefined;
    /**
     * Description of the script as a whole, for generating help text.
     * @since minus-h
     */
    description?: string | undefined;
    /**
     * If positiionals are allowed, what name should be used to refer to them in
     * the documentation?  Defaults to "arguments".
     *
     * @since minus-h
     */
    argumentName?: string | undefined;
    /**
     * Long description for the positional arguments.
     *
     * @since minus-h
     */
    argumentDescription?: string | undefined;
    /**
     * The name of the script.  Defaults to process.argv[1].
     *
     * @since minus-h
     */
    scriptName?: string | undefined;
    /**
     * Where to output help?  Useful for testing.  Defaults to stderr.
     */
    outputStream?: Writable;
    /**
     * What to do after writing help to outputStream.  Useful for testing.
     * Defaults to process.exit.  Called with 64 as the only parameter.
     */
    exit?: typeof process.exit;
}
/**
 * Parsed command line arguments.  Defined strangely here because
 * ParsedResults is not made public in util.d.ts.
 */
export type ParsedResults<T extends ParseArgsConfig> = ReturnType<typeof parseArgs<T>>;
export declare function usage(config?: ParseArgsConfig, options?: LineWrapOptions): void;
/**
 * Wrap `util.parseArgs()`, adding a "-h,--help" argument.  It takes one or
 * two arguments.  The wrapping width defaults to your terminal width (via
 * [process.stdout.columns](https://nodejs.org/api/tty.html#writestreamcolumns)).
 *
 * @param config An augmented version of the options passed to
 *   `util.parseArgs()`, with descriptions provided for options as well as the
 *   command as a whole.
 * @param options How to do line wrapping?
 * @returns The parsed results.
 */
export declare function parseArgsWithHelp<T extends ParseArgsConfig>(config?: T, options?: LineWrapOptions): ParsedResults<T>;
export {};