@clerc/core 0.39.0 → 0.41.0

package/dist/index.d.ts

@@ -1,232 +1,5 @@
-type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
-type Dict<T> = Record<string, T>;
-type MaybeArray$1<T> = T | T[];
-type AlphabetLowercase = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
-type Numeric = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
-type AlphaNumeric = AlphabetLowercase | Uppercase<AlphabetLowercase> | Numeric;
-type CamelCase<Word extends string> = Word extends `${infer FirstCharacter}${infer Rest}` ? (FirstCharacter extends AlphaNumeric ? `${FirstCharacter}${CamelCase<Rest>}` : Capitalize<CamelCase<Rest>>) : Word;
-
-/**
-Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
-
-@category Type
-*/
-type Primitive =
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| symbol
-	| bigint;
-
-declare global {
-	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
-	interface SymbolConstructor {
-		readonly observable: symbol;
-	}
-}
-
-/**
-Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
-
-@example
-```
-import type {Simplify} from 'type-fest';
-
-type PositionProps = {
-	top: number;
-	left: number;
-};
-
-type SizeProps = {
-	width: number;
-	height: number;
-};
-
-// In your editor, hovering over `Props` will show a flattened object with all the properties.
-type Props = Simplify<PositionProps & SizeProps>;
-```
-
-Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
-
-If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
-
-@example
-```
-import type {Simplify} from 'type-fest';
-
-interface SomeInterface {
-	foo: number;
-	bar?: string;
-	baz: number | undefined;
-}
-
-type SomeType = {
-	foo: number;
-	bar?: string;
-	baz: number | undefined;
-};
-
-const literal = {foo: 123, bar: 'hello', baz: 456};
-const someType: SomeType = literal;
-const someInterface: SomeInterface = literal;
-
-function fn(object: Record<string, unknown>): void {}
-
-fn(literal); // Good: literal object type is sealed
-fn(someType); // Good: type is sealed
-fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
-fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
-```
-
-@link https://github.com/microsoft/TypeScript/issues/15300
-
-@category Object
-*/
-type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
-
-/**
-Omit any index signatures from the given object type, leaving only explicitly defined properties.
-
-This is the counterpart of `PickIndexSignature`.
-
-Use-cases:
-- Remove overly permissive signatures from third-party types.
-
-This type was taken from this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
-
-It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.
-
-(The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)
-
-```
-const indexed: Record<string, unknown> = {}; // Allowed
-
-const keyed: Record<'foo', unknown> = {}; // Error
-// => TS2739: Type '{}' is missing the following properties from type 'Record<"foo" | "bar", unknown>': foo, bar
-```
-
-Instead of causing a type error like the above, you can also use a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) to test whether a type is assignable to another:
-
-```
-type Indexed = {} extends Record<string, unknown>
-	? '✅ `{}` is assignable to `Record<string, unknown>`'
-	: '❌ `{}` is NOT assignable to `Record<string, unknown>`';
-// => '✅ `{}` is assignable to `Record<string, unknown>`'
-
-type Keyed = {} extends Record<'foo' | 'bar', unknown>
-	? "✅ `{}` is assignable to `Record<'foo' | 'bar', unknown>`"
-	: "❌ `{}` is NOT assignable to `Record<'foo' | 'bar', unknown>`";
-// => "❌ `{}` is NOT assignable to `Record<'foo' | 'bar', unknown>`"
-```
-
-Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
-
-```
-import type {OmitIndexSignature} from 'type-fest';
-
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType // Map each key of `ObjectType`...
-	]: ObjectType[KeyType]; // ...to its original value, i.e. `OmitIndexSignature<Foo> == Foo`.
-};
-```
-
-...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
-
-```
-import type {OmitIndexSignature} from 'type-fest';
-
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType
-		// Is `{}` assignable to `Record<KeyType, unknown>`?
-		as {} extends Record<KeyType, unknown>
-			? ... // ✅ `{}` is assignable to `Record<KeyType, unknown>`
-			: ... // ❌ `{}` is NOT assignable to `Record<KeyType, unknown>`
-	]: ObjectType[KeyType];
-};
-```
-
-If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
-
-```
-import type {OmitIndexSignature} from 'type-fest';
-
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType
-		as {} extends Record<KeyType, unknown>
-			? never // => Remove this `KeyType`.
-			: KeyType // => Keep this `KeyType` as it is.
-	]: ObjectType[KeyType];
-};
-```
-
-@example
-```
-import type {OmitIndexSignature} from 'type-fest';
-
-interface Example {
-	// These index signatures will be removed.
-	[x: string]: any
-	[x: number]: any
-	[x: symbol]: any
-	[x: `head-${string}`]: string
-	[x: `${string}-tail`]: string
-	[x: `head-${string}-tail`]: string
-	[x: `${bigint}`]: string
-	[x: `embedded-${number}`]: string
-
-	// These explicitly defined keys will remain.
-	foo: 'bar';
-	qux?: 'baz';
-}
-
-type ExampleWithoutIndexSignatures = OmitIndexSignature<Example>;
-// => { foo: 'bar'; qux?: 'baz' | undefined; }
-```
-
-@see PickIndexSignature
-@category Object
-*/
-type OmitIndexSignature<ObjectType> = {
-	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
-		? never
-		: KeyType]: ObjectType[KeyType];
-};
-
-/**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
-
-Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
-
-This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
-
-@example
-```
-import type {LiteralUnion} from 'type-fest';
-
-// Before
-
-type Pet = 'dog' | 'cat' | string;
-
-const pet: Pet = '';
-// Start typing in your TypeScript-enabled IDE.
-// You **will not** get auto-completion for `dog` and `cat` literals.
-
-// After
-
-type Pet2 = LiteralUnion<'dog' | 'cat', string>;
-
-const pet: Pet2 = '';
-// You **will** get auto-completion for `dog` and `cat` literals.
-```
-
-@category Type
-*/
-type LiteralUnion<
-	LiteralType,
-	BaseType extends Primitive,
-> = LiteralType | (BaseType & Record<never, never>);
+import { Equals, Dict, CamelCase, MaybeArray as MaybeArray$1 } from '@clerc/utils';
+import { OmitIndexSignature, LiteralUnion, Simplify } from 'type-fest';
 
 declare const DOUBLE_DASH = "--";
 type TypeFunction<ReturnType = any> = (value: any) => ReturnType;
