args-tokens 0.16.2 → 0.17.0

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 import { ArgToken, ParserOptions, parseArgs$1 as parseArgs } from "./parser-Bx112mWZ.js";
-import { ArgOptionSchema, ArgOptions, ArgValues, OptionResolveError$1 as OptionResolveError, OptionResolveErrorType, ResolveArgsOptions, resolveArgs$1 as resolveArgs } from "./resolver-ByBRRKOK.js";
+import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver--lXziDSy.js";
 
 //#region src/parse.d.ts
 /**
@@ -8,20 +8,20 @@ import { ArgOptionSchema, ArgOptions, ArgValues, OptionResolveError$1 as OptionR
 /**
 * Parse options for {@link parse} function.
 */
-interface ParseOptions<O extends ArgOptions> extends ParserOptions, ResolveArgsOptions {
+interface ParseOptions<A extends Args> extends ParserOptions, ResolveArgs {
   /**
-  * Command line options, about details see {@link ArgOptions}.
+  * Command line arguments, about details see {@link Args}.
   */
-  options?: O;
+  args?: A;
 }
 /**
 * Parsed command line arguments.
 */
-type ParsedArgs<T extends ArgOptions> = {
+type ParsedArgs<A extends Args> = {
   /**
   * Parsed values, same as `values` in {@link resolveArgs}.
   */
-  values: ArgValues<T>;
+  values: ArgValues<A>;
   /**
   * Positional arguments, same as `positionals` in {@link resolveArgs}.
   */
@@ -54,5 +54,5 @@ type ParsedArgs<T extends ArgOptions> = {
 * @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<O extends ArgOptions>(args: string[], options?: ParseOptions<O>): ParsedArgs<O>; //#endregion
-export { ArgOptionSchema, ArgOptions, ArgToken, ArgValues, OptionResolveError, OptionResolveErrorType, ParseOptions, ParsedArgs, ParserOptions, ResolveArgsOptions, parse, parseArgs, resolveArgs };
+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,5 @@
 import { parseArgs } from "./parser-Dr4iAGaX.js";
-import { OptionResolveError, resolveArgs } from "./resolver-B89Gv70Z.js";
+import { ArgResolveError, resolveArgs } from "./resolver-pmWK3ioa.js";
 
 //#region src/parse.ts
 const DEFAULT_OPTIONS = {
@@ -28,10 +28,10 @@ const DEFAULT_OPTIONS = {
 * @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 { options: argOptions, allowCompatible = false } = options;
+	const { args: _args, allowCompatible = false } = options;
 	const tokens = parseArgs(args, { allowCompatible });
-	return Object.assign(Object.create(null), resolveArgs(argOptions || DEFAULT_OPTIONS, tokens), { tokens });
+	return Object.assign(Object.create(null), resolveArgs(_args || DEFAULT_OPTIONS, tokens), { tokens });
 }
 
 //#endregion
-export { OptionResolveError, parse, parseArgs, resolveArgs };
+export { ArgResolveError, parse, parseArgs, resolveArgs };

package/lib/resolver--lXziDSy.d.ts

@@ -0,0 +1,125 @@
+import { ArgToken } from "./parser-Bx112mWZ.js";
+
+//#region src/resolver.d.ts
+/**
+* An argument schema
+* This schema is similar to the schema of the `node:utils`.
+* difference is that:
+* - `multiple` property is not supported
+* - `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:
+* - `multiple` property is not supported
+* - `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
+*/
+interface ArgSchema {
+  /**
+  * Type of argument.
+  */
+  type: "string" | "boolean" | "number" | "enum" | "positional";
+  /**
+  * A single character alias for the option.
+  */
+  short?: string;
+  /**
+  * A description of the argument.
+  */
+  description?: string;
+  /**
+  * Whether the argument is required or not.
+  */
+  required?: 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;
+}
+/**
+* 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 | undefined;
+};
+/**
+* @internal
+*/
+type ExtractOptionValue<A extends ArgSchema> = A["type"] extends "string" ? string : A["type"] extends "boolean" ? boolean : A["type"] extends "number" ? number : A["type"] extends "positional" ? string : A["type"] extends "enum" ? A["choices"] extends string[] | readonly string[] ? A["choices"][number] : never : string | boolean | number;
+/**
+* @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;
+/**
+* @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] };
+/**
+* An arguments for {@link resolveArgs | resolve arguments}.
+*/
+interface ResolveArgs {
+  /**
+  * Whether to group short options.
+  * @default false
+  * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
+  */
+  optionGrouping?: boolean;
+  /**
+  * Skip positional arguments index.
+  * @default -1
+  */
+  skipPositional?: number;
+}
+/**
+* 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, and {@link AggregateError | validation errors}.
+*/
+declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
+  optionGrouping,
+  skipPositional
+}?: ResolveArgs): {
+  values: ArgValues<A>;
+  positionals: string[];
+  rest: string[];
+  error: AggregateError | undefined;
+};
+/**
+* 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 { ArgResolveError as ArgResolveError$1, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs as resolveArgs$1 };

package/lib/{resolver-B89Gv70Z.js → resolver-pmWK3ioa.js}

@@ -1,18 +1,20 @@
 import { hasLongOptionPrefix, isShortOption } from "./parser-Dr4iAGaX.js";
 
 //#region src/resolver.ts
+const SKIP_POSITIONAL_DEFAULT = -1;
 /**
 * Resolve command line arguments.
-* @param options - An options that contains {@link ArgOptionSchema | options schema}.
+* @param args - An arguments that contains {@link ArgSchema | arguments schema}.
 * @param tokens - An array of {@link ArgToken | tokens}.
-* @param resolveArgsOptions - An options that contains {@link resolveArgsOptions | resolve arguments options}.
+* @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(options, tokens, { optionGrouping = false } = {}) {
-	const positionals = [];
+function resolveArgs(args, tokens, { optionGrouping = false, skipPositional = SKIP_POSITIONAL_DEFAULT } = {}) {
+	const skipPositionalIndex = typeof skipPositional === "number" ? Math.max(skipPositional, SKIP_POSITIONAL_DEFAULT) : SKIP_POSITIONAL_DEFAULT;
 	const rest = [];
 	const longOptionTokens = [];
 	const shortOptionTokens = [];
+	const positionalTokens = [];
 	let currentLongOption;
 	let currentShortOption;
 	const expandableShortOptions = [];
@@ -42,7 +44,7 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 	* analyze phase to resolve value
 	* separate tokens into positionals, long and short options, after that resolve values
 	*/
-	const schemas = Object.values(options);
+	const schemas = Object.values(args);
 	let terminated = false;
 	for (let i = 0; i < tokens.length; i++) {
 		const token = tokens[i];
@@ -53,11 +55,11 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 			}
 			if (currentShortOption) {
 				const found = schemas.find((schema) => schema.short === currentShortOption.name && schema.type === "boolean");
-				if (found) positionals.push(token.value);
+				if (found) positionalTokens.push({ ...token });
 			} else if (currentLongOption) {
-				const found = options[currentLongOption.name]?.type === "boolean";
-				if (found) positionals.push(token.value);
-			} else positionals.push(token.value);
+				const found = args[currentLongOption.name]?.type === "boolean";
+				if (found) positionalTokens.push({ ...token });
+			} else positionalTokens.push({ ...token });
 			applyLongOptionValue(token.value);
 			applyShortOptionValue(token.value);
 		} else if (token.kind === "option") if (token.rawName) {
@@ -109,7 +111,12 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 	function checkTokenName(option, schema, token) {
 		return token.name === (schema.type === "boolean" ? schema.negatable && token.name?.startsWith("no-") ? `no-${option}` : option : option);
 	}
-	for (const [option, schema] of Object.entries(options)) {
+	const positionalItemCount = tokens.filter((token) => token.kind === "positional").length;
+	function getPositionalSkipIndex() {
+		return Math.min(skipPositionalIndex, positionalItemCount);
+	}
+	let positionalsCount = 0;
+	for (const [option, schema] of Object.entries(args)) {
 		if (schema.required) {
 			const found = longOptionTokens.find((token) => token.name === option) || schema.short && shortOptionTokens.find((token) => token.name === schema.short);
 			if (!found) {
@@ -117,6 +124,14 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 				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));
+			positionalsCount++;
+			continue;
+		}
 		for (let i = 0; i < longOptionTokens.length; i++) {
 			const token = longOptionTokens[i];
 			if (checkTokenName(option, schema, token) && token.rawName != void 0 && hasLongOptionPrefix(token.rawName)) {
@@ -133,7 +148,7 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 						continue;
 					}
 				}
-				values[option] = resolveOptionValue(token, schema);
+				values[option] = resolveArgumentValue(token, schema);
 				continue;
 			}
 		}
@@ -153,7 +168,7 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 						continue;
 					}
 				}
