args-tokens 0.22.1 → 0.22.2

package/README.md

@@ -302,6 +302,237 @@ const tokens = parseArgs(['-a=1'], { allowCompatible: true }) // add `allowCompa
 deepStrictEqual(tokensNode, tokens)
 ```
 
+## ArgSchema Reference
+
+The `ArgSchema` interface defines the configuration for command-line arguments. This schema is similar to Node.js `util.parseArgs` but with extended features.
+
+### Schema Properties
+
+#### `type` (required)
+
+Type of the argument value:
+
+- `'string'`: Text value (default if not specified)
+- `'boolean'`: True/false flag (can be negatable with `--no-` prefix)
+- `'number'`: Numeric value (parsed as integer or float)
+- `'enum'`: One of predefined string values (requires `choices` property)
+- `'positional'`: Non-option argument by position
+- `'custom'`: Custom parsing with user-defined `parse` function
+
+<!-- eslint-skip -->
+
+```js
+{
+  name: { type: 'string' },        // --name value
+  verbose: { type: 'boolean' },     // --verbose or --no-verbose
+  port: { type: 'number' },         // --port 3000
+  level: { type: 'enum', choices: ['debug', 'info'] },
+  file: { type: 'positional' },     // first positional arg
+  config: { type: 'custom', parse: JSON.parse }
+}
+```
+
+#### `short` (optional)
+
+Single character alias for the long option name. Allows users to use `-x` instead of `--extended-option`.
+
+<!-- eslint-skip -->
+
+```js
+{
+  verbose: {
+    type: 'boolean',
+    short: 'v'  // Enables both --verbose and -v
+  },
+  port: {
+    type: 'number',
+    short: 'p'  // Enables both --port 3000 and -p 3000
+  }
+}
+```
+
+#### `description` (optional)
+
+Human-readable description used for help text generation and documentation.
+
+<!-- eslint-skip -->
+
+```js
+{
+  config: {
+    type: 'string',
+    description: 'Path to configuration file'
+  },
+  timeout: {
+    type: 'number',
+    description: 'Request timeout in milliseconds'
+  }
+}
+```
+
+#### `required` (optional)
+
+Marks the argument as required. When `true`, the argument must be provided or an `ArgResolveError` will be thrown.
+
+<!-- eslint-skip -->
+
+```js
+{
+  input: {
+    type: 'string',
+    required: true,  // Must be provided: --input file.txt
+    description: 'Input file path'
+  },
+  source: {
+    type: 'positional',
+    required: true   // First positional argument must exist
+  }
+}
+```
+
+#### `multiple` (optional)
+
+Allows the argument to accept multiple values. The resolved value becomes an array.
+
+- For options: can be specified multiple times (`--tag foo --tag bar`)
+- For positional: collects remaining positional arguments
+
+<!-- eslint-skip -->
+
+```js
+{
+  tags: {
+    type: 'string',
+    multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+    description: 'Tags to apply'
+  },
+  files: {
+    type: 'positional',
+    multiple: true   // Collects all remaining positional args
+  }
+}
+```
+
+#### `negatable` (optional)
+
+Enables negation for boolean arguments using `--no-` prefix. Only applicable to `type: 'boolean'`.
+
+<!-- eslint-skip -->
+
+```js
+{
+  color: {
+    type: 'boolean',
+    negatable: true,
+    default: true,
+    description: 'Enable colorized output'
+  }
+  // Usage: --color (true), --no-color (false)
+}
+```
+
+#### `choices` (optional)
+
+Array of allowed string values for enum-type arguments. Required when `type: 'enum'`.
+
+<!-- eslint-skip -->
+
+```js
+{
+  logLevel: {
+    type: 'enum',
+    choices: ['debug', 'info', 'warn', 'error'],
+    default: 'info',
+    description: 'Logging verbosity level'
+  },
+  format: {
+    type: 'enum',
+    choices: ['json', 'yaml', 'toml'],
+    description: 'Output format'
+  }
+}
+```
+
+#### `default` (optional)
+
+Default value used when the argument is not provided. The type must match the argument's `type` property.
+
+<!-- eslint-skip -->
+
+```js
+{
+  host: {
+    type: 'string',
+    default: 'localhost'  // string default
+  },
+  verbose: {
+    type: 'boolean',
+    default: false        // boolean default
+  },
+  port: {
+    type: 'number',
+    default: 8080         // number default
+  },
+  level: {
+    type: 'enum',
+    choices: ['low', 'high'],
+    default: 'low'        // must be in choices
+  }
+}
+```
+
+#### `toKebab` (optional)
+
+Converts the argument name from camelCase to kebab-case for CLI usage. A property like `maxCount` becomes available as `--max-count`.
+
+<!-- eslint-skip -->
+
+```js
+{
+  maxRetries: {
+    type: 'number',
+    toKebab: true,        // Accessible as --max-retries
+    description: 'Maximum retry attempts'
+  },
+  enableLogging: {
+    type: 'boolean',
+    toKebab: true         // Accessible as --enable-logging
+  }
+}
+```
+
+#### `parse` (optional)
+
+Custom parsing function for `type: 'custom'` arguments. Required when `type: 'custom'`. Should throw an Error if parsing fails.
+
+<!-- eslint-skip -->
+
+```js
+{
+  config: {
+    type: 'custom',
+    parse: (value) => {
+      try {
+        return JSON.parse(value)  // Parse JSON config
+      } catch {
+        throw new Error('Invalid JSON configuration')
+      }
+    },
+    description: 'JSON configuration object'
+  },
+  date: {
+    type: 'custom',
+    parse: (value) => {
+      const date = new Date(value)
+      if (isNaN(date.getTime())) {
+        throw new Error('Invalid date format')
+      }
+      return date
+    }
+  }
+}
+```
+
 ## 🙌 Contributing guidelines
 
 If you are interested in contributing to `args-tokens`, I highly recommend checking out [the contributing guidelines](/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](/CONTRIBUTING.md#development-setup)) etc., there.
@@ -319,7 +550,7 @@ The development of Gunish is supported by my OSS sponsors!
 
 <p align="center">
   <a href="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg">
-    <img alt="sponsor src='https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg'/>
+    <img alt="sponsor" src="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg"/>
   </a>
 </p>
 

package/lib/index.d.ts

@@ -1,19 +1,23 @@
-import { ArgToken, ParserOptions, parseArgs$1 as parseArgs } from "./parser-Cbxholql.js";
-import { ArgExplicitlyProvided, ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-BoS-UnqX.js";
+import { ArgToken, ParserOptions, parseArgs$1 as parseArgs } from "./parser-DEYiqyo1.js";
+import { ArgExplicitlyProvided, ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-7JOAwfSr.js";
 
 //#region src/parse.d.ts
 
 /**
  * Parse options for {@link parse} function.
+ *
+ * @typeParam A - {@link Args | Arguments schema}, which is an object that defines the command line arguments.
  */
 interface ParseOptions<A extends Args> extends ParserOptions, ResolveArgs {
   /**
-   * Command line arguments, about details see {@link Args}.
+   * Command line arguments.
    */
   args?: A;
 }
 /**
  * Parsed command line arguments.
+ *
+ * @typeParam A - {@link Args | Arguments schema}, which is an object that defines the command line arguments.
  */
 type ParsedArgs<A extends Args> = {
   /**
@@ -38,13 +42,22 @@ type ParsedArgs<A extends Args> = {
   tokens: ArgToken[];
   /**
    * Explicit provision status, same as `explicit` in {@link resolveArgs}.
+   *
    * Indicates which arguments were explicitly provided vs using default values.
    */
   explicit: ArgExplicitlyProvided<A>;
 };
 /**
  * Parse command line arguments.
+ *
  * This function is a convenient API, that is used {@link parseArgs} and {@link resolveArgs} in internal.
+ *
+ * @typeParam A - {@link Args | Arguments schema}, which is an object that defines the command line arguments.
+ *
+ * @param args - command line arguments
+ * @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}.
+ *
  * @example
  * ```js
  * import { parse } from 'args-tokens'