@@ -234,54 +7,60 @@ type TypeFunctionArray<ReturnType> = readonly [TypeFunction<ReturnType>];
 type FlagType<ReturnType = any> = TypeFunction<ReturnType> | TypeFunctionArray<ReturnType>;
 type FlagSchemaBase<TF> = {
     /**
-      Type of the flag as a function that parses the argv string and returns the parsed value.
-  
-      @example
-      ```
-      type: String
-      ```
-      @example Wrap in an array to accept multiple values.
-      ```
-      type: [Boolean]
-      ```
-      @example Custom function type that uses moment.js to parse string as date.
-      ```
-      type: function CustomDate(value: string) {
-          return moment(value).toDate();
-      }
-      ```
+     * Type of the flag as a function that parses the argv string and returns the
+     * parsed value.
+     *
+     * @example
+     *
+     * ```
+     *     type: String
+     *     ```
+     * ```
+     *
+     * @example Wrap in an array to accept multiple values. `type: [Boolean]`
+     *
+     * @example Custom function type that uses moment.js to parse string as date.
+     * `type: function CustomDate(value: string) { return moment(value).toDate();
+     * }`
      */
     type: TF;
     /**
-      A single-character alias for the flag.
-  
-      @example
-      ```
-      alias: 's'
-      ```
+     * A single-character alias for the flag.
+     *
+     * @example
+     *
+     * ```
+     *     alias: 's'
+     *     ```
+     * ```
      */
     alias?: string;
 } & Record<PropertyKey, unknown>;
 type FlagSchemaDefault<TF, DefaultType = any> = FlagSchemaBase<TF> & {
     /**
-      Default value of the flag. Also accepts a function that returns the default value.
-      [Default: undefined]
-  
-      @example
-      ```
-      default: 'hello'
-      ```
-      @example
-      ```
-      default: () => [1, 2, 3]
-      ```
+     * Default value of the flag. Also accepts a function that returns the default
+     * value. [Default: undefined]
+     *
+     * @example
+     *
+     * ```
+     *     default: 'hello'
+     *     ```
+     * ```
+     *
+     * @example
+     *
+     * ```
+     *     default: () => [1, 2, 3]
+     *     ```
+     * ```
      */
     default: DefaultType | (() => DefaultType);
 };
 type FlagSchema<TF = FlagType> = FlagSchemaBase<TF> | FlagSchemaDefault<TF>;
 type FlagTypeOrSchema<ExtraOptions = Record<string, unknown>> = FlagType | (FlagSchema & ExtraOptions);
 type Flags$1<ExtraOptions = Record<string, unknown>> = Record<string, FlagTypeOrSchema<ExtraOptions>>;
