args-tokens 0.18.0 → 0.20.0

package/lib/index.d.ts

@@ -1,10 +1,8 @@
-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 { ArgToken, ParserOptions, parseArgs$1 as parseArgs } from "./parser-FiQIAw-2.js";
+import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-U72Jg6Ll.js";
 
 //#region src/parse.d.ts
-/**
-* Parse options for {@link parse} function.
-*/
+
 /**
 * Parse options for {@link parse} function.
 */
@@ -54,5 +52,6 @@ type ParsedArgs<A extends Args> = {
 * @param options - parse options, about details see {@link ParseOptions}
 * @returns An object that contains the values of the arguments, positional arguments, {@link AggregateError | validation errors}, and {@link ArgToken | argument tokens}.
 */
-declare function parse<A extends Args>(args: string[], options?: ParseOptions<A>): ParsedArgs<A>; //#endregion
+declare function parse<A extends Args>(args: string[], options?: ParseOptions<A>): ParsedArgs<A>;
+//#endregion
 export { ArgResolveError, ArgResolveErrorType, ArgSchema, ArgToken, ArgValues, Args, ParseOptions, ParsedArgs, ParserOptions, ResolveArgs, parse, parseArgs, resolveArgs };

package/lib/index.js

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

package/lib/{parser-Bx112mWZ.d.ts → parser-FiQIAw-2.d.ts}

@@ -86,5 +86,6 @@ declare function isShortOption(arg: string): boolean;
 * @param arg the argument to check
 * @returns whether `arg` is a long option prefix.
 */
-declare function hasLongOptionPrefix(arg: string): boolean; //#endregion
+declare function hasLongOptionPrefix(arg: string): boolean;
+//#endregion
 export { ArgToken, ParserOptions, hasLongOptionPrefix as hasLongOptionPrefix$1, isShortOption as isShortOption$1, parseArgs as parseArgs$1 };

package/lib/parser.d.ts

@@ -1,2 +1,2 @@
-import { ArgToken, ParserOptions, hasLongOptionPrefix$1 as hasLongOptionPrefix, isShortOption$1 as isShortOption, parseArgs$1 as parseArgs } from "./parser-Bx112mWZ.js";
+import { ArgToken, ParserOptions, hasLongOptionPrefix$1 as hasLongOptionPrefix, isShortOption$1 as isShortOption, parseArgs$1 as parseArgs } from "./parser-FiQIAw-2.js";
 export { ArgToken, ParserOptions, hasLongOptionPrefix, isShortOption, parseArgs };

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

@@ -1,4 +1,5 @@
 import { hasLongOptionPrefix, isShortOption } from "./parser-Dr4iAGaX.js";
+import { kebabnize } from "./utils-N7UlhLbz.js";
 
 //#region src/resolver.ts
 const SKIP_POSITIONAL_DEFAULT = -1;
@@ -9,7 +10,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 +69,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 +116,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 +161,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 +206,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_oOCXlX.d.ts → resolver-U72Jg6Ll.d.ts}

@@ -1,29 +1,22 @@
-import { ArgToken } from "./parser-Bx112mWZ.js";
+import { ArgToken } from "./parser-FiQIAw-2.js";
 
 //#region src/resolver.d.ts
+
 /**
 * An argument schema
 * 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.
-* - `default` property type, not support multiple types
-*/
-/**
-* An argument schema
-* 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 +44,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,34 +70,45 @@ 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
 */
-type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, "default"> & FilterArgs<A, V, "required"> extends infer P ? { [K in keyof P]: P[K] } : never;
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, "default"> & FilterArgs<A, V, "required"> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
 /**
 * @internal
 */
 type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K] extends {} ? Arg : never]: V[Arg] };
 /**
+* @internal
+*/
+type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]["type"] extends "positional" ? Arg : never]: V[Arg] };
+/**
 * An arguments for {@link resolveArgs | resolve arguments}.
 */
 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 +118,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[];
@@ -123,6 +141,5 @@ declare class ArgResolveError extends Error {
   type: ArgResolveErrorType;
   constructor(message: string, name: string, type: ArgResolveErrorType, schema: ArgSchema);
 }
-
 //#endregion
-export { ArgResolveError as ArgResolveError$1, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs as resolveArgs$1 };
+export { ArgResolveError as ArgResolveError$1, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs as resolveArgs$1 };

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";
-export { ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs };
+import "./parser-FiQIAw-2.js";
+import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-U72Jg6Ll.js";
+export { ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs };

package/lib/resolver.js

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

package/lib/utils-N7UlhLbz.js

@@ -0,0 +1,18 @@
+//#region src/utils.ts
+/**
+* Entry point of utils.
+*
+* Note that this entry point is used by gunshi to import utility functions.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+function kebabnize(str) {
+	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
+}
+
+//#endregion
+export { kebabnize };

package/lib/utils.d.ts

@@ -0,0 +1,15 @@
+//#region src/utils.d.ts
+/**
+* Entry point of utils.
+*
+* Note that this entry point is used by gunshi to import utility functions.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+declare function kebabnize(str: string): string;
+//#endregion
+export { kebabnize };

package/lib/utils.js

@@ -0,0 +1,3 @@
+import { kebabnize } from "./utils-N7UlhLbz.js";
+
+export { kebabnize };

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.20.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -68,11 +68,11 @@
     "@eslint/markdown": "^6.4.0",
     "@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",
-    "@vitest/eslint-plugin": "^1.2.0",
+    "@types/node": "^22.15.27",
+    "@typescript/native-preview": "7.0.0-dev.20250529.1",
+    "@vitest/eslint-plugin": "^1.2.1",
     "bumpp": "^10.1.1",
-    "deno": "^2.3.3",
+    "deno": "^2.3.4",
     "eslint": "^9.27.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-jsonc": "^2.20.1",
@@ -83,15 +83,16 @@
     "gh-changelogen": "^0.2.8",
     "jsr": "^0.13.4",
     "jsr-exports-lint": "^0.4.0",
-    "knip": "^5.57.1",
-    "lint-staged": "^15.5.2",
+    "knip": "^5.59.1",
+    "lint-staged": "^16.0.0",
     "mitata": "^1.0.34",
-    "pkg-pr-new": "^0.0.50",
+    "pkg-pr-new": "^0.0.51",
     "prettier": "^3.5.3",
-    "tsdown": "^0.12.1",
+    "tsdown": "^0.12.4",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.1",
-    "vitest": "^3.1.4"
+    "typescript-eslint": "^8.33.0",
+    "vitest": "^3.1.4",
+    "zod": "^3.25.41"
   },
   "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"