@clerc/core/dist/index.d.mts

Clerc core

import * as Parser from "@clerc/parser";
import { DOUBLE_DASH, FlagOptions, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, PARAMETER, ParsedResult, TypeFunction, TypeValue, UNKNOWN_FLAG } from "@clerc/parser";
import { CamelCase, DeepPrettify, LiteralUnion, MaybeArray, PartialRequired, Prettify, UnionToIntersection } from "@clerc/utils";

//#region ../advanced-types/src/errors.d.ts
declare class FlagValidationError extends Error {}
declare namespace index_d_exports {
  export { Enum, FlagValidationError, Range, Regex };
}
/**
* Creates a Enum type function that validates the input against allowed values.
* The display name will be formatted as "value1 | value2 | ..." for help
* output.
*
* @example
*
* ```typescript
* const format = Enum(["json", "yaml", "xml"]);
* // Help output will show: json | yaml | xml
* ```
*
* @param values - Array of allowed string values
* @returns A TypeFunction that validates and returns the input value
* @throws {Error} If the value is not in the allowed values list
*/
declare function Enum<T extends string>(...values: T[]): TypeFunction<T>;
/**
* Creates a range type function that validates the input is a number within the
* specified range.
*
* @param min - The minimum acceptable value (inclusive)
* @param max - The maximum acceptable value (inclusive)
* @returns A TypeFunction that validates the input value
* @throws {Error} If the value is not a number or is outside the specified
*   range
*/
declare function Range(min: number, max: number): TypeFunction<number>;
/**
* Creates a regex type function that validates the input against the provided
* pattern.
*
* @param pattern - The regular expression pattern to validate against
* @param description - Optional description for display purposes
* @returns A TypeFunction that validates the input value
* @throws {Error} If the value does not match the regex pattern
*/
declare function Regex(pattern: RegExp, description?: string): TypeFunction<string>;
//#endregion
//#region src/types/clerc.d.ts
type ErrorHandler = (error: unknown) => void;
//#endregion
//#region src/types/flag.d.ts
interface FlagCustomOptions {}
type ClercFlagOptions = FlagOptions & {
  description?: string;
} & FlagCustomOptions;
type ClercFlagDefinitionValue = ClercFlagOptions | TypeValue;
type ClercFlagsDefinition = Record<string, ClercFlagDefinitionValue>;
//#endregion
//#region src/types/parameter.d.ts
interface ParameterCustomOptions {}
type InferStringParameter<T extends string, Type = string> = T extends `<${infer Name extends string}...>` | `[${infer Name extends string}...]` ? Record<CamelCase<Name>, Type[]> : T extends `<${infer Name extends string}>` ? Record<CamelCase<Name>, Type> : T extends `[${infer Name extends string}]` ? Record<CamelCase<Name>, Type | undefined> : never;
type InferParameter<T extends ParameterDefinitionValue> = T extends string ? InferStringParameter<T> : T extends ParameterOptions ? T["type"] extends TypeFunction<infer U> ? InferStringParameter<T["key"], U> : InferStringParameter<T["key"]> : never;
type InferParameters<T extends readonly ParameterDefinitionValue[]> = T extends readonly (infer U extends ParameterDefinitionValue)[] ? Prettify<UnionToIntersection<InferParameter<U>>> : never;
type ParameterOptions = {
  key: string;
  description?: string;
  type?: TypeFunction;
} & ParameterCustomOptions;
type ParameterDefinitionValue = string | ParameterOptions;
//#endregion
//#region src/types/context.d.ts
type AddStringIndex<T> = T & Record<string, any>;
type KnownKeys<T> = string extends keyof T ? never : keyof T;
type InferFlagsWithGlobal<C extends Command, GF extends ClercFlagsDefinition> = AddStringIndex<InferFlags<NonNullable<C["flags"]> & Omit<GF, KnownKeys<NonNullable<C["flags"]>>>>>;
interface ContextStore {}
interface BaseContext<C extends Command = Command, GF extends ClercFlagsDefinition = {}> {
  command?: C;
  calledAs?: string;
  parameters: InferParameters<NonNullable<C["parameters"]>>;
  flags: InferFlagsWithGlobal<C, GF>;
  ignored: string[];
  rawParsed: ParsedResult<InferFlagsWithGlobal<C, GF>>;
  store: Partial<ContextStore>;
}
//#endregion
//#region src/types/command.d.ts
interface CommandCustomOptions {}
interface CommandOptions<Parameters extends readonly ParameterDefinitionValue[] = readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandCustomOptions {
  alias?: MaybeArray<string>;
  parameters?: Parameters;
  flags?: Flags;
  /**
  * A callback function to conditionally stop parsing. When it returns true,
  * parsing stops and remaining arguments are preserved in ignored.
  */
  ignore?: IgnoreFunction;
}
interface Command<Name$1 extends string = string, Parameters extends readonly ParameterDefinitionValue[] = readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandOptions<Parameters, Flags> {
  name: Name$1;
  description?: string;
}
type CommandWithHandler<Name$1 extends string = string, Parameters extends readonly ParameterDefinitionValue[] = readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> = Command<Name$1, Parameters, Flags> & {
  handler?: CommandHandler<Command<Name$1, Parameters, Flags>>;
};
type CommandsRecord = Record<string, Command>;
type CommandsMap = Map<string, Command>;
type MakeEmitterEvents<Commands extends CommandsRecord, GlobalFlags extends ClercFlagsDefinition = ClercFlagsDefinition> = { [K in keyof Commands]: [CommandHandlerContext<Commands[K], GlobalFlags>] };
type CommandHandlerContext<C extends Command = Command, GF extends ClercFlagsDefinition = ClercFlagsDefinition> = DeepPrettify<PartialRequired<BaseContext<C, GF>, "command" | "calledAs"> & {
  resolved: true;
}>;
type CommandHandler<C extends Command = Command, GF extends ClercFlagsDefinition = ClercFlagsDefinition> = (context: CommandHandlerContext<C, GF>) => void;
//#endregion
//#region src/types/interceptor.d.ts
type InterceptorContext<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = DeepPrettify<BaseContext<C, GF>>;
/**
* Function to call the next interceptor in the chain. **MUST** be awaited.
*/
type InterceptorNext = () => void | Promise<void>;
type InterceptorHandler<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = (context: InterceptorContext<C, GF>, next: InterceptorNext) => void | Promise<void>;
interface InterceptorObject<C extends Command = Command, GF extends ClercFlagsDefinition = {}> {
  enforce?: "pre" | "normal" | "post";
  handler: InterceptorHandler<C, GF>;
}
type Interceptor<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = InterceptorHandler<C, GF> | InterceptorObject<C, GF>;
//#endregion
//#region src/types/plugin.d.ts
interface Plugin {
  setup: (cli: Clerc) => void;
}
//#endregion
//#region src/cli.d.ts
interface CreateOptions {
  name?: string;
  scriptName?: string;
  description?: string;
  version?: string;
}
interface ParseOptions<Run extends boolean = true> {
  argv?: string[];
  run?: Run;
}
declare class Clerc<Commands extends CommandsRecord = {}, GlobalFlags extends ClercFlagsDefinition = {}> {
  #private;
  private constructor();
  get _name(): string;
  get _scriptName(): string;
  get _description(): string;
  get _version(): string;
  get _commands(): CommandsMap;
  get _globalFlags(): GlobalFlags;
  get store(): Partial<ContextStore>;
  static create(options?: CreateOptions): Clerc;
  name(name: string): this;
  scriptName(scriptName: string): this;
  description(description: string): this;
  version(version: string): this;
  use(plugin: Plugin): this;
  errorHandler(handler: ErrorHandler): this;
  command(commands: readonly CommandWithHandler<any, any, any>[]): this;
  command<Name$1 extends string, const Parameters extends readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition>(command: CommandWithHandler<Name$1, Parameters, Flags>): Clerc<Commands & Record<string, CommandWithHandler<Name$1, Parameters, Flags>>, GlobalFlags>;
  command<Name$1 extends string, const Parameters extends readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition>(name: Name$1 extends keyof Commands ? ["COMMAND ALREADY EXISTS"] : Name$1, options?: CommandOptions<Parameters, Flags>): Clerc<Commands & Record<Name$1, Command<Name$1, Parameters, Flags>>, GlobalFlags>;
  command<Name$1 extends string, const Parameters extends readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition>(name: Name$1 extends keyof Commands ? ["COMMAND ALREADY EXISTS"] : Name$1, description: string, options?: CommandOptions<Parameters, Flags>): Clerc<Commands & Record<Name$1, Command<Name$1, Parameters, Flags>>, GlobalFlags>;
  globalFlag<Name$1 extends string, Flag extends ClercFlagDefinitionValue>(name: Name$1, description: string, options: Flag): Clerc<Commands, GlobalFlags & Record<Name$1, Flag>>;
  globalFlag<Name$1 extends string, Flag extends ClercFlagDefinitionValue>(name: Name$1, options: Flag): Clerc<Commands, GlobalFlags & Record<Name$1, Flag>>;
  interceptor(interceptor: Interceptor<Command, GlobalFlags>): this;
  on<Name$1 extends LiteralUnion<keyof Commands, string>>(name: Name$1, handler: CommandHandler<Commands[Name$1], GlobalFlags>): this;
  run(): Promise<void>;
  parse<Run extends boolean = true>(argvOrOptions?: string[] | ParseOptions<Run>): Run extends true ? Promise<void> : this;
}
//#endregion
//#region src/command.d.ts
declare function resolveCommand(commandsMap: CommandsMap, parameters: string[]): [Command, string] | [undefined, undefined];
//#endregion
//#region src/errors.d.ts
declare class NoSuchCommandError extends Error {
  commandName: string;
  constructor(commandName: string, text?: string);
}
declare class NoCommandSpecifiedError extends Error {
  constructor(text?: string);
}
declare class InvalidCommandError extends Error {}
declare class MissingRequiredMetadataError extends Error {
  constructor(metadataName: string);
}
declare class InvalidParametersError extends Error {}
declare class MissingRequiredFlagError extends Error {
  constructor(flags: string[]);
}
//#endregion
//#region src/helpers.d.ts
declare const defineCommand: <Name$1 extends string, const Parameters extends readonly ParameterDefinitionValue[], Flags extends ClercFlagsDefinition>(command: Command<Name$1, Parameters, Flags>, handler?: NoInfer<CommandHandler<Command<Name$1, Parameters, Flags>>>) => CommandWithHandler<Name$1, Parameters, Flags>;
//#endregion
//#region src/ignore.d.ts
declare function createStopAtFirstParameter(): IgnoreFunction;
//#endregion
//#region src/parameter.d.ts
interface ParameterInfo {
  name: string;
  isRequired: boolean;
  isVariadic: boolean;
}
declare function extractParameterInfo(key: string): ParameterInfo;
//#endregion
//#region src/plugin.d.ts
declare const definePlugin: (plugin: Plugin) => Plugin;
//#endregion
//#region src/utils.d.ts
declare const normalizeFlagValue: (flag: ClercFlagDefinitionValue) => ClercFlagOptions;
declare const normalizeParameterValue: (parameter: ParameterDefinitionValue) => ParameterOptions;
//#endregion
export { BaseContext, Clerc, ClercFlagDefinitionValue, ClercFlagOptions, ClercFlagsDefinition, Command, CommandCustomOptions, CommandHandler, CommandHandlerContext, CommandOptions, CommandWithHandler, CommandsMap, CommandsRecord, ContextStore, type CreateOptions, DOUBLE_DASH, ErrorHandler, FlagCustomOptions, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, InvalidSchemaError, KNOWN_FLAG, MakeEmitterEvents, MissingRequiredFlagError, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, ParameterCustomOptions, ParameterDefinitionValue, ParameterOptions, type ParseOptions, type Parser, Plugin, index_d_exports as Types, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, extractParameterInfo, normalizeFlagValue, normalizeParameterValue, resolveCommand };