@clerc/core 0.44.0 → 1.0.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +266 -478
  2. package/dist/index.js +333 -810
  3. package/package.json +9 -16
package/dist/index.d.ts CHANGED
@@ -1,498 +1,286 @@
1
- import { Equals, Dict, CamelCase, MaybeArray as MaybeArray$1 } from '@clerc/utils';
2
- import { OmitIndexSignature, LiteralUnion, Simplify } from 'type-fest';
1
+ import { ErrorHandler as ErrorHandler$1 } from "lite-emit";
3
2
 
4
- declare const DOUBLE_DASH = "--";
5
- type TypeFunction<ReturnType = any> = (value: any) => ReturnType;
6
- type TypeFunctionArray<ReturnType> = readonly [TypeFunction<ReturnType>];
7
- type FlagType<ReturnType = any> = TypeFunction<ReturnType> | TypeFunctionArray<ReturnType>;
8
- type FlagSchemaBase<TF> = {
9
- /**
10
- * Type of the flag as a function that parses the argv string and returns the
11
- * parsed value.
12
- *
13
- * @example
14
- *
15
- * ```
16
- * type: String;
17
- * ```
18
- *
19
- * @example Wrap in an array to accept multiple values. `type: [Boolean]`
20
- *
21
- * @example Custom function type that uses moment.js to parse string as date.
22
- * `type: function CustomDate(value: string) { return moment(value).toDate();
23
- * }`
24
- */
25
- type: TF;
26
- /**
27
- * A single-character alias for the flag.
28
- *
29
- * @example
30
- *
31
- * ```
32
- * alias: "s";
33
- * ```
34
- */
35
- alias?: string;
36
- } & Record<PropertyKey, unknown>;
37
- type FlagSchemaDefault<TF, DefaultType = any> = FlagSchemaBase<TF> & {
38
- /**
39
- * Default value of the flag. Also accepts a function that returns the default
40
- * value. [Default: undefined]
41
- *
42
- * @example
43
- *
44
- * ```
45
- * default: 'hello'
46
- * ```
47
- *
48
- * @example
49
- *
50
- * ```
51
- * default: () => [1, 2, 3]
52
- * ```
53
- */
54
- default: DefaultType | (() => DefaultType);
55
- };
56
- type FlagSchema<TF = FlagType> = FlagSchemaBase<TF> | FlagSchemaDefault<TF>;
57
- type FlagTypeOrSchema<ExtraOptions = Record<string, unknown>> = FlagType | (FlagSchema & ExtraOptions);
58
- type Flags$1<ExtraOptions = Record<string, unknown>> = Record<string, FlagTypeOrSchema<ExtraOptions>>;
59
- 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;
60
- interface ParsedFlags<Schemas = Record<string, unknown>> {
61
- flags: Schemas;
62
- unknownFlags: Record<string, (string | boolean)[]>;
63
- _: string[] & {
64
- [DOUBLE_DASH]: string[];
65
- };
66
- }
67
- type TypeFlag<Schemas extends Flags$1> = ParsedFlags<{
68
- [flag in keyof Schemas]: InferFlagType<Schemas[flag]>;
69
- }>;
3
+ //#region ../parser/src/flag-types.d.ts
70
4
 
