@clerc/parser 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -1,15 +1,15 @@
 # @clerc/parser
 
+[![NPM version](https://img.shields.io/npm/v/@clerc/parser?color=a1b858&label=)](https://www.npmjs.com/package/@clerc/parser)
+
 A powerful, lightweight, and flexible command-line arguments parser.
 
 ## Installation
 
 ```bash
-npm install @clerc/parser
-# or
-yarn add @clerc/parser
-# or
-pnpm add @clerc/parser
+$ npm install @clerc/parser
+$ yarn add @clerc/parser
+$ pnpm add @clerc/parser
 ```
 
 ## Usage
@@ -360,3 +360,7 @@ BENCH  Summary
     3.85x faster than nopt
     27.11x faster than yargs-parser
 ```
+
+## 📝 License
+
+[MIT](../../LICENSE). Made with ❤️ by [Ray](https://github.com/so1ve)

package/dist/index.d.ts

@@ -3,44 +3,30 @@ declare class InvalidSchemaError extends Error {
   constructor(message: string);
 }
 //#endregion
-//#region 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 Prettify<T> = { [K in keyof T]: T[K] } & {};
 type IsAny<T> = 0 extends 1 & T ? true : false;
-//#endregion
-//#region ../utils/src/types/index.d.ts
-type MaybeArray<T> = T | T[];
+type RequireExactlyOneOrNone<T, Keys extends keyof T = keyof T> = ({ [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys] & Omit<T, Keys>) | (Partial<Record<Keys, never>> & Omit<T, Keys>);
 //#endregion
 //#region src/types.d.ts
-type FlagDefaultValue<T = unknown> = T | (() => T);
+interface FlagDefaultValueFunction<T> {
+  (): T;
+  display?: string;
+}
+type FlagDefaultValue<T = unknown> = T | FlagDefaultValueFunction<T>;
 /**
 * Defines how a string input is converted to the target type T.
 *
 * @template T The target type.
 */
-type FlagTypeFunction<T = unknown> = ((value: string) => T) & {
+interface TypeFunction<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;
-};
+  display?: string;
+}
 /**
 * A callback function to conditionally stop parsing.
 * When it returns true, parsing stops and remaining arguments are preserved in `ignored`.
@@ -50,19 +36,23 @@ type FlagTypeFunction<T = unknown> = ((value: string) => T) & {
 * @returns true to stop parsing, false to continue
 */
 type IgnoreFunction = (type: typeof KNOWN_FLAG | typeof UNKNOWN_FLAG | typeof PARAMETER, arg: string) => boolean;
-type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
-interface BaseFlagOptions<T extends FlagType = FlagType> {
+type TypeValue<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
+type FlagRequiredOrDefault = RequireExactlyOneOrNone<{
+  /** The default value of the flag. */
+  default?: unknown;
+  /** Whether the flag is required. */
+  required?: boolean;
+}, "default" | "required">;
+type BaseFlagOptions<T extends TypeValue = TypeValue> = FlagRequiredOrDefault & {
   /**
   * The type constructor or a function to convert the string value.
   * To support multiple occurrences of a flag (e.g., --file a --file b), wrap the type in an array: [String], [Number].
   * e.g., String, Number, [String], (val) => val.split(',')
   */
   type: T;
-  /** Aliases for the flag. */
-  alias?: MaybeArray<string>;
-  /** The default value of the flag. */
-  default?: unknown;
-}
+  /** Short flag alias (single character). */
+  short?: string;
+};
 type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
   /**
   * Whether to enable the `--no-<flag>` syntax to set the value to false.
@@ -75,7 +65,7 @@ type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
 }) | (BaseFlagOptions & {
   negatable?: never;
 });
-type FlagDefinitionValue = FlagOptions | FlagType;
+type FlagDefinitionValue = FlagOptions | TypeValue;
 type FlagsDefinition = Record<string, FlagDefinitionValue>;
 /**
 * Configuration options for the parser.
@@ -123,6 +113,8 @@ interface ParsedResult<TFlags extends Record<string, any>> {
   unknown: Record<string, RawInputType>;
   /** Arguments that were not parsed due to ignore callback. */
   ignored: string[];
+  /** List of required flags that were not provided. */
+  missingRequiredFlags: string[];
 }
 type InferFlagDefault<T extends FlagDefinitionValue, Fallback> = T extends {
   default: FlagDefaultValue<infer DefaultType>;
@@ -132,13 +124,15 @@ type IsTypeAny<T extends FlagDefinitionValue> = IsAny<T> extends true ? true : T
 } ? 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 | {
+} ? number | InferFlagDefault<T[K], never> : T[K] extends ObjectConstructor | {
   type: ObjectConstructor;
-} ? ObjectInputType : T[K] extends readonly [FlagType<infer U>] | {
-  type: readonly [FlagType<infer U>];
-} ? U[] | InferFlagDefault<T[K], never> : T[K] extends FlagType<infer U> | {
-  type: FlagType<infer U>;
-} ? U | InferFlagDefault<T[K], [U] extends [boolean] ? never : undefined> : never };
+} ? ObjectInputType | InferFlagDefault<T[K], never> : T[K] extends readonly [TypeValue<infer U>] | {
+  type: readonly [TypeValue<infer U>];
+} ? U[] | InferFlagDefault<T[K], never> : T[K] extends TypeValue<infer U> | {
+  type: TypeValue<infer U>;
+} ? U | InferFlagDefault<T[K], [U] extends [boolean] ? never : T[K] extends {
+  required: true;
+} ? never : undefined> : never };
 /**
 * An advanced utility type that infers the exact type of the `flags` object in the parsed result,
 * based on the provided `flags` configuration object T.
@@ -160,4 +154,4 @@ declare function createParser<T extends FlagsDefinition>(options?: ParserOptions
 };
 declare const parse: <T extends FlagsDefinition>(args: string[], options?: ParserOptions<T>) => ParsedResult<InferFlags<T>>;
 //#endregion
-export { BaseFlagOptions, Choices, DOUBLE_DASH, FlagDefaultValue, FlagDefinitionValue, FlagOptions, FlagType, FlagTypeFunction, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, UNKNOWN_FLAG, createParser, parse };
+export { BaseFlagOptions, DOUBLE_DASH, FlagDefaultValue, FlagDefaultValueFunction, FlagDefinitionValue, FlagOptions, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, TypeFunction, TypeValue, UNKNOWN_FLAG, createParser, parse };

package/dist/index.js

@@ -6,31 +6,6 @@ var InvalidSchemaError = class extends Error {
 	}
 };
 
-//#endregion
-//#region src/flag-types.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
-* ```
-*/
-function Choices(...values) {
-	const fn = ((value) => {
-		if (!values.includes(value)) throw new Error(`Invalid value: ${value}. Must be one of: ${values.join(", ")}`);
-		return value;
-	});
-	fn.displayName = values.join(" | ");
-	return fn;
-}
-
 //#endregion
 //#region src/iterator.ts
 const KNOWN_FLAG = "known-flag";
@@ -81,8 +56,8 @@ function iterateArgs(args, result, shouldProcessAsFlag, isKnownFlag, ignore, cal
 }
 
 //#endregion
-//#region ../utils/dist/index.js
-const toArray = (a) => Array.isArray(a) ? a : [a];
+//#region ../utils/src/index.ts
+const looseIsArray = (arr) => Array.isArray(arr);
 /**
 * Converts a dash- or space-separated string to camelCase.
 * Not using regexp for better performance, because this function is used in parser.
@@ -103,10 +78,49 @@ function camelCase(str) {
 	} else if (str[i] !== "-" && str[i] !== " ") result += str[i];
 	return result;
 }
+const resolveValue = (value) => typeof value === "function" ? value() : value;
+
+//#endregion
+//#region src/config.ts
+const defaultParserOptions = { delimiters: ["=", ":"] };
+const resolveParserOptions = (options = {}) => ({
+	...defaultParserOptions,
+	...options
+});
+const normalizeConfig = (config) => typeof config === "function" || looseIsArray(config) ? { type: config } : config;
+const BUILDTIN_DELIMITERS_RE = /[\s.]/;
+function buildConfigsAndAliases(delimiters, flags) {
+	const configs = /* @__PURE__ */ new Map();
+	const aliases = /* @__PURE__ */ new Map();
+	const isNameInvalid = (name) => delimiters.some((char) => name.includes(char)) || BUILDTIN_DELIMITERS_RE.test(name);
+	function validateFlagOptions(name, options) {
+		const prefix = `Flag "${name}"`;
+		if (Array.isArray(options.type) && options.type.length > 1) throw new InvalidSchemaError(`${prefix} has an invalid type array. Only single-element arrays are allowed to denote multiple occurrences.`);
+		if (name.length < 2) throw new InvalidSchemaError(`${prefix} name must be at least 2 characters long.`);
+		const names = [name];
+		if (options.short) {
+			if (options.short.length !== 1) throw new InvalidSchemaError(`${prefix} short flag must be exactly 1 character long.`);
+			names.push(options.short);
+		}
+		if (names.some(isNameInvalid)) throw new InvalidSchemaError(`${prefix} contains reserved characters, which are used as delimiters.`);
+		if (options.required && options.default !== void 0) throw new InvalidSchemaError(`${prefix} cannot be both required and have a default value.`);
+	}
+	for (const [name, config] of Object.entries(flags)) {
+		const normalized = normalizeConfig(config);
+		validateFlagOptions(name, normalized);
+		configs.set(name, normalized);
+		aliases.set(name, name);
+		aliases.set(camelCase(name), name);
+		if (normalized.short) aliases.set(normalized.short, name);
+	}
+	return {
+		configs,
+		aliases
+	};
+}
 
 //#endregion
 //#region src/utils.ts
-const looseIsArray = (arr) => Array.isArray(arr);
 const isArrayOfType = (arr, type) => Array.isArray(arr) && arr[0] === type;
 /**
 * Check if it's a letter (a-z: 97-122, A-Z: 65-90)
@@ -157,50 +171,13 @@ function splitNameAndValue(arg, delimiters) {
 	};
 }
 
-//#endregion
-//#region src/config.ts
-const defaultParserOptions = { delimiters: ["=", ":"] };
-const resolveParserOptions = (options = {}) => ({
-	...defaultParserOptions,
-	...options
-});
-const normalizeConfig = (config) => typeof config === "function" || looseIsArray(config) ? { type: config } : config;
-const BUILDTIN_DELIMITERS_RE = /[\s.]/;
-function buildConfigsAndAliases(delimiters, flags) {
-	const configs = /* @__PURE__ */ new Map();
-	const aliases = /* @__PURE__ */ new Map();
-	const isNameInvalid = (name) => delimiters.some((char) => name.includes(char)) || BUILDTIN_DELIMITERS_RE.test(name);
-	function validateFlagOptions(name, options) {
-		const prefix = `Flag "${name}"`;
-		if (Array.isArray(options.type) && options.type.length > 1) throw new InvalidSchemaError(`${prefix} has an invalid type array. Only single-element arrays are allowed to denote multiple occurrences.`);
-		const names = [name];
-		if (options.alias) names.push(...toArray(options.alias));
-		if (names.some(isNameInvalid)) throw new InvalidSchemaError(`${prefix} contains reserved characters, which are used as delimiters.`);
-	}
-	for (const [name, config] of Object.entries(flags)) {
-		const normalized = normalizeConfig(config);
-		validateFlagOptions(name, normalized);
-		configs.set(name, normalized);
-		aliases.set(name, name);
-		aliases.set(camelCase(name), name);
-		if (normalized.alias) {
-			const list = Array.isArray(normalized.alias) ? normalized.alias : [normalized.alias];
-			for (const a of list) aliases.set(a, name);
-		}
-	}
-	return {
-		configs,
-		aliases
-	};
-}
-
 //#endregion
 //#region src/parse.ts
 const DOUBLE_DASH = "--";
 function createParser(options = {}) {
 	const { flags: flagsConfig = {}, delimiters, ignore } = resolveParserOptions(options);
 	const { configs, aliases } = buildConfigsAndAliases(delimiters, flagsConfig);
-	function resolve(name) {
+	function resolve(name, isShortFlag = false) {
 		const dotIdx = name.indexOf(".");
 		const rootName = dotIdx === -1 ? name : name.slice(0, dotIdx);
 		let key = aliases.get(rootName);
@@ -209,6 +186,7 @@ function createParser(options = {}) {
 			if (!key) return;
 		}
 		const config = configs.get(key);
+		if (!isShortFlag && config.short === rootName) return;
 		return {
 			key,
 			config,
@@ -229,21 +207,22 @@ function createParser(options = {}) {
 		if (len < 2) return false;
 		const secondChar = arg.charCodeAt(1);
 		if (isLetter(secondChar)) return true;
-		if (isDigit(secondChar)) return !!resolve(secondChar !== 45 ? arg[1] : arg.slice(2));
+		if (isDigit(secondChar)) {
+			const isShortFlag = secondChar !== 45;
+			return !!resolve(isShortFlag ? arg[1] : arg.slice(2), isShortFlag);
+		}
 		if (secondChar === 45 && len > 2) return isLetter(arg.charCodeAt(2));
 		return false;
 	}
 	function isKnownFlag(arg) {
-		const secondChar = arg.charCodeAt(1);
-		if (secondChar === 45) {
+		if (arg.charCodeAt(1) === 45) {
 			const { rawName } = splitNameAndValue(arg.slice(2), delimiters);
-			if (resolve(rawName)) return true;
+			if (resolve(rawName, false)) return true;
 			if (resolveNegated(rawName)) return true;
 			return false;
 		}
-		if (isDigit(secondChar)) return true;
 		const chars = arg.slice(1);
-		for (const char of chars) if (!resolve(char)) return false;
+		for (const char of chars) if (!resolve(char, true)) return false;
 		return true;
 	}
 	const parse$1 = (args) => {
@@ -253,7 +232,8 @@ function createParser(options = {}) {
 			flags: {},
 			raw: args,
 			unknown: {},
-			ignored: []
+			ignored: [],
+			missingRequiredFlags: []
 		};
 		iterateArgs(args, result, shouldProcessAsFlag, isKnownFlag, ignore, ({ current, eat, exit, hasNext, index, next, shouldIgnore }) => {
 			if (current === DOUBLE_DASH) {
@@ -270,13 +250,13 @@ function createParser(options = {}) {
 				result.parameters.push(current);
 				return;
 			}
-			const isAlias = !current.startsWith(DOUBLE_DASH);
-			const chars = current.slice(isAlias ? 1 : 2);
-			if (isAlias) {
+			const isShortFlag = !current.startsWith(DOUBLE_DASH);
+			const chars = current.slice(isShortFlag ? 1 : 2);
+			if (isShortFlag) {
 				const charsLen = chars.length;
 				for (let j = 0; j < charsLen; j++) {
 					const char = chars[j];
-					const resolved = resolve(char);
+					const resolved = resolve(char, true);
 					if (!resolved) {
 						result.unknown[char] = true;
 						continue;
@@ -288,8 +268,8 @@ function createParser(options = {}) {
 						setValueByType(result.flags, key, chars.slice(j + 1), config);
 						break;
 					} else {
-						const nextValue = eat();
-						if (nextValue && !shouldProcessAsFlag(nextValue)) setValueByType(result.flags, key, nextValue, config);
+						const value = hasNext && !shouldProcessAsFlag(next) ? eat() ?? "" : "";
+						setValueByType(result.flags, key, value, config);
 					}
 				}
 			} else {
@@ -329,10 +309,11 @@ function createParser(options = {}) {
 			}
 		});
 		for (const [key, config] of configs.entries()) if (result.flags[key] === void 0) {
-			if (config.default !== void 0) result.flags[key] = typeof config.default === "function" ? config.default() : config.default;
+			if (config.default !== void 0) result.flags[key] = resolveValue(config.default);
 			else if (Array.isArray(config.type)) result.flags[key] = isArrayOfType(config.type, Boolean) ? 0 : [];
 			else if (config.type === Object) result.flags[key] = {};
 			else if (config.type === Boolean) result.flags[key] = false;
+			else if (config.required) result.missingRequiredFlags.push(key);
 		}
 		return result;
 	};
@@ -341,4 +322,4 @@ function createParser(options = {}) {
 const parse = (args, options = {}) => createParser(options).parse(args);
 
 //#endregion
-export { Choices, DOUBLE_DASH, InvalidSchemaError, KNOWN_FLAG, PARAMETER, UNKNOWN_FLAG, createParser, parse };
+export { DOUBLE_DASH, InvalidSchemaError, KNOWN_FLAG, PARAMETER, UNKNOWN_FLAG, createParser, parse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/parser",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc parser",
@@ -56,10 +56,6 @@
     "nopt": "^9.0.0",
     "type-flag": "^4.0.3",
     "yargs-parser": "^22.0.0",
-    "@clerc/utils": "1.0.0-beta.8"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "watch": "tsdown --watch"
+    "@clerc/utils": "1.0.0"
   }
 }