@clerc/parser 1.0.0-beta.2 → 1.0.0-beta.20

package/README.md

@@ -332,3 +332,31 @@ const { flags, doubleDash } = parse(["--foo", "--", "--bar"], {
 // flags: { foo: true, bar: false }
 // doubleDash: ["--bar"]
 ```
+
+## Benchmark
+
+Benchmarked with vitest.
+
+```
+✓ packages/parser/bench/bench.bench.ts > bench 6267ms
+		name                           hz     min     max    mean     p75     p99    p995    p999     rme  samples
+	· minimist               684,422.77  0.0012  3.5582  0.0015  0.0013  0.0031  0.0040  0.0222  ±1.50%   342212
+	· mri                  2,451,855.02  0.0003  0.2422  0.0004  0.0004  0.0007  0.0009  0.0021  ±0.33%  1225928
+	· yargs-parser            90,437.66  0.0092  3.1595  0.0111  0.0103  0.0346  0.0602  0.1311  ±1.42%    45219
+	· nopt                   636,086.73  0.0014  0.3214  0.0016  0.0015  0.0027  0.0031  0.0056  ±0.38%   318044
+	· type-flag              715,908.28  0.0012  0.3783  0.0014  0.0013  0.0022  0.0027  0.0282  ±0.61%   357955
+	· node:util parseArgs  1,204,359.72  0.0007  0.3827  0.0008  0.0008  0.0016  0.0017  0.0047  ±0.56%   602196
+	· args-tokens          2,379,934.00  0.0002  0.2923  0.0004  0.0004  0.0010  0.0015  0.0051  ±0.49%  1189967
+	· @clerc/parser        2,119,030.30  0.0003  0.2482  0.0005  0.0005  0.0009  0.0011  0.0017  ±0.49%  1059516
+
+BENCH  Summary
+
+  mri - packages/parser/bench/bench.bench.ts > bench
+    1.03x faster than args-tokens
+    1.16x faster than @clerc/parser
+    2.04x faster than node:util parseArgs
+    3.42x faster than type-flag
+    3.58x faster than minimist
+    3.85x faster than nopt
+    27.11x faster than yargs-parser
+```

package/dist/index.d.ts

@@ -2,6 +2,9 @@
 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] } & {};
@@ -10,14 +13,30 @@ type IsAny<T> = 0 extends 1 & T ? true : false;
 //#region ../utils/src/types/index.d.ts
 type MaybeArray<T> = T | T[];
 //#endregion
+//#region src/iterator.d.ts
+declare const KNOWN_FLAG = "known-flag";
+declare const UNKNOWN_FLAG = "unknown-flag";
+declare const PARAMETER = "parameter";
+//#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.
+  */
+  display?: string;
+}
 /**
 * A callback function to conditionally stop parsing.
 * When it returns true, parsing stops and remaining arguments are preserved in `ignored`.
@@ -27,7 +46,7 @@ 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>];
+type FlagType<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
 interface BaseFlagOptions<T extends FlagType = FlagType> {
   /**
   * The type constructor or a function to convert the string value.
@@ -39,6 +58,8 @@ interface BaseFlagOptions<T extends FlagType = FlagType> {
   alias?: MaybeArray<string>;
   /** The default value of the flag. */
   default?: unknown;
+  /** Whether the flag is required. */
+  required?: boolean;
 }
 type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
   /**
@@ -109,13 +130,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>] | {
+} ? ObjectInputType | InferFlagDefault<T[K], never> : 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 };
+} ? 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.
@@ -124,10 +147,40 @@ type _InferFlags<T extends FlagsDefinition> = { [K in keyof T]: IsTypeAny<T[K]>
 */
 type InferFlags<T extends FlagsDefinition> = Prettify<_InferFlags<T>>;
 //#endregion
-//#region src/iterator.d.ts
-declare const KNOWN_FLAG = "known-flag";
-declare const UNKNOWN_FLAG = "unknown-flag";
-declare const PARAMETER = "parameter";
+//#region src/flag-types.d.ts
+/**
+* Creates a Enum 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 TypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
+*
+* @example
+* ```typescript
+* const format = Enum(['json', 'yaml', 'xml']);
+* // Help output will show: json | yaml | xml
+* ```
+*/
+declare function Enum<T extends string>(...values: T[]): TypeFunction<T>;
+/**
+* Creates a range type function that validates the input is a number within the specified range.
+*
+* @param min - The minimum acceptable value (inclusive)
+* @param max - The maximum acceptable value (inclusive)
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value is not a number or is outside the specified range
+*/
+declare function Range(min: number, max: number): TypeFunction<number>;
+/**
+* Creates a regex type function that validates the input against the provided pattern.
+*
+* @param pattern - The regular expression pattern to validate against
+* @param description - Optional description for display purposes
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value does not match the regex pattern
+*/
+declare function Regex(pattern: RegExp, description?: string): TypeFunction<string>;
 //#endregion
 //#region src/parse.d.ts
 declare const DOUBLE_DASH = "--";
@@ -137,4 +190,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, FlagDefaultValue, FlagDefinitionValue, FlagOptions, FlagType, FlagTypeFunction, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, UNKNOWN_FLAG, createParser, parse };
+export { BaseFlagOptions, DOUBLE_DASH, Enum, FlagDefaultValue, FlagDefaultValueFunction, FlagDefinitionValue, FlagOptions, FlagType, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, MissingRequiredFlagError, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, Range, RawInputType, Regex, TypeFunction, UNKNOWN_FLAG, createParser, parse };

package/dist/index.js

@@ -5,6 +5,70 @@ 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
+/**
+* Creates a Enum 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 TypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
+*
+* @example
+* ```typescript
+* const format = Enum(['json', 'yaml', 'xml']);
+* // Help output will show: json | yaml | xml
+* ```
+*/
+function Enum(...values) {
+	const fn = ((value) => {
+		if (!values.includes(value)) throw new Error(`Invalid value: ${value}. Must be one of: ${values.join(", ")}`);
+		return value;
+	});
+	fn.display = values.join(" | ");
+	return fn;
+}
+/**
+* Creates a range type function that validates the input is a number within the specified range.
+*
+* @param min - The minimum acceptable value (inclusive)
+* @param max - The maximum acceptable value (inclusive)
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value is not a number or is outside the specified range
+*/
+function Range(min, max) {
+	const fn = ((value) => {
+		const num = Number(value);
+		if (Number.isNaN(num) || num < min || num > max) throw new Error(`Invalid value: ${value}. Must be a number between ${min} and ${max}`);
+		return num;
+	});
+	fn.display = `${min}-${max}`;
+	return fn;
+}
+/**
+* Creates a regex type function that validates the input against the provided pattern.
+*
+* @param pattern - The regular expression pattern to validate against
+* @param description - Optional description for display purposes
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value does not match the regex pattern
+*/
+function Regex(pattern, description) {
+	const fn = ((value) => {
+		if (!pattern.test(value)) throw new Error(`Invalid value: ${value}. Must match pattern: ${pattern}`);
+		return value;
+	});
+	fn.display = description ?? pattern.toString();
+	return fn;
+}
 
 //#endregion
 //#region src/iterator.ts
@@ -56,7 +120,8 @@ function iterateArgs(args, result, shouldProcessAsFlag, isKnownFlag, ignore, cal
 }
 
 //#endregion
-//#region ../utils/dist/index.js
+//#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.
@@ -78,10 +143,47 @@ 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.`);
+		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/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)
@@ -132,43 +234,6 @@ 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 = "--";
@@ -304,10 +369,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) throw new MissingRequiredFlagError(key);
 		}
 		return result;
 	};
@@ -316,4 +382,4 @@ function createParser(options = {}) {
 const parse = (args, options = {}) => createParser(options).parse(args);
 
 //#endregion
-export { DOUBLE_DASH, InvalidSchemaError, KNOWN_FLAG, PARAMETER, UNKNOWN_FLAG, createParser, parse };
+export { DOUBLE_DASH, Enum, InvalidSchemaError, KNOWN_FLAG, MissingRequiredFlagError, PARAMETER, Range, Regex, UNKNOWN_FLAG, createParser, parse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/parser",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.20",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc parser",
@@ -50,15 +50,12 @@
     "@types/minimist": "^1.2.5",
     "@types/nopt": "^3.0.32",
     "@types/yargs-parser": "^21.0.3",
+    "args-tokens": "^0.23.0",
     "minimist": "^1.2.8",
     "mri": "^1.2.0",
     "nopt": "^9.0.0",
     "type-flag": "^4.0.3",
     "yargs-parser": "^22.0.0",
-    "@clerc/utils": "1.0.0-beta.2"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "watch": "tsdown --watch"
+    "@clerc/utils": "1.0.0-beta.20"
   }
 }