@clerc/core 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/index.d.ts

@@ -1,5 +1,23 @@
 import { ErrorHandler as ErrorHandler$1 } from "lite-emit";
 
+//#region ../parser/src/flag-types.d.ts
+
+/**
+* Creates a Choices type function that validates the input against allowed values.
+* The display name will be formatted as "value1 | value2 | ..." for help output.
+*
+* @param values - Array of allowed string values
+* @returns A FlagTypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
+*
+* @example
+* ```typescript
+* const format = Choices(['json', 'yaml', 'xml']);
+* // Help output will show: json | yaml | xml
+* ```
+*/
+declare function Choices<T extends string>(...values: T[]): FlagTypeFunction<T>;
+//#endregion
 //#region ../utils/src/types/type-fest.d.ts
 type LiteralUnion<LiteralType, BaseType> = LiteralType | (BaseType & Record<never, never>);
 type Prettify<T> = { [K in keyof T]: T[K] } & {};
@@ -25,7 +43,13 @@ type FlagDefaultValue<T = unknown> = T | (() => T);
 *
 * @template T The target type.
 */
-type FlagTypeFunction<T = unknown> = (value: string) => T;
+type FlagTypeFunction<T = unknown> = ((value: string) => T) & {
+  /**
+  * Optional display name for the type, useful in help output.
+  * If provided, this will be shown instead of the function name.
+  */
+  displayName?: string;
+};
 /**
 * A callback function to conditionally stop parsing.
 * When it returns true, parsing stops and remaining arguments are preserved in `ignored`.
@@ -122,10 +146,13 @@ declare const DOUBLE_DASH = "--";
 type ErrorHandler = (error: unknown) => void;
 //#endregion
 //#region src/types/flag.d.ts
-type ClercFlagOptions = FlagOptions & {
+interface FlagCustomOptions {}
+type ClercFlagOptions = FlagOptions & FlagCustomOptions;
+type ClercGlobalFlagDefinitionValue = ClercFlagOptions | FlagType;
+type ClercFlagOptionsWithDescription = ClercFlagOptions & {
   description: string;
 };
-type ClercFlagsDefinition = Record<string, ClercFlagOptions>;
+type ClercFlagsDefinition = Record<string, ClercFlagOptionsWithDescription>;
 //#endregion
 //#region src/types/parameters.d.ts
 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;
@@ -197,9 +224,9 @@ interface CreateOptions {
   description?: string;
   version?: string;
 }
-interface ParseOptions {
+interface ParseOptions<Run extends boolean = true> {
   argv?: string[];
-  run?: boolean;
+  run?: Run;
 }
 declare class Clerc<Commands extends CommandsRecord = {}, GlobalFlags extends ClercFlagsDefinition = {}> {
   #private;
@@ -219,11 +246,11 @@ declare class Clerc<Commands extends CommandsRecord = {}, GlobalFlags extends Cl
   errorHandler(handler: ErrorHandler$1): this;
   command<Name$1 extends string, Parameters extends string[] = [], Flags extends ClercFlagsDefinition = {}>(command: CommandWithHandler<Name$1, [...Parameters], Flags>): Clerc<Commands & Record<string, CommandWithHandler<Name$1, Parameters, Flags>>, GlobalFlags>;
   command<Name$1 extends string, Parameters extends string[] = [], 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 FlagDefinitionValue>(name: Name$1, description: string, options: Flag): Clerc<Commands, GlobalFlags & Record<Name$1, Flag>>;
+  globalFlag<Name$1 extends string, Flag extends ClercGlobalFlagDefinitionValue>(name: Name$1, description: string, 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(): void;
-  parse(argvOrOptions?: string[] | ParseOptions): this;
+  run(): Promise<void>;
+  parse<Run extends boolean = true>(argvOrOptions?: string[] | ParseOptions<Run>): Run extends true ? Promise<void> : this;
 }
 //#endregion
 //#region src/commands.d.ts
@@ -256,4 +283,4 @@ declare function createStopAtFirstParameter(): IgnoreFunction;
 //#region src/plugin.d.ts
 declare const definePlugin: (plugin: Plugin) => Plugin;
 //#endregion
-export { BaseContext, Clerc, ClercFlagOptions, ClercFlagsDefinition, Command, CommandCustomOptions, CommandHandler, CommandHandlerContext, CommandOptions, CommandWithHandler, CommandsMap, CommandsRecord, DOUBLE_DASH, ErrorHandler, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, KNOWN_FLAG, MakeEmitterEvents, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, Plugin, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, resolveCommand };
+export { BaseContext, Choices, Clerc, ClercFlagOptions, ClercFlagOptionsWithDescription, ClercFlagsDefinition, ClercGlobalFlagDefinitionValue, Command, CommandCustomOptions, CommandHandler, CommandHandlerContext, CommandOptions, CommandWithHandler, CommandsMap, CommandsRecord, DOUBLE_DASH, ErrorHandler, FlagCustomOptions, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, KNOWN_FLAG, MakeEmitterEvents, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, Plugin, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, resolveCommand };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DOUBLE_DASH, DOUBLE_DASH as DOUBLE_DASH$1, KNOWN_FLAG, PARAMETER, PARAMETER as PARAMETER$1, UNKNOWN_FLAG, parse } from "@clerc/parser";
+import { Choices, DOUBLE_DASH, DOUBLE_DASH as DOUBLE_DASH$1, KNOWN_FLAG, PARAMETER, PARAMETER as PARAMETER$1, UNKNOWN_FLAG, parse } from "@clerc/parser";
 import { camelCase, toArray } from "@clerc/utils";
 import { LiteEmit } from "lite-emit";
 
@@ -198,7 +198,7 @@ var Clerc = class Clerc {
 	#callWithErrorHandler(fn) {
 		try {
 			const result = fn();
-			if (result instanceof Promise) result.catch((error) => {
+			if (result instanceof Promise) return result.catch((error) => {
 				this.#handleError(error);
 			});
 			return result;
@@ -257,7 +257,7 @@ var Clerc = class Clerc {
 			ignore
 		}));
 	}
-	run() {
+	async run() {
 		const parametersToResolve = getParametersToResolve(this.#argv);
 		const [command, calledAs] = resolveCommand(this.#commands, parametersToResolve);
 		const argvToPass = command && calledAs.length > 0 ? this.#argv.slice(calledAs.split(" ").length) : this.#argv;
@@ -288,14 +288,14 @@ var Clerc = class Clerc {
 			}
 		};
 		const composedInterceptor = compose([...this.#interceptors, emitInterceptor]);
-		this.#callWithErrorHandler(() => composedInterceptor(context));
+		return this.#callWithErrorHandler(() => composedInterceptor(context));
 	}
 	parse(argvOrOptions = platformArgv) {
 		this.#callWithErrorHandler(() => this.#validate());
 		if (Array.isArray(argvOrOptions)) argvOrOptions = { argv: argvOrOptions };
 		const { argv = platformArgv, run = true } = argvOrOptions;
 		this.#argv = argv;
-		if (run) this.run();
+		if (run) return this.run();
 		return this;
 	}
 };
@@ -322,4 +322,4 @@ function createStopAtFirstParameter() {
 const definePlugin = (plugin) => plugin;
 
 //#endregion
-export { Clerc, DOUBLE_DASH, InvalidCommandError, InvalidParametersError, KNOWN_FLAG, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, resolveCommand };
+export { Choices, Clerc, DOUBLE_DASH, InvalidCommandError, InvalidParametersError, KNOWN_FLAG, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, resolveCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/core",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc core",
@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "lite-emit": "^3.1.0",
-    "@clerc/parser": "^1.0.0-beta.2",
-    "@clerc/utils": "1.0.0-beta.2"
+    "@clerc/parser": "^1.0.0-beta.3",
+    "@clerc/utils": "1.0.0-beta.3"
   },
   "devDependencies": {
     "is-platform": "^1.0.0"