args-tokens 0.18.0 → 0.19.0

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import { ArgToken, ParserOptions, parseArgs$1 as parseArgs } from "./parser-Bx112mWZ.js";
-import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-D_oOCXlX.js";
+import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-COGeGqd3.js";
 
 //#region src/parse.d.ts
 /**

package/lib/index.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "./parser-Dr4iAGaX.js";
-import { ArgResolveError, resolveArgs } from "./resolver-_BCsM-y_.js";
+import { ArgResolveError, resolveArgs } from "./resolver-Df1uPA8Z.js";
 
 //#region src/parse.ts
 const DEFAULT_OPTIONS = {

package/lib/{resolver-D_oOCXlX.d.ts → resolver-COGeGqd3.d.ts}

@@ -6,7 +6,7 @@ import { ArgToken } from "./parser-Bx112mWZ.js";
 * This schema is similar to the schema of the `node:utils`.
 * difference is that:
 * - `required` property and `description` property are added
-* - `type` is not only 'string' and 'boolean', but also 'number', 'enum' and 'positional' too.
+* - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
 * - `default` property type, not support multiple types
 */
 /**
@@ -14,16 +14,16 @@ import { ArgToken } from "./parser-Bx112mWZ.js";
 * This schema is similar to the schema of the `node:utils`.
 * difference is that:
 * - `required` property and `description` property are added
-* - `type` is not only 'string' and 'boolean', but also 'number', 'enum' and 'positional' too.
+* - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
 * - `default` property type, not support multiple types
 */
 interface ArgSchema {
   /**
   * Type of argument.
   */
-  type: "string" | "boolean" | "number" | "enum" | "positional";
+  type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
   /**
-  * A single character alias for the option.
+  * A single character alias for the argument.
   */
   short?: string;
   /**
@@ -51,6 +51,19 @@ interface ArgSchema {
   * if the type is 'enum', the default value must be one of the allowed values.
   */
   default?: string | boolean | number;
+  /**
+  * Whether to convert the argument name to kebab-case.
+  */
+  toKebab?: true;
+  /**
+  * A function to parse the value of the argument. if the type is 'custom', this function is required.
+  * If argument value will be invalid, this function have to throw an error.
+  * @param value
+  * @returns Parsed value
+  * @throws An Error, If the value is invalid. Error type should be `Error` or extends it
+  */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parse?: (value: string) => any;
 }
 /**
 * An object that contains {@link ArgSchema | argument schema}.
@@ -64,10 +77,12 @@ interface Args {
 type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
   [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
 };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
 /**
 * @internal
 */
-type ExtractOptionValue<A extends ArgSchema> = A["type"] extends "string" ? ResolveOptionValue<A, string> : A["type"] extends "boolean" ? ResolveOptionValue<A, boolean> : A["type"] extends "number" ? ResolveOptionValue<A, number> : A["type"] extends "positional" ? ResolveOptionValue<A, string> : A["type"] extends "enum" ? A["choices"] extends string[] | readonly string[] ? ResolveOptionValue<A, A["choices"][number]> : never : ResolveOptionValue<A, string | boolean | number>;
+type ExtractOptionValue<A extends ArgSchema> = A["type"] extends "string" ? ResolveOptionValue<A, string> : A["type"] extends "boolean" ? ResolveOptionValue<A, boolean> : A["type"] extends "number" ? ResolveOptionValue<A, number> : A["type"] extends "positional" ? ResolveOptionValue<A, string> : A["type"] extends "enum" ? A["choices"] extends string[] | readonly string[] ? ResolveOptionValue<A, A["choices"][number]> : never : A["type"] extends "custom" ? IsFunction<A["parse"]> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A["parse"]>>> : never : ResolveOptionValue<A, string | boolean | number>;
 type ResolveOptionValue<A extends ArgSchema, T> = A["multiple"] extends true ? T[] : T;
 /**
 * @internal
@@ -82,16 +97,21 @@ type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends ke
 */
 interface ResolveArgs {
   /**
-  * Whether to group short options.
+  * Whether to group short arguments.
   * @default false
   * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
   */
-  optionGrouping?: boolean;
+  shortGrouping?: boolean;
   /**
   * Skip positional arguments index.
   * @default -1
   */
   skipPositional?: number;
+  /**
+  * Whether to convert the argument name to kebab-case. This option is applied to all arguments as `toKebab: true`, if set to `true`.
+  * @default false
+  */
+  toKebab?: boolean;
 }
 /**
 * Resolve command line arguments.
@@ -101,8 +121,9 @@ interface ResolveArgs {
 * @returns An object that contains the values of the arguments, positional arguments, rest arguments, and {@link AggregateError | validation errors}.
 */
 declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