-type InferFlagType<Flag extends FlagTypeOrSchema> = Flag extends (TypeFunctionArray<infer T> | FlagSchema<TypeFunctionArray<infer T>>) ? (Flag extends FlagSchemaDefault<TypeFunctionArray<T>, infer D> ? T[] | D : T[]) : (Flag extends TypeFunction<infer T> | FlagSchema<TypeFunction<infer T>> ? (Flag extends FlagSchemaDefault<TypeFunction<T>, infer D> ? T | D : T | undefined) : never);
+type InferFlagType<Flag extends FlagTypeOrSchema> = Flag extends TypeFunctionArray<infer T> | FlagSchema<TypeFunctionArray<infer T>> ? Flag extends FlagSchemaDefault<TypeFunctionArray<T>, infer D> ? T[] | D : T[] : Flag extends TypeFunction<infer T> | FlagSchema<TypeFunction<infer T>> ? Flag extends FlagSchemaDefault<TypeFunction<T>, infer D> ? T | D : T | undefined : never;
 interface ParsedFlags<Schemas = Record<string, unknown>> {
     flags: Schemas;
     unknownFlags: Record<string, (string | boolean)[]>;
@@ -293,7 +72,7 @@ type TypeFlag<Schemas extends Flags$1> = ParsedFlags<{
     [flag in keyof Schemas]: InferFlagType<Schemas[flag]>;
 }>;
 
-type StripBrackets<Parameter extends string> = Parameter extends `<${infer ParameterName}>` | `[${infer ParameterName}]` ? (ParameterName extends `${infer SpreadName}...` ? SpreadName : ParameterName) : never;
+type StripBrackets<Parameter extends string> = Parameter extends `<${infer ParameterName}>` | `[${infer ParameterName}]` ? ParameterName extends `${infer SpreadName}...` ? SpreadName : ParameterName : never;
 type ParameterType<Parameter extends string> = Parameter extends `<${infer _ParameterName}...>` | `[${infer _ParameterName}...]` ? string[] : Parameter extends `<${infer _ParameterName}>` ? string : Parameter extends `[${infer _ParameterName}]` ? string | undefined : never;
 type NonNullableParameters<T extends string[] | undefined> = T extends undefined ? [] : NonNullable<T>;
 type TransformParameters<C extends Command> = {
@@ -391,6 +170,7 @@ declare class Clerc<C extends Commands = {}, GF extends GlobalFlagOptions = {}>
     i18n: I18N;
     private constructor();
     get _name(): string;
+    get _scriptName(): string;
     get _description(): string;
     get _version(): string;
     get _inspectors(): Inspector[];
@@ -399,210 +179,243 @@ declare class Clerc<C extends Commands = {}, GF extends GlobalFlagOptions = {}>
     /**
      * Create a new cli
      *
+     * @example
+     *
+     * ```ts
+     * const cli = Clerc.create();
+     * ```
+     *
      * @param name
      * @param description
      * @param version
      * @returns
-     * @example
-     * ```ts
-     * const cli = Clerc.create()
-     * ```
      */
     static create(name?: string, description?: string, version?: string): Clerc<{}, {}>;
     /**
      * Set the name of the cli
      *
+     * @example
+     *
+     * ```ts
+     * Clerc.create().name("test");
+     * ```
+     *
      * @param name
      * @returns
+     */
+    name(name: string): this;
+    /**
+     * Set the script name of the cli
+     *
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .name("test")
+     * Clerc.create().scriptName("test");
      * ```
+     *
+     * @param scriptName
+     * @returns
      */
-    name(name: string): this;
+    scriptName(scriptName: string): this;
     /**
      * Set the description of the cli
      *
-     * @param description
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .description("test cli")
+     * Clerc.create().description("test cli");
      * ```
+     *
+     * @param description
+     * @returns
      */
     description(description: string): this;
     /**
      * Set the version of the cli
      *
-     * @param version
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .version("1.0.0")
+     * Clerc.create().version("1.0.0");
      * ```
+     *
+     * @param version
+     * @returns
      */
     version(version: string): this;
     /**
-     * Set the Locale
-     * You must call this method once after you created the Clerc instance.
+     * Set the Locale You must call this method once after you created the Clerc
+     * instance.
      *
-     * @param locale
-     * @returns
      * @example
+     *
      * ```ts
      * Clerc.create()
      *   .locale("en")
      *   .command(...)
      * ```
+     *
+     * @param locale
+     * @returns
      */
     locale(locale: string): this;
     /**
-     * Set the fallback Locale
-     * You must call this method once after you created the Clerc instance.
+     * Set the fallback Locale You must call this method once after you created
+     * the Clerc instance.
      *
-     * @param fallbackLocale
-     * @returns
      * @example
+     *
      * ```ts
      * Clerc.create()
      *   .fallbackLocale("en")
      *   .command(...)
      * ```
+     *
+     * @param fallbackLocale
+     * @returns
      */
     fallbackLocale(fallbackLocale: string): this;
     /**
      * Register a error handler
      *
-     * @param handler
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .errorHandler((err) => { console.log(err); })
+     * Clerc.create().errorHandler((err) => {
+     *   console.log(err);
+     * });
      * ```
+     *
+     * @param handler
+     * @returns
      */
     errorHandler(handler: (err: any) => void): this;
     /**
      * Register a command
      *
-     * @param name
-     * @param description
-     * @param options
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .command("test", "test command", {
-     *     alias: "t",
-     *     flags: {
-     *       foo: {
-     *         alias: "f",
-     *         description: "foo flag",
-     *       }
-     *     }
-     *   })
+     * Clerc.create().command("test", "test command", {
+     *   alias: "t",
+     *   flags: {
+     *     foo: {
+     *       alias: "f",
+     *       description: "foo flag",
+     *     },
+     *   },
+     * });
      * ```
+     *
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .command("", "root", {
-     *     flags: {
-     *       foo: {
-     *         alias: "f",
-     *         description: "foo flag",
-     *       }
-     *     }
-     *   })
+     * Clerc.create().command("", "root", {
+     *   flags: {
+     *     foo: {
+     *       alias: "f",
+     *       description: "foo flag",
+     *     },
+     *   },
+     * });
      * ```
+     *
+     * @param name
+     * @param description
+     * @param options
+     * @returns
      */
     command<N extends string | RootType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray$1<string | RootType> = MaybeArray$1<string | RootType>, F extends Flags = Flags>(c: CommandWithHandler<N, O & CommandOptions<[...P], A, F>>): this & Clerc<C & Record<N, Command<N, O>>, GF>;
     command<N extends string | RootType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray$1<string | RootType> = MaybeArray$1<string | RootType>, F extends Flags = Flags>(name: N, description: string, options?: O & CommandOptions<[...P], A, F>): this & Clerc<C & Record<N, Command<N, O>>, GF>;
     /**
      * Register a global flag
      *
+     * @example
+     *
+     * ```ts
+     * Clerc.create().flag("help", "help", {
+     *   alias: "h",
+     *   type: Boolean,
+     * });
+     * ```
+     *
      * @param name
      * @param description
      * @param options
      * @returns
-     * @example
-     * ```ts
-     * Clerc.create()
-     *   .flag("help", "help", {
-     *     alias: "h",
-     *     type: Boolean,
-     *   })
-     * ```
      */
     flag<N extends string, O extends GlobalFlagOption>(name: N, description: string, options: O): this & Clerc<C, GF & Record<N, O>>;
     /**
      * Register a handler
      *
-     * @param name
-     * @param handler
-     * @returns
      * @example
+     *
      * ```ts
      * Clerc.create()
      *   .command("test", "test command")
      *   .on("test", (ctx) => {
      *     console.log(ctx);
-     *   })
+     *   });
      * ```
+     *
+     * @param name
+     * @param handler
+     * @returns
      */
     on<K extends LiteralUnion<keyof CM, string | RootType>, CM extends this["_commands"] = this["_commands"]>(name: K, handler: Handler<CM, K, this["_flags"]>): this;
     /**
      * Use a plugin
      *
-     * @param plugin
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .use(plugin)
+     * Clerc.create().use(plugin);
      * ```
+     *
+     * @param plugin
+     * @returns
      */
     use<T extends Clerc, U extends Clerc>(plugin: Plugin<T, U>): this & Clerc<C & U["_commands"]> & U;
     /**
      * Register a inspector
      *
-     * @param inspector
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .inspector((ctx, next) => {
-     *     console.log(ctx);
-     *     next();
-     *   })
+     * Clerc.create().inspector((ctx, next) => {
+     *   console.log(ctx);
+     *   next();
+     * });
      * ```
+     *
+     * @param inspector
+     * @returns
      */
     inspector(inspector: Inspector): this;
     /**
      * Parse the command line arguments
      *
-     * @param args
-     * @param optionsOrArgv
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .parse(process.argv.slice(2)) // Optional
+     * Clerc.create().parse(process.argv.slice(2)); // Optional
      * ```
+     *
+     * @param args
+     * @param optionsOrArgv
+     * @returns
      */
     parse(optionsOrArgv?: string[] | ParseOptions): this;
     /**
      * Run matched command
      *
-     * @returns
      * @example
+     *
      * ```ts
-     * Clerc.create()
-     *   .parse({ run: false })
-     *   .runMatchedCommand()
+     * Clerc.create().parse({ run: false }).runMatchedCommand();
      * ```
+     *
+     * @returns
      */
     runMatchedCommand(): this;
 }
@@ -623,7 +436,7 @@ declare class CommandNameConflictError extends Error {
     n2: string;
     constructor(n1: string, n2: string, t: TranslateFn);
 }
-declare class NameNotSetError extends Error {
+declare class ScriptNameNotSetError extends Error {
     constructor(t: TranslateFn);
 }
 declare class DescriptionNotSetError extends Error {
@@ -657,4 +470,4 @@ declare const formatCommandName: (name: string | string[] | RootType) => string;
 declare const detectLocale: () => string;
 declare const stripFlags: (argv: string[]) => string[];
 
-export { Clerc, Command, CommandAlias, CommandCustomProperties, CommandExistsError, CommandNameConflictError, CommandOptions, CommandType, CommandWithHandler, Commands, DescriptionNotSetError, FallbackType, Flag, FlagOptions, Flags, GlobalFlagOption, GlobalFlagOptions, Handler, HandlerContext, HandlerInCommand, I18N, Inspector, InspectorContext, InspectorFn, InspectorObject, InvalidCommandNameError, LocaleNotCalledFirstError, Locales, MakeEventMap, NameNotSetError, NoCommandGivenError, NoSuchCommandError, ParseOptions, Plugin, Root, RootType, TranslateFn, VersionNotSetError, compose, defineCommand, defineHandler, defineInspector, definePlugin, detectLocale, formatCommandName, isValidName, resolveArgv, resolveCommand, resolveFlattenCommands, stripFlags, withBrackets };
+export { Clerc, Command, CommandAlias, CommandCustomProperties, CommandExistsError, CommandNameConflictError, CommandOptions, CommandType, CommandWithHandler, Commands, DescriptionNotSetError, FallbackType, Flag, FlagOptions, Flags, GlobalFlagOption, GlobalFlagOptions, Handler, HandlerContext, HandlerInCommand, I18N, Inspector, InspectorContext, InspectorFn, InspectorObject, InvalidCommandNameError, LocaleNotCalledFirstError, Locales, MakeEventMap, NoCommandGivenError, NoSuchCommandError, ParseOptions, Plugin, Root, RootType, ScriptNameNotSetError, TranslateFn, VersionNotSetError, compose, defineCommand, defineHandler, defineInspector, definePlugin, detectLocale, formatCommandName, isValidName, resolveArgv, resolveCommand, resolveFlattenCommands, stripFlags, withBrackets };