-				values[option] = resolveOptionValue(token, schema);
+				values[option] = resolveArgumentValue(token, schema);
 				continue;
 			}
 		}
@@ -161,19 +176,20 @@ function resolveArgs(options, tokens, { optionGrouping = false } = {}) {
 	}
 	return {
 		values,
-		positionals,
+		positionals: positionalTokens.map((token) => token.value),
 		rest,
 		error: errors.length > 0 ? new AggregateError(errors) : void 0
 	};
 }
 function createRequireError(option, schema) {
-	return new OptionResolveError(`Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`, option, "required", schema);
+	const message = schema.type === "positional" ? `Positional argument '${option}' is required` : `Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`;
+	return new ArgResolveError(message, option, "required", schema);
 }
 /**
-* An error that occurs when resolving options.
-* This error is thrown when the option is not valid.
+* An error that occurs when resolving arguments.
+* This error is thrown when the argument is not valid.
 */
-var OptionResolveError = class extends Error {
+var ArgResolveError = class extends Error {
 	name;
 	schema;
 	type;
@@ -198,7 +214,7 @@ function validateValue(token, option, schema) {
 			break;
 		}
 		case "enum": {
-			if (schema.choices && !schema.choices.includes(token.value)) return new OptionResolveError(`Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be chosen from '${schema.type}' [${schema.choices.map((c) => JSON.stringify(c)).join(", ")}] values`, option, "type", schema);
+			if (schema.choices && !schema.choices.includes(token.value)) return new ArgResolveError(`Option '--${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;
 		}
 	}
@@ -207,13 +223,13 @@ function isNumeric(str) {
 	return str.trim() !== "" && !isNaN(str);
 }
 function createTypeError(option, schema) {
-	return new OptionResolveError(`Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be '${schema.type}'`, option, "type", schema);
+	return new ArgResolveError(`Option '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be '${schema.type}'`, option, "type", schema);
 }
-function resolveOptionValue(token, 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 { OptionResolveError, resolveArgs };
+export { ArgResolveError, resolveArgs };

package/lib/resolver.d.ts

@@ -1,3 +1,3 @@
 import "./parser-Bx112mWZ.js";
-import { ArgOptionSchema, ArgOptions, ArgValues, ExtractOptionValue, FilterArgs, OptionResolveError$1 as OptionResolveError, OptionResolveErrorType, ResolveArgValues, ResolveArgsOptions, resolveArgs$1 as resolveArgs } from "./resolver-ByBRRKOK.js";
-export { ArgOptionSchema, ArgOptions, ArgValues, ExtractOptionValue, FilterArgs, OptionResolveError, OptionResolveErrorType, ResolveArgValues, ResolveArgsOptions, resolveArgs };
+import { ArgResolveError$1 as ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs$1 as resolveArgs } from "./resolver--lXziDSy.js";
+export { ArgResolveError, ArgResolveErrorType, ArgSchema, ArgValues, Args, ExtractOptionValue, FilterArgs, ResolveArgValues, ResolveArgs, resolveArgs };

package/lib/resolver.js

@@ -1,4 +1,4 @@
 import "./parser-Dr4iAGaX.js";
-import { OptionResolveError, resolveArgs } from "./resolver-B89Gv70Z.js";
+import { ArgResolveError, resolveArgs } from "./resolver-pmWK3ioa.js";
 
-export { OptionResolveError, resolveArgs };
+export { ArgResolveError, resolveArgs };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"

package/lib/resolver-ByBRRKOK.d.ts

@@ -1,119 +0,0 @@
-import { ArgToken } from "./parser-Bx112mWZ.js";
-
-//#region src/resolver.d.ts
-/**
-* An option schema for an argument.
-* This schema is similar to the schema of the `node:utils`.
-* difference is that:
-* - `multiple` property is not supported
-* - `required` property and `description` property are added
-* - `type` is not only 'string' and 'boolean', but also 'number' and 'enum' too.
-* - `default` property type, not support multiple types
-*/
-/**
-* An option schema for an argument.
-* This schema is similar to the schema of the `node:utils`.
-* difference is that:
-* - `multiple` property is not supported
-* - `required` property and `description` property are added
-* - `type` is not only 'string' and 'boolean', but also 'number' and 'enum' too.
-* - `default` property type, not support multiple types
-*/
-interface ArgOptionSchema {
-  /**
-  * Type of argument.
-  */
-  type: "string" | "boolean" | "number" | "enum";
-  /**
-  * A single character alias for the option.
-  */
-  short?: string;
-  /**
-  * A description of the argument.
-  */
-  description?: string;
-  /**
-  * Whether the argument is required or not.
-  */
-  required?: 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;
-}
-/**
-* An object that contains {@link ArgOptionSchema | options schema}.
-*/
-interface ArgOptions {
-  [option: string]: ArgOptionSchema;
-}
-/**
-* An object that contains the values of the arguments.
-*/
-type ArgValues<T> = T extends ArgOptions ? ResolveArgValues<T, { [Option in keyof T]: ExtractOptionValue<T[Option]> }> : {
-  [option: string]: string | boolean | number | undefined;
-};
-/**
-* @internal
-*/
-type ExtractOptionValue<O extends ArgOptionSchema> = O["type"] extends "string" ? string : O["type"] extends "boolean" ? boolean : O["type"] extends "number" ? number : O["type"] extends "enum" ? O["choices"] extends string[] | readonly string[] ? O["choices"][number] : never : string | boolean | number;
-/**
-* @internal
-*/
-type ResolveArgValues<O extends ArgOptions, V extends Record<keyof O, unknown>> = { -readonly [Option in keyof O]?: V[Option] } & FilterArgs<O, V, "default"> & FilterArgs<O, V, "required"> extends infer P ? { [K in keyof P]: P[K] } : never;
-/**
-* @internal
-*/
-type FilterArgs<O extends ArgOptions, V extends Record<keyof O, unknown>, K extends keyof ArgOptionSchema> = { [Option in keyof O as O[Option][K] extends {} ? Option : never]: V[Option] };
-/**
-* An options for {@link resolveArgs | resolve arguments}.
-*/
-interface ResolveArgsOptions {
-  /**
-  * Whether to group short options.
-  * @default false
-  * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
-  */
-  optionGrouping?: boolean;
-}
-/**
-* Resolve command line arguments.
-* @param options - An options that contains {@link ArgOptionSchema | options schema}.
-* @param tokens - An array of {@link ArgToken | tokens}.
-* @param resolveArgsOptions - An options that contains {@link resolveArgsOptions | resolve arguments options}.
-* @returns An object that contains the values of the arguments, positional arguments, rest arguments, and {@link AggregateError | validation errors}.
-*/
-declare function resolveArgs<T extends ArgOptions>(options: T, tokens: ArgToken[], {
-  optionGrouping
-}?: ResolveArgsOptions): {
-  values: ArgValues<T>;
-  positionals: string[];
-  rest: string[];
-  error: AggregateError | undefined;
-};
-/**
-* An error type for {@link OptionResolveError}.
-*/
-type OptionResolveErrorType = "type" | "required";
-/**
-* An error that occurs when resolving options.
-* This error is thrown when the option is not valid.
-*/
-declare class OptionResolveError extends Error {
-  name: string;
-  schema: ArgOptionSchema;
-  type: OptionResolveErrorType;
-  constructor(message: string, name: string, type: OptionResolveErrorType, schema: ArgOptionSchema);
-}
-
-//#endregion
-export { ArgOptionSchema, ArgOptions, ArgValues, ExtractOptionValue, FilterArgs, OptionResolveError as OptionResolveError$1, OptionResolveErrorType, ResolveArgValues, ResolveArgsOptions, resolveArgs as resolveArgs$1 };