@wooksjs/event-cli/dist/index.d.ts

@wooksjs/event-cli

import * as wooks from 'wooks';
import { TWooksHandler, TWooksOptions, WooksAdapterBase, Wooks } from 'wooks';
import * as _prostojs_cli_help from '@prostojs/cli-help';
import { CliHelpRenderer, TCliHelpOptions, TCliEntry } from '@prostojs/cli-help';
import { TConsoleBase } from '@prostojs/logger';
import * as _wooksjs_event_core from '@wooksjs/event-core';
import { TEventOptions, TEmpty } from '@wooksjs/event-core';
import minimist from 'minimist';
import { TProstoRouterPathHandle } from '@prostojs/router';

interface TCliEventData {
    argv: string[];
    pathParams: string[];
    command: string;
    opts?: minimist.Opts;
    type: 'CLI';
    cliHelp: TCliHelpRenderer;
}
interface TCliContextStore {
    flags?: Record<string, boolean | string>;
}
interface TCliHelpCustom {
    handler: TWooksHandler<any>;
    /**
     * ### Callback for registered path
     *
     * @param path registered path
     * @param aliasType 0 - direct command, 1 - direct alias, 2 - computed alias
     */
    cb?: <T>(path: string, aliasType: number, route?: TProstoRouterPathHandle<T>) => void;
}
type TCliHelpRenderer = CliHelpRenderer<TCliHelpCustom>;

declare const cliShortcuts: {
    cli: string;
};
interface TWooksCliOptions {
    onError?: (e: Error) => void;
    onNotFound?: TWooksHandler;
    onUnknownCommand?: (params: string[], raiseError: () => void) => unknown;
    logger?: TConsoleBase;
    eventOptions?: TEventOptions;
    cliHelp?: TCliHelpRenderer | TCliHelpOptions;
    router?: TWooksOptions['router'];
}
interface TWooksCliEntry<T> extends Omit<TCliEntry<TWooksHandler<T>>, 'custom' | 'command'> {
    onRegister?: TCliHelpCustom['cb'];
    handler: TWooksHandler<T>;
}
declare class WooksCli extends WooksAdapterBase {
    protected opts?: TWooksCliOptions | undefined;
    protected logger: TConsoleBase;
    protected cliHelp: TCliHelpRenderer;
    constructor(opts?: TWooksCliOptions | undefined, wooks?: Wooks | WooksAdapterBase);
    /**
     * ### Register CLI Command
     * Command path segments may be separated by / or space.
     *
     * For example the folowing path are interpreted the same:
     * - "command test use:dev :name"
     * - "command/test/use:dev/:name"
     *
     * Where name will become an argument
     *
     * ```js
     * // example without options
     * app.cli('command/:arg', () => 'arg = ' + useRouteParams().params.arg )
     *
     * // example with options
     * app.cli('command/:arg', {
     *   description: 'Description of the command',
     *   options: [{ keys: ['project', 'p'], description: 'Description of the option', value: 'myProject' }],
     *   args: { arg: 'Description of the arg' },
     *   aliases: ['cmd'],  // alias "cmd/:arg" will be registered
     *   examples: [{
     *      description: 'Example of usage with someProject',
     *      cmd: 'argValue -p=someProject',
     *      // will result in help display:
     *      // "# Example of usage with someProject\n" +
     *      // "$ myCli command argValue -p=someProject\n"
     *   }],
     *   handler: () => 'arg = ' + useRouteParams().params.arg
     * })
     * ```
     *
     * @param path command path
     * @param _options handler or options
     *
     * @returns
     */
    cli<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, _options: TWooksCliEntry<ResType> | TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
    protected alreadyComputedAliases: boolean;
    protected computeAliases(): void;
    /**
     * ## run
     * ### Start command processing
     * Triggers command processing
     *
     * By default takes `process.argv.slice(2)` as a command
     *
     * It's possible to replace the command by passing an argument
     *
     * @param _argv optionally overwrite `process.argv.slice(2)` with your `argv` array
     */
    run(_argv?: string[], _opts?: minimist.Opts): Promise<unknown>;
    protected onError(e: Error): void;
    /**
     * Triggers `unknown command` processing and callbacks
     * @param pathParams `string[]` containing command
     */
    onUnknownCommand(pathParams: string[]): void;
    protected error(e: string | Error): void;
}
/**
 * Factory for WooksCli App
 * @param opts TWooksCliOptions
 * @param wooks Wooks | WooksAdapterBase
 * @returns WooksCli
 */
