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

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

@@ -3,6 +3,23 @@ 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;
@@ -17,7 +34,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`.
@@ -137,4 +160,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, Choices, DOUBLE_DASH, FlagDefaultValue, FlagDefinitionValue, FlagOptions, FlagType, FlagTypeFunction, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, UNKNOWN_FLAG, createParser, parse };

package/dist/index.js

@@ -6,6 +6,31 @@ 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";
@@ -316,4 +341,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 { Choices, 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.2",
+  "version": "1.0.0-beta.3",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc parser",
@@ -50,12 +50,13 @@
     "@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"
+    "@clerc/utils": "1.0.0-beta.3"
   },
   "scripts": {
     "build": "tsdown",