@clerc/parser 1.0.0-beta.24 → 1.0.0-beta.26

package/dist/index.d.ts

@@ -2,16 +2,11 @@
 declare class InvalidSchemaError extends Error {
   constructor(message: string);
 }
-declare class MissingRequiredFlagError extends Error {
-  constructor(name: string);
-}
 //#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/iterator.d.ts
 declare const KNOWN_FLAG = "known-flag";
@@ -47,20 +42,22 @@ interface TypeFunction<T = unknown> {
 */
 type IgnoreFunction = (type: typeof KNOWN_FLAG | typeof UNKNOWN_FLAG | typeof PARAMETER, arg: string) => boolean;
 type TypeValue<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
-interface BaseFlagOptions<T extends TypeValue = TypeValue> {
+type Foo = RequireExactlyOneOrNone<{
+  /** The default value of the flag. */
+  default?: unknown;
+  /** Whether the flag is required. */
+  required?: boolean;
+}, "default" | "required">;
+type BaseFlagOptions<T extends TypeValue = TypeValue> = Foo & {
   /**
   * 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;
-  /** Whether the flag is required. */
-  required?: boolean;
-}
+  /** Short flag alias (single character). */
+  short?: string;
+};
 type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
   /**
   * Whether to enable the `--no-<flag>` syntax to set the value to false.
@@ -121,6 +118,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>;
@@ -190,4 +189,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, DOUBLE_DASH, Enum, FlagDefaultValue, FlagDefaultValueFunction, FlagDefinitionValue, FlagOptions, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, MissingRequiredFlagError, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, Range, RawInputType, Regex, TypeFunction, TypeValue, UNKNOWN_FLAG, createParser, parse };
+export { BaseFlagOptions, DOUBLE_DASH, Enum, FlagDefaultValue, FlagDefaultValueFunction, FlagDefinitionValue, FlagOptions, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, Range, RawInputType, Regex, TypeFunction, TypeValue, UNKNOWN_FLAG, createParser, parse };

package/dist/index.js

@@ -5,12 +5,6 @@ var InvalidSchemaError = class extends Error {
 		this.name = "InvalidSchemaError";
 	}
 };
-var MissingRequiredFlagError = class extends Error {
-	constructor(name) {
-		super(`Missing required flag: ${name}`);
-		this.name = "MissingRequiredFlagError";
-	}
-};
 
 //#endregion
 //#region src/flag-types.ts
@@ -122,7 +116,6 @@ function iterateArgs(args, result, shouldProcessAsFlag, isKnownFlag, ignore, cal
 //#endregion
 //#region ../utils/src/index.ts
 const looseIsArray = (arr) => Array.isArray(arr);
-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.
@@ -161,9 +154,14 @@ function buildConfigsAndAliases(delimiters, flags) {
 	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.alias) names.push(...toArray(options.alias));
+		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);
@@ -171,10 +169,7 @@ function buildConfigsAndAliases(delimiters, flags) {
 		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);
-		}
+		if (normalized.short) aliases.set(normalized.short, name);
 	}
 	return {
 		configs,
@@ -240,7 +235,7 @@ 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);
@@ -249,6 +244,7 @@ function createParser(options = {}) {
 			if (!key) return;
 		}
 		const config = configs.get(key);
+		if (!isShortFlag && config.short === rootName) return;
 		return {
 			key,
 			config,
@@ -269,21 +265,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) => {
@@ -293,7 +290,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) {
@@ -310,13 +308,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;
@@ -373,7 +371,7 @@ function createParser(options = {}) {
 			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) throw new MissingRequiredFlagError(key);
+			else if (config.required) result.missingRequiredFlags.push(key);
 		}
 		return result;
 	};
@@ -382,4 +380,4 @@ function createParser(options = {}) {
 const parse = (args, options = {}) => createParser(options).parse(args);
 
 //#endregion
-export { DOUBLE_DASH, Enum, InvalidSchemaError, KNOWN_FLAG, MissingRequiredFlagError, PARAMETER, Range, Regex, UNKNOWN_FLAG, createParser, parse };
+export { DOUBLE_DASH, Enum, InvalidSchemaError, KNOWN_FLAG, PARAMETER, Range, Regex, UNKNOWN_FLAG, createParser, parse };

package/package.json

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