71
- type StripBrackets<Parameter extends string> = Parameter extends `<${infer ParameterName}>` | `[${infer ParameterName}]` ? ParameterName extends `${infer SpreadName}...` ? SpreadName : ParameterName : never;
72
- type ParameterType<Parameter extends string> = Parameter extends `<${infer _ParameterName}...>` | `[${infer _ParameterName}...]` ? string[] : Parameter extends `<${infer _ParameterName}>` ? string : Parameter extends `[${infer _ParameterName}]` ? string | undefined : never;
73
- type NonNullableParameters<T extends string[] | undefined> = T extends undefined ? [] : NonNullable<T>;
74
- type TransformParameters<C extends Command> = {
75
- [Parameter in NonNullableParameters<C["parameters"]>[number] as CamelCase<StripBrackets<Parameter>>]: ParameterType<Parameter>;
76
- };
77
- type MakeEventMap<T extends Commands> = {
78
- [K in keyof T]: [InterceptorContext];
79
- };
80
- type FallbackFlags<F extends Flags | undefined> = Equals<NonNullableFlag<F>["flags"], {}> extends true ? Dict<any> : NonNullableFlag<F>["flags"];
81
- type NonNullableFlag<F extends Flags | undefined> = TypeFlag<NonNullable<F>>;
82
- type ParseFlag<C extends Commands, N extends keyof C, GF extends GlobalFlagOptions = {}> = N extends keyof C ? OmitIndexSignature<NonNullableFlag<C[N]["flags"] & GF>["flags"]> : FallbackFlags<C[N]["flags"] & GF>["flags"];
83
- type ParseRaw<C extends Command, GF extends GlobalFlagOptions = {}> = NonNullableFlag<C["flags"] & GF> & {
84
- flags: FallbackFlags<C["flags"] & GF>;
85
- parameters: string[];
86
- mergedFlags: FallbackFlags<C["flags"] & GF> & NonNullableFlag<C["flags"] & GF>["unknownFlags"];
5
+ /**
6
+ * Creates a Choices type function that validates the input against allowed values.
7
+ * The display name will be formatted as "value1 | value2 | ..." for help output.
8
+ *
9
+ * @param values - Array of allowed string values
10
+ * @returns A FlagTypeFunction that validates and returns the input value
11
+ * @throws {Error} If the value is not in the allowed values list
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * const format = Choices(['json', 'yaml', 'xml']);
16
+ * // Help output will show: json | yaml | xml
17
+ * ```
18
+ */
19
+ declare function Choices<T extends string>(...values: T[]): FlagTypeFunction<T>;
20
+ //#endregion
21
+ //#region ../utils/src/types/type-fest.d.ts
22
+ type LiteralUnion<LiteralType, BaseType> = LiteralType | (BaseType & Record<never, never>);
23
+ type Prettify<T> = { [K in keyof T]: T[K] } & {};
24
+ type Primitive = null | undefined | string | number | boolean | symbol | bigint;
25
+ type BuiltIns = Primitive | void | Date | RegExp;
26
+ type NonRecursiveType = BuiltIns | Function | (new (...arguments_: any[]) => unknown) | Promise<unknown>;
27
+ type UnknownArray = readonly unknown[];
28
+ type MapsSetsOrArrays = ReadonlyMap<unknown, unknown> | WeakMap<WeakKey, unknown> | ReadonlySet<unknown> | WeakSet<WeakKey> | UnknownArray;
29
+ type ConditionalDeepPrettify<T, E = never, I$1 = unknown> = T extends E ? T : T extends I$1 ? { [TypeKey in keyof T]: ConditionalDeepPrettify<T[TypeKey], E, I$1> } : T;
30
+ type DeepPrettify<T, E = never> = ConditionalDeepPrettify<T, E | NonRecursiveType | MapsSetsOrArrays, object>;
31
+ type IsAny<T> = 0 extends 1 & T ? true : false;
32
+ //#endregion
33
+ //#region ../utils/src/types/index.d.ts
34
+ type MaybeArray<T> = T | T[];
35
+ type PartialRequired<T, K$1 extends keyof T> = T & { [P in K$1]-?: T[P] };
36
+ type UnionToIntersection<U$1> = (U$1 extends any ? (k: U$1) => void : never) extends ((k: infer I) => void) ? I : never;
37
+ type CamelCase<S extends string> = S extends `${infer Head} ${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
38
+ //#endregion
39
+ //#region ../parser/src/types.d.ts
40
+ type FlagDefaultValue<T = unknown> = T | (() => T);
41
+ /**
42
+ * Defines how a string input is converted to the target type T.
43
+ *
44
+ * @template T The target type.
45
+ */
46
+ type FlagTypeFunction<T = unknown> = ((value: string) => T) & {
47
+ /**
48
+ * Optional display name for the type, useful in help output.
49
+ * If provided, this will be shown instead of the function name.
50
+ */
51
+ displayName?: string;
87
52
  };
88
- type ParseParameters<C extends Commands = Commands, N extends keyof C = keyof C> = Equals<TransformParameters<C[N]>, {}> extends true ? N extends keyof C ? TransformParameters<C[N]> : Dict<string | string[] | undefined> : TransformParameters<C[N]>;
89
-
90
- type Locales = Dict<Dict<string>>;
91
- type TranslateFn = (name: string, ...args: string[]) => string | undefined;
92
- interface I18N {
93
- add: (locales: Locales) => void;
94
- t: TranslateFn;
95
- }
96
-
97
- interface Plugin<T extends Clerc = Clerc, U extends Clerc = Clerc> {
98
- setup: (cli: T) => U;
53
+ /**
54
+ * A callback function to conditionally stop parsing.
55
+ * When it returns true, parsing stops and remaining arguments are preserved in `ignored`.
56
+ *
57
+ * @param type - The type of the current argument: 'known-flag' or 'unknown-flag' for flags, 'parameter' for positional arguments
58
+ * @param arg - The current argument being processed
59
+ * @returns true to stop parsing, false to continue
60
+ */
61
+ type IgnoreFunction = (type: typeof KNOWN_FLAG | typeof UNKNOWN_FLAG | typeof PARAMETER, arg: string) => boolean;
62
+ type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
63
+ interface BaseFlagOptions<T extends FlagType = FlagType> {
64
+ /**
65
+ * The type constructor or a function to convert the string value.
66
+ * To support multiple occurrences of a flag (e.g., --file a --file b), wrap the type in an array: [String], [Number].
67
+ * e.g., String, Number, [String], (val) => val.split(',')
68
+ */
69
+ type: T;
70
+ /** Aliases for the flag. */
71
+ alias?: MaybeArray<string>;
72
+ /** The default value of the flag. */
73
+ default?: unknown;
99
74
  }
100
-
101
- type CommandType = RootType | string;
102
- type FlagOptions = FlagSchema & {
103
- description: string;
104
- };
105
- type Flag = FlagOptions & {
106
- name: string;
107
- };
108
- type GlobalFlagOption = FlagSchema;
109
- type Flags = Dict<FlagOptions>;
110
- type GlobalFlagOptions = Dict<GlobalFlagOption>;
111
- declare interface CommandCustomProperties {
75
+ type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
76
+ /**
77
+ * Whether to enable the `--no-<flag>` syntax to set the value to false.
78
+ * Only useful for boolean flags.
79
+ * When set on a non-boolean flag, a type error will be shown.
80
+ *
81
+ * @default true
82
+ */
83
+ negatable?: boolean;
84
+ }) | (BaseFlagOptions & {
85
+ negatable?: never;
86
+ });
87
+ type FlagDefinitionValue = FlagOptions | FlagType;
88
+ type FlagsDefinition = Record<string, FlagDefinitionValue>;
89
+ type RawInputType = string | boolean;
90
+ interface ObjectInputType {
91
+ [key: string]: RawInputType | ObjectInputType;
112
92
  }
113
- interface CommandOptions<P extends string[] = string[], A extends MaybeArray$1<string | RootType> = MaybeArray$1<string | RootType>, F extends Flags = Flags> extends CommandCustomProperties {
114
- alias?: A;
115
- parameters?: P;
116
- flags?: F;
93
+ /**
94
+ * The parsed result.
95
+ * @template TFlags The specific flags type inferred from ParserOptions.
96
+ */
97
+ interface ParsedResult<TFlags extends Record<string, any>> {
98
+ /** Positional arguments or commands. */
99
+ parameters: string[];
100
+ /** Arguments after the `--` delimiter. */
101
+ doubleDash: string[];
102
+ /**
103
+ * The parsed flags.
104
+ * This is a strongly-typed object whose structure is inferred from the `flags` configuration in ParserOptions.
105
+ */
106
+ flags: TFlags;
107
+ /** The raw command-line arguments. */
108
+ raw: string[];
109
+ /** Unknown flags encountered during parsing. */
110
+ unknown: Record<string, RawInputType>;
111
+ /** Arguments that were not parsed due to ignore callback. */
112
+ ignored: string[];
117
113
  }
118
- type Command<N extends string | RootType = string, O extends CommandOptions = CommandOptions> = O & {
119
- name: N;
120
- description: string;
121
- };
122
- type CommandAlias<N extends string | RootType = string, O extends CommandOptions = CommandOptions> = Command<N, O> & {
123
- __isAlias?: true;
124
- };
125
- type CommandWithHandler<N extends string | RootType = string, O extends CommandOptions = CommandOptions> = Command<N, O> & {
126
- handler?: HandlerInCommand<HandlerContext<Record<N, Command<N, O>> & Record<never, never>, N>>;
127
- };
128
- type Commands = Dict<Command> & {
129
- [Root]?: Command;
114
+ type InferFlagDefault<T extends FlagDefinitionValue, Fallback> = T extends {
115
+ default: FlagDefaultValue<infer DefaultType>;
116
+ } ? DefaultType : Fallback;
117
+ type IsTypeAny<T extends FlagDefinitionValue> = IsAny<T> extends true ? true : T extends {
118
+ type: infer Type;
119
+ } ? IsAny<Type> extends true ? true : false : false;
120
+ type _InferFlags<T extends FlagsDefinition> = { [K in keyof T]: IsTypeAny<T[K]> extends true ? any : T[K] extends readonly [BooleanConstructor] | {
121
+ type: readonly [BooleanConstructor];
122
+ } ? number : T[K] extends ObjectConstructor | {
123
+ type: ObjectConstructor;
124
+ } ? ObjectInputType : T[K] extends readonly [FlagType<infer U>] | {
125
+ type: readonly [FlagType<infer U>];
126
+ } ? U[] | InferFlagDefault<T[K], never> : T[K] extends FlagType<infer U> | {
127
+ type: FlagType<infer U>;
128
+ } ? U | InferFlagDefault<T[K], [U] extends [boolean] ? never : undefined> : never };
129
+ /**
130
+ * An advanced utility type that infers the exact type of the `flags` object in the parsed result,
131
+ * based on the provided `flags` configuration object T.
132
+ *
133
+ * @template T The type of the flags configuration object.
134
+ */
135
+ type InferFlags<T extends FlagsDefinition> = Prettify<_InferFlags<T>>;
136
+ //#endregion
137
+ //#region ../parser/src/iterator.d.ts
138
+ declare const KNOWN_FLAG = "known-flag";
139
+ declare const UNKNOWN_FLAG = "unknown-flag";
140
+ declare const PARAMETER = "parameter";
141
+ //#endregion
142
+ //#region ../parser/src/parse.d.ts
143
+ declare const DOUBLE_DASH = "--";
144
+ //#endregion
145
+ //#region src/types/clerc.d.ts
146
+ type ErrorHandler = (error: unknown) => void;
147
+ //#endregion
148
+ //#region src/types/flag.d.ts
149
+ interface FlagCustomOptions {}
150
+ type ClercFlagOptions = FlagOptions & FlagCustomOptions;
151
+ type ClercGlobalFlagDefinitionValue = ClercFlagOptions | FlagType;
152
+ type ClercFlagOptionsWithDescription = ClercFlagOptions & {
153
+ description: string;
130
154
  };
131
- interface ParseOptions {
132
- argv?: string[];
133
- run?: boolean;
155
+ type ClercFlagsDefinition = Record<string, ClercFlagOptionsWithDescription>;
156
+ //#endregion
157
+ //#region src/types/parameters.d.ts
158
+ type InferParameter<T extends string> = T extends `<${infer Name extends string}...>` | `[${infer Name extends string}...]` ? Record<CamelCase<Name>, string[]> : T extends `<${infer Name extends string}>` ? Record<CamelCase<Name>, string> : T extends `[${infer Name extends string}]` ? Record<CamelCase<Name>, string | undefined> : never;
159
+ type InferParameters<T extends readonly string[]> = T extends readonly (infer U extends string)[] ? Prettify<UnionToIntersection<InferParameter<U>>> : never;
160
+ //#endregion
161
+ //#region src/types/context.d.ts
162
+ type AddStringIndex<T> = T & Record<string, any>;
163
+ type InferFlagsWithGlobal<C extends Command, GF extends ClercFlagsDefinition> = AddStringIndex<InferFlags<NonNullable<C["flags"]> & Omit<GF, keyof NonNullable<C["flags"]>>>>;
164
+ interface BaseContext<C extends Command = Command, GF extends ClercFlagsDefinition = {}> {
165
+ resolved: boolean;
166
+ command?: C;
167
+ calledAs?: string;
168
+ parameters: InferParameters<NonNullable<C["parameters"]>>;
169
+ flags: InferFlagsWithGlobal<C, GF>;
170
+ ignored: string[];
171
+ rawParsed: ParsedResult<InferFlagsWithGlobal<C, GF>>;
172
+ missingParameters: boolean;
134
173
  }
135
- interface HandlerContext<C extends Commands = Commands, N extends keyof C = keyof C, GF extends GlobalFlagOptions = {}> {
136
- name?: LiteralUnion<N, string>;
137
- called?: string | RootType;
138
- resolved: boolean;
139
- hasRootOrAlias: boolean;
140
- hasRoot: boolean;
141
- raw: Simplify<ParseRaw<C[N], GF>>;
142
- parameters: Simplify<ParseParameters<C, N>>;
143
- unknownFlags: ParsedFlags["unknownFlags"];
144
- flags: Simplify<ParseFlag<C, N, GF> & Record<string, any>>;
145
- cli: Clerc<C, GF>;
174
+ //#endregion
175
+ //#region src/types/command.d.ts
176
+ interface CommandCustomOptions {}
177
+ interface CommandOptions<Parameters extends readonly string[] = readonly string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandCustomOptions {
178
+ alias?: MaybeArray<string>;
179
+ parameters?: Parameters;
180
+ flags?: Flags;
181
+ /**
182
+ * A callback function to conditionally stop parsing. When it returns true, parsing stops and remaining arguments are preserved in ignored.
183
+ */
184
+ ignore?: IgnoreFunction;
146
185
  }
147
- type Handler<C extends Commands = Commands, K extends keyof C = keyof C, GF extends GlobalFlagOptions = {}> = (ctx: HandlerContext<C, K, GF>) => void;
148
- type HandlerInCommand<C extends HandlerContext> = (ctx: {
149
- [K in keyof C]: C[K];
150
- }) => void;
151
- type FallbackType<T, U> = {} extends T ? U : T;
152
- /**
153
- * @deprecated This is a typo. Use `InterceptorContext` instead.
154
- */
155
- type InspectorContext<C extends Commands = Commands> = InterceptorContext<C>;
156
- /**
157
- * @deprecated This is a typo. Use `Interceptor` instead.
158
- */
159
- type Inspector<C extends Commands = Commands> = Interceptor<C>;
160
- /**
161
- * @deprecated This is a typo. Use `InspectorFn` instead.
162
- */
163
- type InspectorFn<C extends Commands = Commands> = InterceptorFn<C>;
164
- /**
165
- * @deprecated This is a typo. Use `InspectorObject` instead.
166
- */
167
- type InspectorObject<C extends Commands = Commands> = InterceptorObject<C>;
168
- type InterceptorContext<C extends Commands = Commands> = HandlerContext<C> & {
169
- flags: FallbackType<TypeFlag<NonNullable<C[keyof C]["flags"]>>["flags"], Dict<any>>;
170
- };
171
- type Interceptor<C extends Commands = Commands> = InterceptorFn<C> | InterceptorObject<C>;
172
- type InterceptorFn<C extends Commands = Commands> = (ctx: InterceptorContext<C>, next: () => void) => void;
173
- interface InterceptorObject<C extends Commands = Commands> {
174
- enforce?: "pre" | "post";
175
- fn: InterceptorFn<C>;
186
+ interface Command<Name$1 extends string = string, Parameters extends readonly string[] = readonly string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandOptions<Parameters, Flags> {
187
+ name: Name$1;
188
+ description: string;
176
189
  }
177
-
178
- declare const Root: unique symbol;
179
- type RootType = typeof Root;
180
- declare class Clerc<C extends Commands = {}, GF extends GlobalFlagOptions = {}> {
181
- #private;
182
- get i18n(): I18N;
183
- private constructor();
184
- get _name(): string;
185
- get _scriptName(): string;
186
- get _description(): string;
187
- get _version(): string;
188
- /**
189
- * @deprecated This is a typo. Use `_interceptor` instead.
190
- */
191
- get _inspectors(): Interceptor[];
192
- get _interceptors(): Interceptor[];
193
- get _commands(): C;
194
- get _flags(): GF;
195
- /**
196
- * Create a new cli
197
- *
198
- * @example
199
- *
200
- * ```ts
201
- * const cli = Clerc.create();
202
- * ```
203
- *
204
- * @param name
205
- * @param description
206
- * @param version
207
- * @returns
208
- */
209
- static create(name?: string, description?: string, version?: string): Clerc<{}, {}>;
210
- /**
211
- * Set the name of the cli
212
- *
213
- * @example
214
- *
215
- * ```ts
216
- * Clerc.create().name("test");
217
- * ```
218
- *
219
- * @param name
220
- * @returns
221
- */
222
- name(name: string): this;
223
- /**
224
- * Set the script name of the cli
225
- *
226
- * @example
227
- *
228
- * ```ts
229
- * Clerc.create().scriptName("test");
230
- * ```
231
- *
232
- * @param scriptName
233
- * @returns
234
- */
235
- scriptName(scriptName: string): this;
236
- /**
237
- * Set the description of the cli
238
- *
239
- * @example
240
- *
241
- * ```ts
242
- * Clerc.create().description("test cli");
243
- * ```
244
- *
245
- * @param description
246
- * @returns
247
- */
248
- description(description: string): this;
249
- /**
250
- * Set the version of the cli
251
- *
252
- * @example
253
- *
254
- * ```ts
255
- * Clerc.create().version("1.0.0");
256
- * ```
257
- *
258
- * @param version
259
- * @returns
260
- */
261
- version(version: string): this;
262
- /**
263
- * Set the Locale You must call this method once after you created the Clerc
264
- * instance.
265
- *
266
- * @example
267
- *
268
- * ```ts
269
- * Clerc.create()
270
- * .locale("en")
271
- * .command(...)
272
- * ```
273
- *
274
- * @param locale
275
- * @returns
276
- */
277
- locale(locale: string): this;
278
- /**
279
- * Set the fallback Locale You must call this method once after you created
280
- * the Clerc instance.
281
- *
282
- * @example
283
- *
284
- * ```ts
285
- * Clerc.create()
286
- * .fallbackLocale("en")
287
- * .command(...)
288
- * ```
289
- *
290
- * @param fallbackLocale
291
- * @returns
292
- */
293
- fallbackLocale(fallbackLocale: string): this;
294
- /**
295
- * Register a error handler
296
- *
297
- * @example
298
- *
299
- * ```ts
300
- * Clerc.create().errorHandler((err) => {
301
- * console.log(err);
302
- * });
303
- * ```
304
- *
305
- * @param handler
306
- * @returns
307
- */
308
- errorHandler(handler: (err: any) => void): this;
309
- /**
310
- * Register a command
311
- *
312
- * @example
313
- *
314
- * ```ts
315
- * Clerc.create().command("test", "test command", {
316
- * alias: "t",
317
- * flags: {
318
- * foo: {
319
- * alias: "f",
320
- * description: "foo flag",
321
- * },
322
- * },
323
- * });
324
- * ```
325
- *
326
- * @example
327
- *
328
- * ```ts
329
- * Clerc.create().command("", "root", {
330
- * flags: {
331
- * foo: {
332
- * alias: "f",
333
- * description: "foo flag",
334
- * },
335
- * },
336
- * });
337
- * ```
338
- *
339
- * @param name
340
- * @param description
341
- * @param options
342
- * @returns
343
- */
344
- command<C extends CommandWithHandler<any, any>[]>(c: [...C]): this;
345
- 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>;
346
- 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>;
347
- /**
348
- * Register a global flag
349
- *
350
- * @example
351
- *
352
- * ```ts
353
- * Clerc.create().flag("help", "help", {
354
- * alias: "h",
355
- * type: Boolean,
356
- * });
357
- * ```
358
- *
359
- * @param name
360
- * @param description
361
- * @param options
362
- * @returns
363
- */
364
- flag<N extends string, O extends GlobalFlagOption>(name: N, description: string, options: O): this & Clerc<C, GF & Record<N, O>>;
365
- /**
366
- * Register a handler
367
- *
368
- * @example
369
- *
370
- * ```ts
371
- * Clerc.create()
372
- * .command("test", "test command")
373
- * .on("test", (ctx) => {
374
- * console.log(ctx);
375
- * });
376
- * ```
377
- *
378
- * @param name
379
- * @param handler
380
- * @returns
381
- */
382
- on<K extends LiteralUnion<keyof CM, string | RootType>, CM extends this["_commands"] = this["_commands"]>(name: K, handler: Handler<CM, K, this["_flags"]>): this;
383
- /**
384
- * Use a plugin
385
- *
386
- * @example
387
- *
388
- * ```ts
389
- * Clerc.create().use(plugin);
390
- * ```
391
- *
392
- * @param plugin
393
- * @returns
394
- */
395
- use<T extends Clerc, U extends Clerc>(plugin: Plugin<T, U>): this & Clerc<C & U["_commands"]> & U;
396
- /**
397
- * @deprecated This is a typo. Use `intercetor()` instead.
398
- */
399
- inspector(interceptor: Interceptor): this;
400
- /**
401
- * Register a interceptor
402
- *
403
- * @example
404
- *
405
- * ```ts
406
- * Clerc.create().interceptor((ctx, next) => {
407
- * console.log(ctx);
408
- * next();
409
- * });
410
- * ```
411
- *
412
- * @param interceptor
413
- * @returns
414
- */
415
- interceptor(interceptor: Interceptor): this;
416
- /**
417
- * Parse the command line arguments
418
- *
419
- * @example
420
- *
421
- * ```ts
422
- * Clerc.create().parse(process.argv.slice(2)); // Optional
423
- * ```
424
- *
425
- * @param args
426
- * @param optionsOrArgv
427
- * @returns
428
- */
429
- parse(optionsOrArgv?: string[] | ParseOptions): this;
430
- /**
431
- * Run matched command
432
- *
433
- * @example
434
- *
435
- * ```ts
436
- * Clerc.create().parse({ run: false }).runMatchedCommand();
437
- * ```
438
- *
439
- * @returns
440
- */
441
- runMatchedCommand(): this;
190
+ type CommandWithHandler<Name$1 extends string = string, Parameters extends readonly string[] = readonly string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> = Command<Name$1, Parameters, Flags> & {
191
+ handler?: CommandHandler<Command<Name$1, Parameters, Flags>>;
192
+ };
193
+ type CommandsRecord = Record<string, Command>;
194
+ type CommandsMap = Map<string, Command>;
195
+ type MakeEmitterEvents<Commands extends CommandsRecord, GlobalFlags extends ClercFlagsDefinition = ClercFlagsDefinition> = { [K in keyof Commands]: [CommandHandlerContext<Commands[K], GlobalFlags>] };
196
+ type CommandHandlerContext<C extends Command = Command, GF extends ClercFlagsDefinition = ClercFlagsDefinition> = DeepPrettify<PartialRequired<BaseContext<C, GF>, "command" | "calledAs"> & {
197
+ resolved: true;
198
+ }>;
199
+ type CommandHandler<C extends Command = Command, GF extends ClercFlagsDefinition = ClercFlagsDefinition> = (context: CommandHandlerContext<C, GF>) => void;
200
+ //#endregion
201
+ //#region src/types/interceptor.d.ts
202
+ type InterceptorContext<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = DeepPrettify<BaseContext<C, GF>>;
203
+ /**
204
+ * Function to call the next interceptor in the chain.
205
+ * **MUST** be awaited.
206
+ */
207
+ type InterceptorNext = () => void | Promise<void>;
208
+ type InterceptorHandler<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = (context: InterceptorContext<C, GF>, next: InterceptorNext) => void | Promise<void>;
209
+ interface InterceptorObject<C extends Command = Command, GF extends ClercFlagsDefinition = {}> {
210
+ enforce?: "pre" | "normal" | "post";
211
+ handler: InterceptorHandler<C, GF>;
442
212
  }
443
-
444
- declare class CommandExistsError extends Error {
445
- commandName: string;
446
- constructor(commandName: string, t: TranslateFn);
213
+ type Interceptor<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = InterceptorHandler<C, GF> | InterceptorObject<C, GF>;
214
+ //#endregion
215
+ //#region src/types/plugin.d.ts
216
+ interface Plugin {
217
+ setup: (cli: Clerc) => void;
447
218
  }
448
- declare class NoSuchCommandError extends Error {
449
- commandName: string;
450
- constructor(commandName: string, t: TranslateFn);
219
+ //#endregion
220
+ //#region src/cli.d.ts
221
+ interface CreateOptions {
222
+ name?: string;
223
+ scriptName?: string;
224
+ description?: string;
225
+ version?: string;
451
226
  }
452
- declare class NoCommandGivenError extends Error {
453
- constructor(t: TranslateFn);
227
+ interface ParseOptions<Run extends boolean = true> {
228
+ argv?: string[];
229
+ run?: Run;
454
230
  }
455
- declare class CommandNameConflictError extends Error {
456
- n1: string;
457
- n2: string;
458
- constructor(n1: string, n2: string, t: TranslateFn);
231
+ declare class Clerc<Commands extends CommandsRecord = {}, GlobalFlags extends ClercFlagsDefinition = {}> {
232
+ #private;
233
+ private constructor();
234
+ get _name(): string;
235
+ get _scriptName(): string;
236
+ get _description(): string;
237
+ get _version(): string;
238
+ get _commands(): CommandsMap;
239
+ get _globalFlags(): GlobalFlags;
240
+ static create(options?: CreateOptions): Clerc;
241
+ name(name: string): this;
242
+ scriptName(scriptName: string): this;
243
+ description(description: string): this;
244
+ version(version: string): this;
245
+ use(plugin: Plugin): this;
246
+ errorHandler(handler: ErrorHandler$1): this;
247
+ command<Name$1 extends string, const Parameters extends readonly string[] = readonly [], Flags extends ClercFlagsDefinition = {}>(command: CommandWithHandler<Name$1, Parameters, Flags>): Clerc<Commands & Record<string, CommandWithHandler<Name$1, Parameters, Flags>>, GlobalFlags>;
248
+ command<Name$1 extends string, const Parameters extends readonly string[] = readonly [], 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>;
249
+ globalFlag<Name$1 extends string, Flag extends ClercGlobalFlagDefinitionValue>(name: Name$1, description: string, options: Flag): Clerc<Commands, GlobalFlags & Record<Name$1, Flag>>;
250
+ interceptor(interceptor: Interceptor<Command, GlobalFlags>): this;
251
+ on<Name$1 extends LiteralUnion<keyof Commands, string>>(name: Name$1, handler: CommandHandler<Commands[Name$1], GlobalFlags>): this;
252
+ run(): Promise<void>;
253
+ parse<Run extends boolean = true>(argvOrOptions?: string[] | ParseOptions<Run>): Run extends true ? Promise<void> : this;
459
254
  }
460
- declare class ScriptNameNotSetError extends Error {
461
- constructor(t: TranslateFn);
255
+ //#endregion
256
+ //#region src/commands.d.ts
257
+ declare function resolveCommand(commandsMap: CommandsMap, parameters: string[]): [Command, string] | [undefined, undefined];
258
+ //#endregion
259
+ //#region src/errors.d.ts
260
+ declare class NoSuchCommandError extends Error {
261
+ commandName: string;
262
+ constructor(commandName: string, text?: string);
462
263
  }
463
- declare class DescriptionNotSetError extends Error {
464
- constructor(t: TranslateFn);
264
+ declare class NoCommandSpecifiedError extends Error {
265
+ constructor(text?: string);
465
266
  }
466
- declare class VersionNotSetError extends Error {
467
- constructor(t: TranslateFn);
267
+ declare class InvalidCommandError extends Error {
268
+ constructor(message: string);
468
269
  }
469
- declare class InvalidCommandNameError extends Error {
470
- commandName: string;
471
- constructor(commandName: string, t: TranslateFn);
270
+ declare class MissingRequiredMetadataError extends Error {
271
+ constructor(metadataName: string);
472
272
  }
473
- declare class LocaleNotCalledFirstError extends Error {
474
- constructor(t: TranslateFn);
273
+ declare class InvalidParametersError extends Error {
274
+ constructor(message: string);
475
275
  }
476
-
477
- type MaybeArray<T> = T | T[];
478
-
479
- declare const definePlugin: <T extends Clerc<{}, {}>, U extends Clerc<{}, {}>>(p: Plugin<T, U>) => Plugin<T, U>;
480
- declare const defineHandler: <C extends Clerc<{}, {}>, K extends keyof C["_commands"]>(_cli: C, _key: K, handler: Handler<C["_commands"], K>) => Handler<C["_commands"], K>;
481
- declare const defineInterceptor: <C extends Clerc<{}, {}>>(_cli: C, interceptor: Interceptor<C["_commands"]>) => Interceptor<C["_commands"]>;
482
- /**
483
- * @deprecated This is a typo. Use `defineInterceptor` instead.
484
- */
485
- declare const defineInspector: <C extends Clerc<{}, {}>>(_cli: C, interceptor: Interceptor<C["_commands"]>) => Interceptor<C["_commands"]>;
486
- declare const defineCommand: <N extends string | typeof Root, O extends CommandOptions<[...P], MaybeArray<string | typeof Root>, Flags>, P extends string[]>(command: Command<N, O & CommandOptions<[...P], MaybeArray<string | typeof Root>, Flags>>, handler?: HandlerInCommand<HandlerContext<Record<N, Command<N, O>> & Record<never, never>, N, {}>> | undefined) => CommandWithHandler<N, O & CommandOptions<[...P], MaybeArray<string | typeof Root>, Flags>>;
487
-
488
- declare function resolveFlattenCommands(commands: Commands, t: TranslateFn): Map<string[] | typeof Root, CommandAlias>;
489
- declare function resolveCommand(commands: Commands, argv: string[], t: TranslateFn): [Command<string | RootType> | undefined, string[] | RootType | undefined];
490
- declare const resolveArgv: () => string[];
491
- declare function compose(interceptors: Interceptor[]): (ctx: InterceptorContext) => void;
492
- declare const isValidName: (name: CommandType) => boolean;
493
- declare const withBrackets: (s: string, isOptional?: boolean) => string;
494
- declare const formatCommandName: (name: string | string[] | RootType) => string;
495
- declare const detectLocale: () => string;
496
- declare const stripFlags: (argv: string[]) => string[];
497
-
498
- 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, Interceptor, InterceptorContext, InterceptorFn, InterceptorObject, InvalidCommandNameError, LocaleNotCalledFirstError, Locales, MakeEventMap, NoCommandGivenError, NoSuchCommandError, ParseOptions, Plugin, Root, RootType, ScriptNameNotSetError, TranslateFn, VersionNotSetError, compose, defineCommand, defineHandler, defineInspector, defineInterceptor, definePlugin, detectLocale, formatCommandName, isValidName, resolveArgv, resolveCommand, resolveFlattenCommands, stripFlags, withBrackets };
276
+ //#endregion
277
+ //#region src/helpers.d.ts
278
+ declare const defineCommand: <Name$1 extends string, const Parameters extends readonly string[] = readonly [], Flags extends ClercFlagsDefinition = {}>(command: Command<Name$1, Parameters, Flags>, handler?: NoInfer<CommandHandler<Command<Name$1, Parameters, Flags>>>) => CommandWithHandler<Name$1, Parameters, Flags>;
279
+ //#endregion
280
+ //#region src/ignore.d.ts
281
+ declare function createStopAtFirstParameter(): IgnoreFunction;
282
+ //#endregion
283
+ //#region src/plugin.d.ts
284
+ declare const definePlugin: (plugin: Plugin) => Plugin;
285
+ //#endregion
286
+ export { BaseContext, Choices, Clerc, ClercFlagOptions, ClercFlagOptionsWithDescription, ClercFlagsDefinition, ClercGlobalFlagDefinitionValue, Command, CommandCustomOptions, CommandHandler, CommandHandlerContext, CommandOptions, CommandWithHandler, CommandsMap, CommandsRecord, type CreateOptions, DOUBLE_DASH, ErrorHandler, FlagCustomOptions, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, KNOWN_FLAG, MakeEmitterEvents, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, type ParseOptions, Plugin, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, resolveCommand };