declare function createCliApp(opts?: TWooksCliOptions, wooks?: Wooks | WooksAdapterBase): WooksCli;

/**
 * ## useCliHelp
 * ### Composable
 * ```js
 * // example of printing cli instructions
 * const { print } = useCliHelp()
 * // print with colors
 * print(true)
 * // print with no colors
 * // print(false)
 * ```
 * @returns
 */
declare function useCliHelp(): {
    getCliHelp: () => TCliHelpRenderer;
    getEntry: () => _prostojs_cli_help.TCliEntry<TCliHelpCustom>;
    render: (width?: number, withColors?: boolean) => string[];
    print: (withColors?: boolean) => void;
};
/**
 * ## useAutoHelp
 * ### Composable
 *
 * Prints help if `--help` option provided.
 *
 * ```js
 *  // example of use: print help and exit
 *  app.cli('test', () => {
 *      useAutoHelp() && process.exit(0)
 *      return 'hit test command'
 *  })
 *
 *  // add option -h to print help, no colors
 *  app.cli('test/nocolors', () => {
 *      useAutoHelp(['help', 'h'], false) && process.exit(0)
 *      return 'hit test nocolors command'
 *  })
 * ```
 * @param keys default `['help']` - list of options to trigger help render
 * @param colors default `true`, prints with colors when true
 * @returns true when --help was provided. Otherwise returns false
 */
declare function useAutoHelp(keys?: string[], colors?: boolean): true | undefined;
/**
 * ##useCommandLookupHelp
 * ### Composable
 *
 * Tries to find valid command based on provided command.
 *
 * If manages to find a valid command, throws an error
 * suggesting a list of valid commands
 *
 * Best to use in `onUnknownCommand` callback:
 *
 * ```js
 *  const app = createCliApp({
 *      onUnknownCommand: (path, raiseError) => {
 *          // will throw an error suggesting a list
 *          // of valid commands if could find some
 *          useCommandLookupHelp()
 *          // fallback to a regular error handler
 *          raiseError()
 *      },
 *  })
 * ```
 *
 * @param lookupDepth depth of search in backwards
 * @example
 *
 * For provided command `run test:drive dir`
 *  - lookup1: `run test:drive dir`  (deep = 0)
 *  - lookup2: `run test:drive`      (deep = 1)
 *  - lookup3: `run test`            (deep = 2)
 *  - lookup4: `run`                 (deep = 3)
 * ...
 */
declare function useCommandLookupHelp(lookupDepth?: number): void;

/**
 * Get CLI Options
 *
 * @returns an object with CLI options
 */
declare function useCliOptions(): Record<string, string | boolean>;
/**
 * Getter for Cli Option value
 *
 * @param name name of the option
 * @returns value of a CLI option
 */
declare function useCliOption(name: string): string | boolean;

declare function createCliContext(data: Omit<TCliEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: any[]) => T) => T;
/**
 * Wrapper on top of useEventContext that provides
 * proper context types for CLI event
 * @returns set of hooks { getCtx, restoreCtx, clearCtx, hookStore, getStore, setStore }
 */
declare function useCliContext<T extends TEmpty>(): _wooksjs_event_core.TCtxHelpers<TCliContextStore & T & _wooksjs_event_core.TGenericContextStore<TCliEventData>>;

export { type TCliContextStore, type TCliEventData, type TCliHelpCustom, type TCliHelpRenderer, type TWooksCliEntry, type TWooksCliOptions, WooksCli, cliShortcuts, createCliApp, createCliContext, useAutoHelp, useCliContext, useCliHelp, useCliOption, useCliOptions, useCommandLookupHelp };