-  optionGrouping,
-  skipPositional
+  shortGrouping,
+  skipPositional,
+  toKebab
 }?: ResolveArgs): {
   values: ArgValues<A>;
   positionals: string[];

package/lib/{resolver-_BCsM-y_.js → resolver-Df1uPA8Z.js}

@@ -2,6 +2,9 @@ import { hasLongOptionPrefix, isShortOption } from "./parser-Dr4iAGaX.js";
 
 //#region src/resolver.ts
 const SKIP_POSITIONAL_DEFAULT = -1;
+function kebabnize(str) {
+	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
+}
 /**
 * Resolve command line arguments.
 * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
@@ -9,7 +12,7 @@ const SKIP_POSITIONAL_DEFAULT = -1;
 * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
 * @returns An object that contains the values of the arguments, positional arguments, rest arguments, and {@link AggregateError | validation errors}.
 */
-function resolveArgs(args, tokens, { optionGrouping = false, skipPositional = SKIP_POSITIONAL_DEFAULT } = {}) {
+function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKIP_POSITIONAL_DEFAULT, toKebab = false } = {}) {
 	const skipPositionalIndex = typeof skipPositional === "number" ? Math.max(skipPositional, SKIP_POSITIONAL_DEFAULT) : SKIP_POSITIONAL_DEFAULT;
 	const rest = [];
 	const optionTokens = [];
@@ -68,7 +71,7 @@ function resolveArgs(args, tokens, { optionGrouping = false, skipPositional = SK
 				else currentLongOption = { ...token };
 				applyShortOptionValue();
 			} else if (isShortOption(token.rawName)) if (currentShortOption) {
-				if (currentShortOption.index === token.index) if (optionGrouping) {
+				if (currentShortOption.index === token.index) if (shortGrouping) {
 					currentShortOption.value = token.value;
 					optionTokens.push({ ...currentShortOption });
 					currentShortOption = { ...token };
@@ -115,48 +118,43 @@ function resolveArgs(args, tokens, { optionGrouping = false, skipPositional = SK
 		return Math.min(skipPositionalIndex, positionalItemCount);
 	}
 	let positionalsCount = 0;
-	for (const [option, schema] of Object.entries(args)) {
+	for (const [rawArg, schema] of Object.entries(args)) {
+		const arg = toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
 		if (schema.required) {
 			const found = optionTokens.find((token) => {
-				return schema.short && token.name === schema.short || token.rawName && hasLongOptionPrefix(token.rawName) && token.name === option;
+				return schema.short && token.name === schema.short || token.rawName && hasLongOptionPrefix(token.rawName) && token.name === arg;
 			});
 			if (!found) {
-				errors.push(createRequireError(option, schema));
+				errors.push(createRequireError(arg, schema));
 				continue;
 			}
 		}
 		if (schema.type === "positional") {
 			if (skipPositionalIndex > SKIP_POSITIONAL_DEFAULT) while (positionalsCount <= getPositionalSkipIndex()) positionalsCount++;
 			const positional = positionalTokens[positionalsCount];
-			if (positional != null) values[option] = positional.value;
-			else errors.push(createRequireError(option, schema));
+			if (positional != null) values[rawArg] = positional.value;
+			else errors.push(createRequireError(arg, schema));
 			positionalsCount++;
 			continue;
 		}
 		for (let i = 0; i < optionTokens.length; i++) {
 			const token = optionTokens[i];
-			if (checkTokenName(option, schema, token) && token.rawName != void 0 && hasLongOptionPrefix(token.rawName) || schema.short === token.name && token.rawName != void 0 && isShortOption(token.rawName)) {
-				const invalid = validateRequire(token, option, schema);
+			if (checkTokenName(arg, schema, token) && token.rawName != void 0 && hasLongOptionPrefix(token.rawName) || schema.short === token.name && token.rawName != void 0 && isShortOption(token.rawName)) {
+				const invalid = validateRequire(token, arg, schema);
 				if (invalid) {
 					errors.push(invalid);
 					continue;
 				}
 				if (schema.type === "boolean") token.value = void 0;
-				else {
-					const invalid$1 = validateValue(token, option, schema);
-					if (invalid$1) {
-						errors.push(invalid$1);
-						continue;
-					}
-				}
-				if (schema.multiple) {
-					values[option] ||= [];
-					values[option].push(resolveArgumentValue(token, schema));
-				} else values[option] = resolveArgumentValue(token, schema);
-				continue;
+				const [parsedValue, error] = parse(token, arg, schema);
+				if (error) errors.push(error);
+				else if (schema.multiple) {
+					values[rawArg] ||= [];
+					values[rawArg].push(parsedValue);
+				} else values[rawArg] = parsedValue;
 			}
 		}
-		if (values[option] == null && schema.default != null) values[option] = schema.default;
+		if (values[rawArg] == null && schema.default != null) values[rawArg] = schema.default;
 	}
 	return {
 		values,
@@ -165,6 +163,29 @@ function resolveArgs(args, tokens, { optionGrouping = false, skipPositional = SK
 		error: errors.length > 0 ? new AggregateError(errors) : void 0
 	};
 }
+function parse(token, option, schema) {
+	switch (schema.type) {
+		case "string": return typeof token.value === "string" ? [token.value || schema.default, void 0] : [void 0, createTypeError(option, schema)];
+		case "boolean": return token.value ? [token.value || schema.default, void 0] : [!(schema.negatable && token.name.startsWith("no-")), void 0];
+		case "number": {
+			if (!isNumeric(token.value)) return [void 0, createTypeError(option, schema)];
+			return token.value ? [+token.value, void 0] : [+(schema.default || ""), void 0];
+		}
+		case "enum": {
+			if (schema.choices && !schema.choices.includes(token.value)) return [void 0, new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be chosen from '${schema.type}' [${schema.choices.map((c) => JSON.stringify(c)).join(", ")}] values`, option, "type", schema)];
+			return [token.value || schema.default, void 0];
+		}
+		case "custom": {
+			if (typeof schema.parse !== "function") throw new TypeError(`argument '${option}' should have a 'parse' function`);
+			try {
+				return [schema.parse(token.value || String(schema.default || "")), void 0];
+			} catch (error) {
+				return [void 0, error];
+			}
+		}
+		default: throw new Error(`Unsupported argument type '${schema.type}' for option '${option}'`);
+	}
+}
 function createRequireError(option, schema) {
 	const message = schema.type === "positional" ? `Positional argument '${option}' is required` : `Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`;
 	return new ArgResolveError(message, option, "required", schema);
@@ -187,33 +208,12 @@ var ArgResolveError = class extends Error {
 function validateRequire(token, option, schema) {
 	if (schema.required && schema.type !== "boolean" && !token.value) return createRequireError(option, schema);
 }
-function validateValue(token, option, schema) {
-	switch (schema.type) {
-		case "number": {
-			if (!isNumeric(token.value)) return createTypeError(option, schema);
-			break;
-		}
-		case "string": {
-			if (typeof token.value !== "string") return createTypeError(option, schema);
-			break;
-		}
-		case "enum": {
-			if (schema.choices && !schema.choices.includes(token.value)) return new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be chosen from '${schema.type}' [${schema.choices.map((c) => JSON.stringify(c)).join(", ")}] values`, option, "type", schema);
-			break;
-		}
-	}
-}
 function isNumeric(str) {
 	return str.trim() !== "" && !isNaN(str);
 }
 function createTypeError(option, schema) {
 	return new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be '${schema.type}'`, option, "type", schema);
 }
-function resolveArgumentValue(token, schema) {
-	if (token.value) return schema.type === "number" ? +token.value : token.value;
-	if (schema.type === "boolean") return schema.negatable && token.name.startsWith("no-") ? false : true;
-	return schema.type === "number" ? +(schema.default || "") : schema.default;
-}
 
 //#endregion
 export { ArgResolveError, resolveArgs };

package/lib/resolver.d.ts

@@ -1,3 +1,3 @@
 import "./parser-Bx112mWZ.js";
-import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-D_oOCXlX.js";
+import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-COGeGqd3.js";
 export { ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs };

package/lib/resolver.js

@@ -1,4 +1,4 @@
 import "./parser-Dr4iAGaX.js";
-import { ArgResolveError, resolveArgs } from "./resolver-_BCsM-y_.js";
+import { ArgResolveError, resolveArgs } from "./resolver-Df1uPA8Z.js";
 
 export { ArgResolveError, resolveArgs };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -69,7 +69,7 @@
     "@kazupon/eslint-config": "^0.29.0",
     "@kazupon/prettier-config": "^0.1.1",
     "@types/node": "^22.15.21",
-    "@typescript/native-preview": "7.0.0-dev.20250522.2",
+    "@typescript/native-preview": "7.0.0-dev.20250525.1",
     "@vitest/eslint-plugin": "^1.2.0",
     "bumpp": "^10.1.1",
     "deno": "^2.3.3",
@@ -91,7 +91,8 @@
     "tsdown": "^0.12.1",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.32.1",
-    "vitest": "^3.1.4"
+    "vitest": "^3.1.4",
+    "zod": "^3.25.28"
   },
   "prettier": "@kazupon/prettier-config",
   "lint-staged": {
@@ -124,7 +125,7 @@
     "lint:knip": "knip",
     "lint:prettier": "prettier . --check",
     "release": "bumpp --commit \"release: v%s\" --all --push --tag",
-    "test": "vitest run",
+    "test": "vitest run --typecheck",
     "typecheck": "pnpm run --parallel --color \"/^typecheck:/\"",
     "typecheck:deno": "deno check src",
     "typecheck:tsc": "tsgo --noEmit"