@@ -53,9 +66,6 @@ type ParsedArgs<A extends Args> = {
  * console.log('values', values)
  * console.log('positionals', positionals)
  * ```
- * @param args - command line arguments
- * @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

package/lib/index.js

@@ -1,6 +1,6 @@
-import { parseArgs } from "./parser-Dr4iAGaX.js";
-import "./utils-N7UlhLbz.js";
-import { ArgResolveError, resolveArgs } from "./resolver-BsDoIgzu.js";
+import { parseArgs } from "./parser-M-ayhS1h.js";
+import "./utils-1LQrGCWG.js";
+import { ArgResolveError, resolveArgs } from "./resolver-DBvNkaE7.js";
 
 //#region src/parse.ts
 const DEFAULT_OPTIONS = {
@@ -15,7 +15,15 @@ const DEFAULT_OPTIONS = {
 };
 /**
 * Parse command line arguments.
+*
 * This function is a convenient API, that is used {@link parseArgs} and {@link resolveArgs} in internal.
+*
+* @typeParam A - {@link Args | Arguments schema}, which is an object that defines the command line arguments.
+*
+* @param args - command line arguments
+* @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}.
+*
 * @example
 * ```js
 * import { parse } from 'args-tokens'
@@ -24,9 +32,6 @@ const DEFAULT_OPTIONS = {
 * console.log('values', values)
 * console.log('positionals', positionals)
 * ```
-* @param args - command line arguments
-* @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}.
 */
 function parse(args, options = {}) {
 	const { args: _args, allowCompatible = false } = options;

package/lib/{parser-Cbxholql.d.ts → parser-DEYiqyo1.d.ts}

@@ -1,6 +1,7 @@
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
+ *
  * @module
  */
 /**
@@ -13,6 +14,7 @@
  */
 /**
  * Argument token Kind.
+ *
  * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
  * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
  * - `positional`: positional token
@@ -54,12 +56,18 @@ interface ArgToken {
 interface ParserOptions {
   /**
    * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode.
+   *
    * @default false
    */
   allowCompatible?: boolean;
 }
 /**
  * Parse command line arguments.
+ *
+ * @param args - command line arguments
+ * @param options - parse options, about details see {@link ParserOptions}
+ * @returns Argument tokens.
+ *
  * @example
  * ```js
  * import { parseArgs } from 'args-tokens' // for Node.js and Bun
@@ -70,21 +78,20 @@ interface ParserOptions {
  * // ...
  * console.log('tokens:', tokens)
  * ```
- * @param args command line arguments
- * @param options parse options
- * @returns Argument tokens.
  */
 declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
 /**
  * Check if `arg` is a short option (e.g. `-f`).
- * @param arg the argument to check
- * @returns whether `arg` is a short option.
+ *
+ * @param arg - An argument to check
+ * @returns Whether `arg` is a short option.
  */
 declare function isShortOption(arg: string): boolean;
 /**
  * Check if `arg` is a long option prefix (e.g. `--`).
- * @param arg the argument to check
- * @returns whether `arg` is a long option prefix.
+ *
+ * @param arg - An argument to check
+ * @returns Whether `arg` is a long option prefix.
  */
 declare function hasLongOptionPrefix(arg: string): boolean;
 //#endregion

package/lib/{parser-Dr4iAGaX.js → parser-M-ayhS1h.js}

@@ -8,6 +8,11 @@ const SHORT_OPTION_PREFIX = HYPHEN_CHAR;
 const LONG_OPTION_PREFIX = "--";
 /**
 * Parse command line arguments.
+*
+* @param args - command line arguments
+* @param options - parse options, about details see {@link ParserOptions}
+* @returns Argument tokens.
+*
 * @example
 * ```js
 * import { parseArgs } from 'args-tokens' // for Node.js and Bun
@@ -18,9 +23,6 @@ const LONG_OPTION_PREFIX = "--";
 * // ...
 * console.log('tokens:', tokens)
 * ```
-* @param args command line arguments
-* @param options parse options
-* @returns Argument tokens.
 */
 function parseArgs(args, options = {}) {
 	const { allowCompatible = false } = options;
@@ -137,16 +139,18 @@ function parseArgs(args, options = {}) {
 }
 /**
 * Check if `arg` is a short option (e.g. `-f`).
-* @param arg the argument to check
-* @returns whether `arg` is a short option.
+*
+* @param arg - An argument to check
+* @returns Whether `arg` is a short option.
 */
 function isShortOption(arg) {
 	return arg.length === 2 && arg.codePointAt(0) === HYPHEN_CODE && arg.codePointAt(1) !== HYPHEN_CODE;
 }
 /**
 * Check if `arg` is a short option group (e.g. `-abc`).
-* @param arg the argument to check
-* @returns whether `arg` is a short option group.
+*
+* @param arg - An argument to check
+* @returns Whether `arg` is a short option group.
 */
 function isShortOptionGroup(arg) {
 	if (arg.length <= 2) return false;
@@ -156,32 +160,36 @@ function isShortOptionGroup(arg) {
 }
 /**
 * Check if `arg` is a long option (e.g. `--foo`).
-* @param arg the argument to check
-* @returns whether `arg` is a long option.
+*
+* @param arg - An argument to check
+* @returns Whether `arg` is a long option.
 */
 function isLongOption(arg) {
 	return hasLongOptionPrefix(arg) && !arg.includes(EQUAL_CHAR, 3);
 }
 /**
 * Check if `arg` is a long option with value (e.g. `--foo=bar`).
-* @param arg the argument to check
-* @returns whether `arg` is a long option.
+*
+* @param arg - An argument to check
+* @returns Whether `arg` is a long option.
 */
 function isLongOptionAndValue(arg) {
 	return hasLongOptionPrefix(arg) && arg.includes(EQUAL_CHAR, 3);
 }
 /**
 * Check if `arg` is a long option prefix (e.g. `--`).
-* @param arg the argument to check
-* @returns whether `arg` is a long option prefix.
+*
+* @param arg - An argument to check
+* @returns Whether `arg` is a long option prefix.
 */
 function hasLongOptionPrefix(arg) {
 	return arg.length > 2 && ~arg.indexOf(LONG_OPTION_PREFIX);
 }
 /**
 * Check if a `value` is an option value.
-* @param value a value to check
-* @returns whether a `value` is an option value.
+*
+* @param value - A value to check
+* @returns Whether a `value` is an option value.
 */
 function hasOptionValue(value) {
 	return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;

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-Cbxholql.js";
+import { ArgToken, ParserOptions, hasLongOptionPrefix$1 as hasLongOptionPrefix, isShortOption$1 as isShortOption, parseArgs$1 as parseArgs } from "./parser-DEYiqyo1.js";
 export { ArgToken, ParserOptions, hasLongOptionPrefix, isShortOption, parseArgs };

package/lib/parser.js

@@ -1,3 +1,3 @@
-import { hasLongOptionPrefix, isShortOption, parseArgs } from "./parser-Dr4iAGaX.js";
+import { hasLongOptionPrefix, isShortOption, parseArgs } from "./parser-M-ayhS1h.js";
 
 export { hasLongOptionPrefix, isShortOption, parseArgs };

package/lib/resolver-7JOAwfSr.d.ts

@@ -0,0 +1,474 @@
+import { ArgToken } from "./parser-DEYiqyo1.js";
+
+//#region src/resolver.d.ts
+
+/**
+ * An argument schema definition for command-line argument parsing.
+ *
+ * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
+ * - Additional `required` and `description` properties
+ * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
+ * - Simplified `default` property (single type, not union types)
+ *
+ * @example
+ * Basic string argument:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'string',
+ *   description: 'Server hostname',
+ *   default: 'localhost'
+ * }
+ * ```
+ *
+ * @example
+ * Required number argument with alias:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'number',
+ *   short: 'p',
+ *   description: 'Port number to listen on',
+ *   required: true
+ * }
+ * ```
+ *
+ * @example
+ * Enum argument with choices:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'enum',
+ *   choices: ['info', 'warn', 'error'],
+ *   description: 'Logging level',
+ *   default: 'info'
+ * }
+ * ```
+ */
+interface ArgSchema {
+  /**
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value (default if not specified)
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   port: { type: 'number' },         // --port 3000
+   *   level: { type: 'enum', choices: ['debug', 'info'] },
+   *   file: { type: 'positional' },     // first positional arg
+   *   config: { type: 'custom', parse: JSON.parse }
+   * }
+   * ```
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
+  /**
+   * Single character alias for the long option name.
+   *
+   * As example, allows users to use `-x` instead of `--extended-option`.
+   * Only valid for non-positional argument types.
+   *
+   * @example
+   * Short alias usage:
+   * ```ts
+   * {
+   *   verbose: {
+   *     type: 'boolean',
+   *     short: 'v'  // Enables both --verbose and -v
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     short: 'p'  // Enables both --port 3000 and -p 3000
+   *   }
+   * }
+   * ```
+   */
+  short?: string;
+  /**
+   * Human-readable description of the argument's purpose.
+   *
+   * Used for help text generation and documentation.
+   * Should be concise but descriptive enough to understand the argument's role.
+   *
+   * @example
+   * Descriptive help text:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'string',
+   *     description: 'Path to configuration file'
+   *   },
+   *   timeout: {
+   *     type: 'number',
+   *     description: 'Request timeout in milliseconds'
+   *   }
+   * }
+   * ```
+   */
+  description?: string;
+  /**
+   * Marks the argument as required.
+   *
+   * When `true`, the argument must be provided by the user.
+   * If missing, an `ArgResolveError` with type 'required' will be thrown.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Required arguments:
+   * ```ts
+   * {
+   *   input: {
+   *     type: 'string',
+   *     required: true,  // Must be provided: --input file.txt
+   *     description: 'Input file path'
+   *   },
+   *   source: {
+   *     type: 'positional',
+   *     required: true   // First positional argument must exist
+   *   }
+   * }
+   * ```
+   */
+  required?: true;
+  /**
+   * Allows the argument to accept multiple values.
+   *
+   * When `true`, the resolved value becomes an array.
+   * For options: can be specified multiple times (--tag foo --tag bar)
+   * For positional: collects remaining positional arguments
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Multiple values:
+   * ```ts
+   * {
+   *   tags: {
+   *     type: 'string',
+   *     multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+   *     description: 'Tags to apply'
+   *   },
+   *   files: {
+   *     type: 'positional',
+   *     multiple: true   // Collects all remaining positional args
+   *   }
+   * }
+   * ```
+   */
+  multiple?: true;
+  /**
+   * Enables negation for boolean arguments using `--no-` prefix.
+   *
+   * When `true`, allows users to explicitly set the boolean to `false`
+   * using `--no-option-name`. When `false` or omitted, only positive
+   * form is available.
+   *
+   * Only applicable to `type: 'boolean'` arguments.
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
+   */
+  negatable?: boolean;
+  /**
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`. The argument value must be one of these choices,
+   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   *
+   * Supports both mutable arrays and readonly arrays for type safety.
+   *
+   * @example
+   * Enum choices:
+   * ```ts
+   * {
+   *   logLevel: {
+   *     type: 'enum',
+   *     choices: ['debug', 'info', 'warn', 'error'] as const,
+   *     default: 'info',
+   *     description: 'Logging verbosity level'
+   *   },
+   *   format: {
+   *     type: 'enum',
+   *     choices: ['json', 'yaml', 'toml'],
+   *     description: 'Output format'
+   *   }
+   * }
+   * ```
+   */
+  choices?: string[] | readonly string[];
+  /**
+   * Default value used when the argument is not provided.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: must be one of the `choices` values
+   * - `positional`/`custom` type: any appropriate default
+   *
+   * @example
+   * Default values by type:
+   * ```ts
+   * {
+   *   host: {
+   *     type: 'string',
+   *     default: 'localhost'  // string default
+   *   },
+   *   verbose: {
+   *     type: 'boolean',
+   *     default: false        // boolean default
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     default: 8080         // number default
+   *   },
+   *   level: {
+   *     type: 'enum',
+   *     choices: ['low', 'high'],
+   *     default: 'low'        // must be in choices
+   *   }
+   * }
+   * ```
+   */
+  default?: string | boolean | number;
+  /**
+   * Converts the argument name from camelCase to kebab-case for CLI usage.
+   *
+   * When `true`, a property like `maxCount` becomes available as `--max-count`.
+   * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
+   *
+   * Can be overridden globally with `resolveArgs({ toKebab: true })`.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Kebab-case conversion:
+   * ```ts
+   * {
+   *   maxRetries: {
+   *     type: 'number',
+   *     toKebab: true,        // Accessible as --max-retries
+   *     description: 'Maximum retry attempts'
+   *   },
+   *   enableLogging: {
+   *     type: 'boolean',
+   *     toKebab: true         // Accessible as --enable-logging
+   *   }
+   * }
+   * ```
+   */
+  toKebab?: true;
+  /**
+   * Custom parsing function for `type: 'custom'` arguments.
+   *
+   * Required when `type: 'custom'`. Receives the raw string value and must
+   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws Error or subclass when value is invalid
+   *
+   * @example
+   * Custom parsing functions:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       try {
+   *         return JSON.parse(value)  // Parse JSON config
+   *       } catch {
+   *         throw new Error('Invalid JSON configuration')
+   *       }
+   *     },
+   *     description: 'JSON configuration object'
+   *   },
+   *   date: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       const date = new Date(value)
+   *       if (isNaN(date.getTime())) {
+   *         throw new Error('Invalid date format')
+   *       }
+   *       return date
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  parse?: (value: string) => any;
+}
+/**
+ * An object that contains {@link ArgSchema | argument schema}.
+ *
+ * This type is used to define the structure and validation rules for command line arguments.
+ */
+interface Args {
+  [option: string]: ArgSchema;
+}
+/**
+ * An object that contains the values of the arguments.
+ *
+ * @typeParam T - Arguments which is an object that defines the command line arguments.
+ */
+type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
+  [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
+};
+type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
+/**
+ * Extracts the value type from the argument schema.
+ *
+ * @typeParam A - Argument schema which is an object that defines command line arguments.
+ *
+ * @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 : 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;
+/**
+ * Resolved argument values.
+ *
+ * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
+ * @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'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
+/**
+ * Filters the arguments based on their default values.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
+ *
+ * @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] };
+/**
+ * Filters positional arguments from the argument schema.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
+ * @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 arguments.
+   *
+   * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
+   *
+   * @default false
+   */
+  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;
+}
+/**
+ * Tracks which arguments were explicitly provided by the user.
+ *
+ * Each property indicates whether the corresponding argument was explicitly
+ * provided (true) or is using a default value or not provided (false).
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ */
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
+/**
+ * Resolve command line arguments.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ *
+ * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
+ * @param tokens - An array of {@link ArgToken | tokens}.
+ * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
+ * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+ *
+ * @example
+ * ```typescript
+ * // passed tokens: --port 3000
+ *
+ * const { values, explicit } = resolveArgs({
+ *   port: {
+ *     type: 'number',
+ *     default: 8080
+ *   },
+ *   host: {
+ *     type: 'string',
+ *     default: 'localhost'
+ *   }
+ * }, parsedTokens)
+ *
+ * values.port // 3000
+ * values.host // 'localhost'
+ *
+ * explicit.port // true (explicitly provided)
+ * explicit.host // false (not provided, fallback to default)
+ * ```
+ */
+declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
+  shortGrouping,
+  skipPositional,
+  toKebab
+}?: ResolveArgs): {
+  values: ArgValues<A>;
+  positionals: string[];
+  rest: string[];
+  error: AggregateError | undefined;
+  explicit: ArgExplicitlyProvided<A>;
+};
+/**
+ * An error type for {@link ArgResolveError}.
+ */
+type ArgResolveErrorType = 'type' | 'required';
+/**
+ * An error that occurs when resolving arguments.
+ * This error is thrown when the argument is not valid.
+ */
+declare class ArgResolveError extends Error {
+  name: string;
+  schema: ArgSchema;
+  type: ArgResolveErrorType;
+  /**
+   * Create an instance of ArgResolveError.
+   *
+   * @param message - the error message
+   * @param name - the name of the argument
+   * @param type - the type of the error, either 'type' or 'required'
+   * @param schema - the argument schema that caused the error
+   */
+  constructor(message: string, name: string, type: ArgResolveErrorType, schema: ArgSchema);
+}
+//#endregion
+export { ArgExplicitlyProvided, ArgResolveError as ArgResolveError$1, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs as resolveArgs$1 };

