args-tokens 0.22.6 → 0.23.1

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.
@@ -546,7 +584,7 @@ This project is inspired by:
 
 ## 🤝 Sponsors
 
-The development of Gunish is supported by my OSS sponsors!
+The development of Gunshi is supported by my OSS sponsors!
 
 <p align="center">
   <a href="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg">

package/lib/index.d.ts

@@ -1,8 +1,11 @@
-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.js";
+import { ArgExplicitlyProvided, ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs } from "./resolver.js";
 
 //#region src/parse.d.ts
-
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 /**
  * Parse options for {@link parse} function.
  *

package/lib/index.js

@@ -1,8 +1,11 @@
-import { parseArgs } from "./parser-M-ayhS1h.js";
-import "./utils-1LQrGCWG.js";
-import { ArgResolveError, resolveArgs } from "./resolver-DBvNkaE7.js";
+import { parseArgs } from "./parser.js";
+import { ArgResolveError, resolveArgs } from "./resolver.js";
 
 //#region src/parse.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 const DEFAULT_OPTIONS = {
 	help: {
 		type: "boolean",

package/lib/parser.d.ts

@@ -1,2 +1,98 @@
-import { ArgToken, ParserOptions, hasLongOptionPrefix$1 as hasLongOptionPrefix, isShortOption$1 as isShortOption, parseArgs$1 as parseArgs } from "./parser-DEYiqyo1.js";
+//#region src/parser.d.ts
+/**
+ * Entry point of argument parser.
+ *
+ * @module
+ */
+/**
+ * forked from `nodejs/node` (`pkgjs/parseargs`)
+ * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+ * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+ *
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * 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
+ */
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+/**
+ * Argument token.
+ */
+interface ArgToken {
+  /**
+   * Argument token kind.
+   */
+  kind: ArgTokenKind;
+  /**
+   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
+   */
+  index: number;
+  /**
+   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
+   */
+  name?: string;
+  /**
+   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
+   */
+  rawName?: string;
+  /**
+   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
+   */
+  value?: string;
+  /**
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   */
+  inlineValue?: boolean;
+}
+/**
+ * Parser Options.
+ */
+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
+ * // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
+ *
+ * const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
+ * // do something with using tokens
+ * // ...
+ * console.log('tokens:', tokens)
+ * ```
+ */
+declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
+/**
+ * Check if `arg` is a short option (e.g. `-f`).
+ *
+ * @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 - An argument to check
+ * @returns Whether `arg` is a long option prefix.
+ */
+declare function hasLongOptionPrefix(arg: string): boolean;
+//#endregion
 export { ArgToken, ParserOptions, hasLongOptionPrefix, isShortOption, parseArgs };

package/lib/parser.js

@@ -1,3 +1,199 @@
-import { hasLongOptionPrefix, isShortOption, parseArgs } from "./parser-M-ayhS1h.js";
+//#region src/parser.ts
+const HYPHEN_CHAR = "-";
+const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
+const EQUAL_CHAR = "=";
+const EQUAL_CODE = EQUAL_CHAR.codePointAt(0);
+const TERMINATOR = "--";
+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
+* // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
+*
+* const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
+* // do something with using tokens
+* // ...
+* console.log('tokens:', tokens)
+* ```
+*/
+function parseArgs(args, options = {}) {
+	const { allowCompatible = false } = options;
+	const tokens = [];
+	const remainings = [...args];
+	let index = -1;
+	let groupCount = 0;
+	let hasShortValueSeparator = false;
+	while (remainings.length > 0) {
+		const arg = remainings.shift();
+		if (arg == void 0) break;
+		const nextArg = remainings[0];
+		if (groupCount > 0) groupCount--;
+		else index++;
+		if (arg === TERMINATOR) {
+			tokens.push({
+				kind: "option-terminator",
+				index
+			});
+			const mapped = remainings.map((arg) => {
+				return {
+					kind: "positional",
+					index: ++index,
+					value: arg
+				};
+			});
+			tokens.push(...mapped);
+			break;
+		}
+		if (isShortOption(arg)) {
+			const shortOption = arg.charAt(1);
+			let value;
+			let inlineValue;
+			if (groupCount) {
+				tokens.push({
+					kind: "option",
+					name: shortOption,
+					rawName: arg,
+					index,
+					value,
+					inlineValue
+				});
+				if (groupCount === 1 && hasOptionValue(nextArg)) {
+					value = remainings.shift();
+					if (hasShortValueSeparator) {
+						inlineValue = true;
+						hasShortValueSeparator = false;
+					}
+					tokens.push({
+						kind: "option",
+						index,
+						value,
+						inlineValue
+					});
+				}
+			} else tokens.push({
+				kind: "option",
+				name: shortOption,
+				rawName: arg,
+				index,
+				value,
+				inlineValue
+			});
+			if (value != null) ++index;
+			continue;
+		}
+		if (isShortOptionGroup(arg)) {
+			const expanded = [];
+			let shortValue = "";
+			for (let i = 1; i < arg.length; i++) {
+				const shortableOption = arg.charAt(i);
+				if (hasShortValueSeparator) shortValue += shortableOption;
+				else if (!allowCompatible && shortableOption.codePointAt(0) === EQUAL_CODE) hasShortValueSeparator = true;
+				else expanded.push(`${SHORT_OPTION_PREFIX}${shortableOption}`);
+			}
+			if (shortValue) expanded.push(shortValue);
+			remainings.unshift(...expanded);
+			groupCount = expanded.length;
+			continue;
+		}
+		if (isLongOption(arg)) {
+			const longOption = arg.slice(2);
+			tokens.push({
+				kind: "option",
+				name: longOption,
+				rawName: arg,
+				index,
+				value: void 0,
+				inlineValue: void 0
+			});
+			continue;
+		}
+		if (isLongOptionAndValue(arg)) {
+			const equalIndex = arg.indexOf(EQUAL_CHAR);
+			const longOption = arg.slice(2, equalIndex);
+			const value = arg.slice(equalIndex + 1);
+			tokens.push({
+				kind: "option",
+				name: longOption,
+				rawName: `${LONG_OPTION_PREFIX}${longOption}`,
+				index,
+				value,
+				inlineValue: true
+			});
+			continue;
+		}
+		tokens.push({
+			kind: "positional",
+			index,
+			value: arg
+		});
+	}
+	return tokens;
+}
+/**
+* Check if `arg` is a short option (e.g. `-f`).
+*
+* @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 - An argument to check
+* @returns Whether `arg` is a short option group.
+*/
+function isShortOptionGroup(arg) {
+	if (arg.length <= 2) return false;
+	if (arg.codePointAt(0) !== HYPHEN_CODE) return false;
+	if (arg.codePointAt(1) === HYPHEN_CODE) return false;
+	return true;
+}
+/**
+* Check if `arg` is a long option (e.g. `--foo`).
+*
+* @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 - 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 - 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.
+*/
+function hasOptionValue(value) {
+	return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
+}
 
+//#endregion
 export { hasLongOptionPrefix, isShortOption, parseArgs };