args-tokens 0.22.2 → 0.23.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![Version][npm-version-src]][npm-version-href]
 [![JSR][jsr-src]][jsr-href]
-[![InstallSize][install-size-src]][install-size-src]
+[![InstallSize][install-size-src]][install-size-href]
 [![CI][ci-src]][ci-href]
 
 > [`parseArgs` tokens](https://nodejs.org/api/util.html#parseargs-tokens) compatibility and more high-performance parser
@@ -95,7 +95,7 @@ Breaking changes might not follow SemVer, please pin Vitest's version when using
 
 ```
 
-## ❓ What's different about parseArgs tokens?
+## ❓ What's different about `parseArgs` tokens?
 
 The token output for the short option `-x=v` is different:
 
@@ -184,7 +184,7 @@ bun add args-tokens
 
 ### Parse args to tokens
 
-`parseArgs` will transform arguments into tokens. This function is useful if you want to analyze arguments yourself based on the tokens. It's faster than `node:util` parseArgs because it only focuses on token transformation.
+`parseArgs` will transform arguments into tokens. This function is useful if you want to analyze arguments yourself based on the tokens. It's faster than `parseArgs` of `node:util` because it only focuses on token transformation.
 
 ```js
 import { parseArgs } from 'args-tokens' // for Node.js and Bun
@@ -239,7 +239,7 @@ console.log('positionals:', positionals)
 
 ## Convenient argument parsing
 
-Using the `parse,` you can transform the arguments into tokens and resolve the argument values once:
+Using the `parse` you can transform the arguments into tokens and resolve the argument values once:
 
 ```js
 import { parse } from 'args-tokens' // for Node.js and Bun
@@ -302,7 +302,7 @@ const tokens = parseArgs(['-a=1'], { allowCompatible: true }) // add `allowCompa
 deepStrictEqual(tokensNode, tokens)
 ```
 
-## ArgSchema Reference
+## `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.
 
@@ -533,6 +533,44 @@ Custom parsing function for `type: 'custom'` arguments. Required when `type: 'cu
 }
 ```
 
+#### `conflicts` (optional)
+
+Specifies other options that cannot be used together with this option. When conflicting options are provided together, an `ArgResolveError` will be thrown.
+
+Conflicts only need to be defined on one side - if option A defines a conflict with option B, the conflict is automatically detected when both are used.
+
+<!-- eslint-skip -->
+
+```js
+{
+  // Single conflict
+  port: {
+    type: 'number',
+    conflicts: 'socket'  // Cannot use --port with --socket
+  },
+  socket: {
+    type: 'string'
+    // No need to define conflicts: 'port' here
+  }
+}
+
+// Multiple conflicts (mutually exclusive options)
+{
+  tcp: {
+    type: 'number',
+    conflicts: ['udp', 'unix']  // Cannot use with --udp or --unix
+  },
+  udp: {
+    type: 'number',
+    conflicts: ['tcp', 'unix']
+  },
+  unix: {
+    type: 'string',
+    conflicts: ['tcp', 'udp']
+  }
+}
+```
+
 ## 🙌 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.

package/lib/index.d.ts

@@ -1,5 +1,5 @@
-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";
+import { ArgToken, ParserOptions, parseArgs } from "./parser-C6MbpZjd.js";
+import { ArgExplicitlyProvided, ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs } from "./resolver-D64nGlCD.js";
 
 //#region src/parse.d.ts
 

package/lib/index.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "./parser-M-ayhS1h.js";
 import "./utils-1LQrGCWG.js";
-import { ArgResolveError, resolveArgs } from "./resolver-DBvNkaE7.js";
+import { ArgResolveError, resolveArgs } from "./resolver-D0hj6HpX.js";
 
 //#region src/parse.ts
 const DEFAULT_OPTIONS = {

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

@@ -95,4 +95,4 @@ declare function isShortOption(arg: string): boolean;
  */
 declare function hasLongOptionPrefix(arg: string): boolean;
 //#endregion
-export { ArgToken, ParserOptions, hasLongOptionPrefix as hasLongOptionPrefix$1, isShortOption as isShortOption$1, parseArgs as parseArgs$1 };
+export { ArgToken, ParserOptions, hasLongOptionPrefix, isShortOption, parseArgs };

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

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

@@ -134,6 +134,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	const values = Object.create(null);
 	const errors = [];
 	const explicit = Object.create(null);
+	const actualInputNames = /* @__PURE__ */ new Map();
 	function checkTokenName(option, schema, token) {
 		return token.name === (schema.type === "boolean" ? schema.negatable && token.name?.startsWith("no-") ? `no-${option}` : option : option);
 	}
@@ -179,6 +180,8 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 					continue;
 				}
 				explicit[rawArg] = true;
+				const actualInputName = isShortOption(token.rawName) ? `-${token.name}` : `--${arg}`;
+				actualInputNames.set(rawArg, actualInputName);
 				if (schema.type === "boolean") token.value = void 0;
 				const [parsedValue, error] = parse(token, arg, schema);
 				if (error) errors.push(error);
@@ -190,6 +193,8 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 		}
 		if (values[rawArg] == null && schema.default != null) values[rawArg] = schema.default;
 	}