package/lib/{resolver-BsDoIgzu.js → resolver-DBvNkaE7.js}

@@ -1,10 +1,13 @@
-import { hasLongOptionPrefix, isShortOption } from "./parser-Dr4iAGaX.js";
-import { kebabnize } from "./utils-N7UlhLbz.js";
+import { hasLongOptionPrefix, isShortOption } from "./parser-M-ayhS1h.js";
+import { kebabnize } from "./utils-1LQrGCWG.js";
 
 //#region src/resolver.ts
 const SKIP_POSITIONAL_DEFAULT = -1;
 /**
 * Resolve command line arguments.
+*
+* @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+*
 * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
 * @param tokens - An array of {@link ArgToken | tokens}.
 * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
@@ -230,6 +233,14 @@ var ArgResolveError = class extends Error {
 	name;
 	schema;
 	type;
+	/**
+	* Create an instance of ArgResolveError.
+	*
+	* @param message - the error message
+	* @param name - the name of the argument
+	* @param type - the type of the error, either 'type' or 'required'
+	* @param schema - the argument schema that caused the error
+	*/
 	constructor(message, name, type, schema) {
 		super(message);
 		this.name = name;

package/lib/resolver.d.ts

@@ -1,3 +1,3 @@
-import "./parser-Cbxholql.js";
-import { ArgExplicitlyProvided, ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-BoS-UnqX.js";
+import "./parser-DEYiqyo1.js";
+import { ArgExplicitlyProvided, ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver-7JOAwfSr.js";
 export { ArgExplicitlyProvided, ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs };

package/lib/resolver.js

@@ -1,5 +1,5 @@
-import "./parser-Dr4iAGaX.js";
-import "./utils-N7UlhLbz.js";
-import { ArgResolveError, resolveArgs } from "./resolver-BsDoIgzu.js";
+import "./parser-M-ayhS1h.js";
+import "./utils-1LQrGCWG.js";
+import { ArgResolveError, resolveArgs } from "./resolver-DBvNkaE7.js";
 
 export { ArgResolveError, resolveArgs };

package/lib/{utils-N7UlhLbz.js → utils-1LQrGCWG.js}

@@ -10,6 +10,12 @@
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+/**
+* Convert a string to kebab-case.
+*
+* @param str - A string to convert
+* @returns Converted string into kebab-case.
+*/
 function kebabnize(str) {
 	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
 }

package/lib/utils.d.ts

@@ -10,6 +10,12 @@
  * @author kazuya kawaguchi (a.k.a. kazupon)
  * @license MIT
  */
+/**
+ * Convert a string to kebab-case.
+ *
+ * @param str - A string to convert
+ * @returns Converted string into kebab-case.
+ */
 declare function kebabnize(str: string): string;
 //#endregion
 export { kebabnize };

package/lib/utils.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -72,15 +72,16 @@
   },
   "devDependencies": {
     "@eslint/markdown": "^6.6.0",
-    "@kazupon/eslint-config": "^0.33.0",
+    "@kazupon/eslint-config": "^0.33.3",
     "@kazupon/prettier-config": "^0.1.1",
     "@types/node": "^22.17.0",
-    "@typescript/native-preview": "7.0.0-dev.20250731.1",
+    "@typescript/native-preview": "7.0.0-dev.20250801.1",
     "@vitest/eslint-plugin": "^1.3.4",
-    "bumpp": "^10.2.1",
+    "bumpp": "^10.2.2",
     "deno": "^2.4.3",
     "eslint": "^9.32.0",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^52.0.2",
     "eslint-plugin-jsonc": "^2.20.1",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-regexp": "^2.9.0",
@@ -94,8 +95,8 @@
     "mitata": "^1.0.34",
     "pkg-pr-new": "^0.0.54",
     "prettier": "^3.6.2",
-    "tsdown": "^0.13.0",
-    "typescript": "^5.8.3",
+    "tsdown": "^0.13.1",
+    "typescript": "^5.9.2",
     "typescript-eslint": "^8.38.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.14"

package/lib/resolver-BoS-UnqX.d.ts

@@ -1,173 +0,0 @@
-import { ArgToken } from "./parser-Cbxholql.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', 'positional', 'custom' too.
- * - `default` property type, not support multiple types
- */
-interface ArgSchema {
-  /**
-   * Type of argument.
-   */
-  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
-  /**
-   * A single character alias for the argument.
-   */
-  short?: string;
-  /**
-   * A description of the argument.
-   */
-  description?: string;
-  /**
-   * Whether the argument is required or not.
-   */
-  required?: true;
-  /**
-   * Whether the argument allow multiple values or not.
-   */
-  multiple?: true;
-  /**
-   * Whether the negatable option for `boolean` type
-   */
-  negatable?: boolean;
-  /**
-   * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
-   */
-  choices?: string[] | readonly string[];
-  /**
-   * The default value of the argument.
-   * 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
-   */
-  parse?: (value: string) => any;
-}
-/**
- * An object that contains {@link ArgSchema | argument schema}.
- */
-interface Args {
-  [option: string]: ArgSchema;
-}
-/**
- * An object that contains the values of the arguments.
- */
-type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
-  [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
-};
-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 : 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'> & 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 arguments.
-   * @default false
-   * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
-   */
-  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;
-}
-/**
- * Tracks which arguments were explicitly provided by the user.
- *
- * Each property indicates whether the corresponding argument was explicitly
- * provided (true) or is using a default value or not provided (false).
- */
-type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
-/**
- * Resolve command line arguments.
- * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
- * @param tokens - An array of {@link ArgToken | tokens}.
- * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
- * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
- *
- * @example
- * ```typescript
- * // passed tokens: --port 3000
- *
- * const { values, explicit } = resolveArgs({
- *   port: {
- *     type: 'number',
- *     default: 8080
- *   },
- *   host: {
- *     type: 'string',
- *     default: 'localhost'
- *   }
- * }, parsedTokens)
- *
- * values.port // 3000
- * values.host // 'localhost'
- *
- * explicit.port // true (explicitly provided)
- * explicit.host // false (not provided, fallback to default)
- * ```
- */
-declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
-  shortGrouping,
-  skipPositional,
-  toKebab
-}?: ResolveArgs): {
-  values: ArgValues<A>;
-  positionals: string[];
-  rest: string[];
-  error: AggregateError | undefined;
-  explicit: ArgExplicitlyProvided<A>;
-};
-/**
- * An error type for {@link ArgResolveError}.
- */
-type ArgResolveErrorType = 'type' | 'required';
-/**
- * An error that occurs when resolving arguments.
- * This error is thrown when the argument is not valid.
- */
-declare class ArgResolveError extends Error {
-  name: string;
-  schema: ArgSchema;
-  type: ArgResolveErrorType;
-  constructor(message: string, name: string, type: ArgResolveErrorType, schema: ArgSchema);
-}
-//#endregion
-export { ArgExplicitlyProvided, ArgResolveError as ArgResolveError$1, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs as resolveArgs$1 };