@clerc/core 1.0.0-beta.1 → 1.0.0-beta.10

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] } & {};
@@ -10,11 +28,13 @@ type UnknownArray = readonly unknown[];
 type MapsSetsOrArrays = ReadonlyMap<unknown, unknown> | WeakMap<WeakKey, unknown> | ReadonlySet<unknown> | WeakSet<WeakKey> | UnknownArray;
 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;
 type DeepPrettify<T, E = never> = ConditionalDeepPrettify<T, E | NonRecursiveType | MapsSetsOrArrays, object>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
 //#endregion
 //#region ../utils/src/types/index.d.ts
 type MaybeArray<T> = T | T[];
 type PartialRequired<T, K$1 extends keyof T> = T & { [P in K$1]-?: T[P] };
 type UnionToIntersection<U$1> = (U$1 extends any ? (k: U$1) => void : never) extends ((k: infer I) => void) ? I : never;
+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;
 //#endregion
 //#region ../parser/src/types.d.ts
 type FlagDefaultValue<T = unknown> = T | (() => T);
@@ -23,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`.
@@ -88,7 +114,10 @@ interface ParsedResult<TFlags extends Record<string, any>> {
 type InferFlagDefault<T extends FlagDefinitionValue, Fallback> = T extends {
   default: FlagDefaultValue<infer DefaultType>;
 } ? DefaultType : Fallback;
-type _InferFlags<T extends FlagsDefinition> = { [K in keyof T]: T[K] extends readonly [BooleanConstructor] | {
+type IsTypeAny<T extends FlagDefinitionValue> = IsAny<T> extends true ? true : T extends {
+  type: infer Type;
+} ? IsAny<Type> extends true ? true : false : false;
+type _InferFlags<T extends FlagsDefinition> = { [K in keyof T]: IsTypeAny<T[K]> extends true ? any : T[K] extends readonly [BooleanConstructor] | {
   type: readonly [BooleanConstructor];
 } ? number : T[K] extends ObjectConstructor | {
   type: ObjectConstructor;
@@ -110,18 +139,24 @@ declare const KNOWN_FLAG = "known-flag";
 declare const UNKNOWN_FLAG = "unknown-flag";
 declare const PARAMETER = "parameter";
 //#endregion
+//#region ../parser/src/parse.d.ts
+declare const DOUBLE_DASH = "--";
+//#endregion
 //#region src/types/clerc.d.ts
 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<Name, string[]> : T extends `<${infer Name extends string}>` ? Record<Name, string> : T extends `[${infer Name extends string}]` ? Record<Name, string | undefined> : never;
-type InferParameters<T extends string[]> = T extends (infer U extends string)[] ? Prettify<UnionToIntersection<InferParameter<U>>> : never;
+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;
+type InferParameters<T extends readonly string[]> = T extends readonly (infer U extends string)[] ? Prettify<UnionToIntersection<InferParameter<U>>> : never;
 //#endregion
 //#region src/types/context.d.ts
 type AddStringIndex<T> = T & Record<string, any>;
@@ -134,12 +169,12 @@ interface BaseContext<C extends Command = Command, GF extends ClercFlagsDefiniti
   flags: InferFlagsWithGlobal<C, GF>;
   ignored: string[];
   rawParsed: ParsedResult<InferFlagsWithGlobal<C, GF>>;
-  maybeMissingParameters?: boolean;
+  missingParameters: boolean;
 }
 //#endregion
 //#region src/types/command.d.ts
 interface CommandCustomOptions {}
-interface CommandOptions<Parameters extends string[] = string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandCustomOptions {
+interface CommandOptions<Parameters extends readonly string[] = readonly string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandCustomOptions {
   alias?: MaybeArray<string>;
   parameters?: Parameters;
   flags?: Flags;
@@ -148,11 +183,11 @@ interface CommandOptions<Parameters extends string[] = string[], Flags extends C
   */
   ignore?: IgnoreFunction;
 }
-interface Command<Name$1 extends string = string, Parameters extends string[] = string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandOptions<Parameters, Flags> {
+interface Command<Name$1 extends string = string, Parameters extends readonly string[] = readonly string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> extends CommandOptions<Parameters, Flags> {
   name: Name$1;
   description: string;
 }
-type CommandWithHandler<Name$1 extends string = string, Parameters extends string[] = string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> = Command<Name$1, Parameters, Flags> & {
+type CommandWithHandler<Name$1 extends string = string, Parameters extends readonly string[] = readonly string[], Flags extends ClercFlagsDefinition = ClercFlagsDefinition> = Command<Name$1, Parameters, Flags> & {
   handler?: CommandHandler<Command<Name$1, Parameters, Flags>>;
 };
 type CommandsRecord = Record<string, Command>;
@@ -189,8 +224,9 @@ interface CreateOptions {
   description?: string;
   version?: string;
 }
-interface ParseOptions {
-  run?: boolean;
+interface ParseOptions<Run extends boolean = true> {
+  argv?: string[];
+  run?: Run;
 }
 declare class Clerc<Commands extends CommandsRecord = {}, GlobalFlags extends ClercFlagsDefinition = {}> {
   #private;
@@ -208,15 +244,13 @@ declare class Clerc<Commands extends CommandsRecord = {}, GlobalFlags extends Cl
   version(version: string): this;
   use(plugin: Plugin): this;
   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>>;
+  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>;
+  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>;
+  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(argv?: string[], {
-    run
-  }?: 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
@@ -225,10 +259,10 @@ declare function resolveCommand(commandsMap: CommandsMap, parameters: string[]):
 //#region src/errors.d.ts
 declare class NoSuchCommandError extends Error {
   commandName: string;
-  constructor(commandName: string);
+  constructor(commandName: string, text?: string);
 }
-declare class NoCommandGivenError extends Error {
-  constructor();
+declare class NoCommandSpecifiedError extends Error {
+  constructor(text?: string);
 }
 declare class InvalidCommandError extends Error {
   constructor(message: string);
@@ -241,7 +275,7 @@ declare class InvalidParametersError extends Error {
 }
 //#endregion
 //#region src/helpers.d.ts
-declare const defineCommand: <Name$1 extends string, Parameters extends string[] = [], Flags extends ClercFlagsDefinition = {}>(command: CommandWithHandler<Name$1, [...Parameters], Flags>) => CommandWithHandler<Name$1, [...Parameters], Flags>;
+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>;
 //#endregion
 //#region src/ignore.d.ts
 declare function createStopAtFirstParameter(): IgnoreFunction;
@@ -249,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, ErrorHandler, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, MakeEmitterEvents, MissingRequiredMetadataError, NoCommandGivenError, NoSuchCommandError, Plugin, createStopAtFirstParameter, defineCommand, definePlugin, resolveCommand };
+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 };

package/dist/index.js

@@ -1,7 +1,30 @@
-import { DOUBLE_DASH, PARAMETER, parse } from "@clerc/parser";
-import { toArray } from "@clerc/utils";
+import { Choices, DOUBLE_DASH, DOUBLE_DASH as DOUBLE_DASH$1, KNOWN_FLAG, PARAMETER, PARAMETER as PARAMETER$1, UNKNOWN_FLAG, parse } from "@clerc/parser";
 import { LiteEmit } from "lite-emit";
 
+//#region ../utils/src/index.ts
+const toArray = (a) => Array.isArray(a) ? a : [a];
+/**
+* Converts a dash- or space-separated string to camelCase.
+* Not using regexp for better performance, because this function is used in parser.
+*/
+function camelCase(str) {
+	const firstIdx = Math.min(str.includes("-") ? str.indexOf("-") : Infinity, str.includes(" ") ? str.indexOf(" ") : Infinity);
+	if (firstIdx === Infinity) return str;
+	let result = str.slice(0, firstIdx);
+	for (let i = firstIdx; i < str.length; i++) if ((str[i] === "-" || str[i] === " ") && i + 1 < str.length) {
+		const nextChar = str.charCodeAt(i + 1);
+		if (nextChar >= 97 && nextChar <= 122) {
+			result += String.fromCharCode(nextChar - 32);
+			i++;
+		} else {
+			result += str[i + 1];
+			i++;
+		}
+	} else if (str[i] !== "-" && str[i] !== " ") result += str[i];
+	return result;
+}
+
+//#endregion
 //#region src/commands.ts
 function resolveCommand(commandsMap, parameters) {
 	for (let i = parameters.length; i >= 0; i--) {
@@ -14,14 +37,14 @@ function resolveCommand(commandsMap, parameters) {
 //#endregion
 //#region src/errors.ts
 var NoSuchCommandError = class extends Error {
-	constructor(commandName) {
-		super(`No such command: "${commandName}".`);
+	constructor(commandName, text = `No such command: "${commandName}".`) {
+		super(text);
 		this.commandName = commandName;
 	}
 };
-var NoCommandGivenError = class extends Error {
-	constructor() {
-		super("No command specified.");
+var NoCommandSpecifiedError = class extends Error {
+	constructor(text = "No command specified.") {
+		super(text);
 	}
 };
 var InvalidCommandError = class extends Error {
@@ -82,7 +105,7 @@ function getParametersToResolve(argv) {
 	}
 	return parameters;
 }
-const PARAMETER_REGEX = /^(<|\[)(\w+)(\.\.\.)?(\]|>)$/;
+const PARAMETER_REGEX = /^(<|\[)([\w ]+)(\.\.\.)?(\]|>)$/;
 const isParameterDefinitionBracketsValid = (definition) => definition.startsWith("<") && definition.endsWith(">") || definition.startsWith("[") && definition.endsWith("]");
 function _parseParameters(definitions, parameters) {
 	const result = {};
@@ -90,7 +113,7 @@ function _parseParameters(definitions, parameters) {
 	for (const [i, definition] of definitions.entries()) {
 		const match = definition.match(PARAMETER_REGEX);
 		if (!match || !isParameterDefinitionBracketsValid(definition)) throw new InvalidParametersError(`Invalid parameter definition: ${definition}`);
-		const name = match[2];
+		const name = camelCase(match[2]);
 		const isVariadic = !!match[3];
 		const isRequired = definition.startsWith("<");
 		if (name in result) throw new InvalidParametersError(`Duplicate parameter name: ${name}`);
@@ -105,7 +128,7 @@ function _parseParameters(definitions, parameters) {
 	return result;
 }
 function parseParameters(definitions, parameters, doubleDashParameters) {
-	const doubleDashIndex = definitions.indexOf(DOUBLE_DASH);
+	const doubleDashIndex = definitions.indexOf(DOUBLE_DASH$1);
 	if (doubleDashIndex === -1) return _parseParameters(definitions, parameters);
 	else {
 		const definitionBeforeDoubleDash = definitions.slice(0, doubleDashIndex);
@@ -198,7 +221,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;
@@ -217,7 +240,7 @@ var Clerc = class Clerc {
 			description,
 			...options
 		} : nameOrCommandObject;
-		const aliases = toArray(options?.alias ?? []);
+		const aliases = toArray(command?.alias ?? []);
 		this.#callWithErrorHandler(() => this.#validateCommandNameAndAlias(command.name, aliases));
 		this.#commands.set(command.name, command);
 		for (const alias of aliases) this.#commands.set(alias, {
@@ -257,7 +280,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;
@@ -277,37 +300,42 @@ var Clerc = class Clerc {
 			flags: parsed.flags,
 			ignored: parsed.ignored,
 			rawParsed: parsed,
-			maybeMissingParameters: !!parametersError
+			missingParameters: !!parametersError
 		};
 		const emitInterceptor = {
 			enforce: "post",
 			handler: (ctx) => {
 				if (parametersError) throw parametersError;
 				if (command) this.#emitter.emit(command.name, ctx);
-				else throw parametersToResolve.length > 0 ? new NoSuchCommandError(parametersToResolve.join(" ")) : new NoCommandGivenError();
+				else throw parametersToResolve.length > 0 ? new NoSuchCommandError(parametersToResolve.join(" ")) : new NoCommandSpecifiedError();
 			}
 		};
 		const composedInterceptor = compose([...this.#interceptors, emitInterceptor]);
-		this.#callWithErrorHandler(() => composedInterceptor(context));
+		return this.#callWithErrorHandler(() => composedInterceptor(context));
 	}
-	parse(argv = platformArgv, { run = true } = {}) {
+	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;
 	}
 };
 
 //#endregion
 //#region src/helpers.ts
-const defineCommand = (command) => command;
+const defineCommand = (command, handler) => ({
+	...command,
+	handler
+});
 
 //#endregion
 //#region src/ignore.ts
 function createStopAtFirstParameter() {
 	let encounteredParameter = false;
 	return (type) => {
-		if (type === PARAMETER && !encounteredParameter) {
+		if (type === PARAMETER$1 && !encounteredParameter) {
 			encounteredParameter = true;
 			return false;
 		}
@@ -320,4 +348,4 @@ function createStopAtFirstParameter() {
 const definePlugin = (plugin) => plugin;
 
 //#endregion
-export { Clerc, InvalidCommandError, InvalidParametersError, MissingRequiredMetadataError, NoCommandGivenError, NoSuchCommandError, 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.1",
+  "version": "1.0.0-beta.10",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc core",
@@ -45,14 +45,10 @@
   },
   "dependencies": {
     "lite-emit": "^3.1.0",
-    "@clerc/parser": "^1.0.0-beta.1",
-    "@clerc/utils": "1.0.0-beta.1"
+    "@clerc/parser": "^1.0.0-beta.10"
   },
   "devDependencies": {
-    "is-platform": "^1.0.0"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "watch": "tsdown --watch"
+    "is-platform": "^1.0.0",
+    "@clerc/utils": "1.0.0-beta.10"
   }
 }