+	const conflictErrors = checkConflicts(args, explicit, toKebab, actualInputNames);
+	errors.push(...conflictErrors);
 	return {
 		values,
 		positionals: positionalTokens.map((token) => token.value),
@@ -202,22 +207,19 @@ 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": {
+		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": {
+		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": {
+		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}'`);
 	}
 }
@@ -234,7 +236,7 @@ var ArgResolveError = class extends Error {
 	schema;
 	type;
 	/**
-	* Create an instance of ArgResolveError.
+	* Create an `ArgResolveError` instance.
 	*
 	* @param message - the error message
 	* @param name - the name of the argument
@@ -257,6 +259,25 @@ function isNumeric(str) {
 function createTypeError(option, schema) {
 	return new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be '${schema.type}'`, option, "type", schema);
 }
+function checkConflicts(args, explicit, toKebab, actualInputNames) {
+	for (const rawArg in args) {
+		const schema = args[rawArg];
+		if (!explicit[rawArg]) continue;
+		if (!schema.conflicts) continue;
+		const conflicts = Array.isArray(schema.conflicts) ? schema.conflicts : [schema.conflicts];
+		for (let i = 0; i < conflicts.length; i++) {
+			const conflictingArg = conflicts[i];
+			if (!explicit[conflictingArg]) continue;
+			const arg = toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
+			const conflictingArgKebab = toKebab || args[conflictingArg]?.toKebab ? kebabnize(conflictingArg) : conflictingArg;
+			const optionActualName = actualInputNames.get(rawArg) || `--${arg}`;
+			const conflictingActualName = actualInputNames.get(conflictingArg) || `--${conflictingArgKebab}`;
+			const message = `Optional argument '${optionActualName}' conflicts with '${conflictingActualName}'`;
+			return [new ArgResolveError(message, rawArg, "conflict", schema)];
+		}
+	}
+	return [];
+}
 
 //#endregion
 export { ArgResolveError, resolveArgs };

package/lib/{resolver-7JOAwfSr.d.ts → resolver-D64nGlCD.d.ts}

@@ -1,4 +1,4 @@
-import { ArgToken } from "./parser-DEYiqyo1.js";
+import { ArgToken } from "./parser-C6MbpZjd.js";
 
 //#region src/resolver.d.ts
 
@@ -275,6 +275,93 @@ interface ArgSchema {
    * ```
    */
   toKebab?: true;
+  /**
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options,
+   * an `ArgResolveError` with type 'conflict' will be thrown.
+   *
+   * Conflicts only need to be defined on one side - if option A defines a conflict
+   * with option B, the conflict is automatically detected when both are used,
+   * regardless of whether B also defines a conflict with A.
+   *
+   * Supports both single option name or array of option names.
+   * Option names must match the property keys in the schema object exactly
+   * (no automatic conversion between camelCase and kebab-case).
+   *
+   * @example
+   * Single conflict (bidirectional definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Cannot use --summer with --autumn
+   *   },
+   *   autumn: {
+   *     type: 'boolean',
+   *     conflicts: 'summer'  // Can define on both sides for clarity
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Single conflict (one-way definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Only defined on summer side
+   *   },
+   *   autumn: {
+   *     type: 'boolean'
+   *     // No conflicts defined, but still cannot use with --summer
+   *   }
+   * }
+   * // Usage: --summer --autumn will throw error
+   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * ```
+   *
+   * @example
+   * Multiple conflicts:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'number',
+   *     conflicts: ['socket', 'pipe'],  // Cannot use with --socket or --pipe
+   *     description: 'TCP port number'
+   *   },
+   *   socket: {
+   *     type: 'string',
+   *     conflicts: ['port', 'pipe'],    // Cannot use with --port or --pipe
+   *     description: 'Unix socket path'
+   *   },
+   *   pipe: {
+   *     type: 'string',
+   *     conflicts: ['port', 'socket'],  // Cannot use with --port or --socket
+   *     description: 'Named pipe path'
+   *   }
+   * }
+   * // These three options are mutually exclusive
+   * ```
+   *
+   * @example
+   * With kebab-case conversion:
+   * ```ts
+   * {
+   *   summerSeason: {
+   *     type: 'boolean',
+   *     toKebab: true,  // Accessible as --summer-season
+   *     conflicts: 'autumnSeason'  // Must use property key, not CLI name
+   *   },
+   *   autumnSeason: {
+   *     type: 'boolean',
+   *     toKebab: true  // Accessible as --autumn-season
+   *   }
+   * }
+   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * ```
+   */
+  conflicts?: string | string[];
   /**
    * Custom parsing function for `type: 'custom'` arguments.
    *
@@ -328,7 +415,7 @@ interface Args {
 /**
  * An object that contains the values of the arguments.
  *
- * @typeParam T - Arguments which is an object that defines the command line arguments.
+ * @typeParam T - {@link Args | 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;
@@ -337,7 +424,7 @@ 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.
+ * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
  *
  * @internal
  */
@@ -451,7 +538,7 @@ declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
 /**
  * An error type for {@link ArgResolveError}.
  */
-type ArgResolveErrorType = 'type' | 'required';
+type ArgResolveErrorType = 'type' | 'required' | 'conflict';
 /**
  * An error that occurs when resolving arguments.
  * This error is thrown when the argument is not valid.
@@ -461,7 +548,7 @@ declare class ArgResolveError extends Error {
   schema: ArgSchema;
   type: ArgResolveErrorType;
   /**
-   * Create an instance of ArgResolveError.
+   * Create an `ArgResolveError` instance.
    *
    * @param message - the error message
    * @param name - the name of the argument
@@ -471,4 +558,4 @@ declare class ArgResolveError extends 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 };
+export { ArgExplicitlyProvided, ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs };

package/lib/resolver.d.ts

@@ -1,3 +1,3 @@
-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";
+import "./parser-C6MbpZjd.js";
+import { ArgExplicitlyProvided, ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs } from "./resolver-D64nGlCD.js";
 export { ArgExplicitlyProvided, ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, FilterPositionalArgs, ResolveArgValues, ResolveArgs, resolveArgs };

package/lib/resolver.js

@@ -1,5 +1,5 @@
 import "./parser-M-ayhS1h.js";
 import "./utils-1LQrGCWG.js";
-import { ArgResolveError, resolveArgs } from "./resolver-DBvNkaE7.js";
+import { ArgResolveError, resolveArgs } from "./resolver-D0hj6HpX.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.22.2",
+  "version": "0.23.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -71,11 +71,11 @@
     }
   },
   "devDependencies": {
-    "@eslint/markdown": "^6.6.0",
-    "@kazupon/eslint-config": "^0.33.3",
+    "@eslint/markdown": "^7.1.0",
+    "@kazupon/eslint-config": "^0.35.0",
     "@kazupon/prettier-config": "^0.1.1",
-    "@types/node": "^22.17.0",
-    "@typescript/native-preview": "7.0.0-dev.20250801.1",
+    "@types/node": "^24.1.0",
+    "@typescript/native-preview": "7.0.0-dev.20250810.1",
     "@vitest/eslint-plugin": "^1.3.4",
     "bumpp": "^10.2.2",
     "deno": "^2.4.3",
@@ -83,8 +83,9 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsdoc": "^52.0.2",
     "eslint-plugin-jsonc": "^2.20.1",
+    "eslint-plugin-markdown-preferences": "^0.10.0",
     "eslint-plugin-promise": "^7.2.1",
-    "eslint-plugin-regexp": "^2.9.0",
+    "eslint-plugin-regexp": "^2.9.1",
     "eslint-plugin-unicorn": "^60.0.0",
     "eslint-plugin-yml": "^1.18.0",
     "gh-changelogen": "^0.2.8",
@@ -95,7 +96,7 @@
     "mitata": "^1.0.34",
     "pkg-pr-new": "^0.0.54",
     "prettier": "^3.6.2",
-    "tsdown": "^0.13.1",
+    "tsdown": "^0.14.0",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.38.0",
     "vitest": "^3.2.4",