gunshi 0.28.2 → 0.29.2

package/lib/combinators.js

@@ -0,0 +1,503 @@
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/combinators.js
+/**
+* Create a string argument schema with optional validation.
+*
+* @param opts - Validation options.
+* @returns A combinator schema that resolves to string.
+*
+* @example
+* ```ts
+* const args = {
+*   name: string({ minLength: 1, maxLength: 50 })
+* }
+* ```
+*
+* @experimental
+*/
+function string(opts) {
+	return {
+		type: "string",
+		metavar: "string",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			if (opts?.minLength != null && value.length < opts.minLength) throw new RangeError(`String must be at least ${opts.minLength} characters`);
+			if (opts?.maxLength != null && value.length > opts.maxLength) throw new RangeError(`String must be at most ${opts.maxLength} characters`);
+			if (opts?.pattern != null && !opts.pattern.test(value)) throw new Error(`String must match pattern ${opts.pattern}`);
+			return value;
+		}
+	};
+}
+/**
+* Create a number argument schema with optional range validation.
+*
+* Accepts any numeric value (integer or float).
+*
+* @param opts - Range options.
+* @returns A combinator schema that resolves to number.
+*
+* @example
+* ```ts
+* const args = {
+*   timeout: number({ min: 0, max: 30000 })
+* }
+* ```
+*
+* @experimental
+*/
+function number(opts) {
+	return {
+		type: "number",
+		metavar: "number",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			const n = Number(value);
+			if (value.trim() === "" || isNaN(n)) throw new TypeError(`Expected a number, got '${value}'`);
+			if (opts?.min != null && n < opts.min) throw new RangeError(`Number must be >= ${opts.min}, got ${n}`);
+			if (opts?.max != null && n > opts.max) throw new RangeError(`Number must be <= ${opts.max}, got ${n}`);
+			return n;
+		}
+	};
+}
+/**
+* Create an integer argument schema with optional range validation.
+*
+* Only accepts integer values (no decimals).
+*
+* @param opts - Range options.
+* @returns A combinator schema that resolves to number (integer).
+*
+* @example
+* ```ts
+* const args = {
+*   retries: integer({ min: 0, max: 10 })
+* }
+* ```
+*
+* @experimental
+*/
+function integer(opts) {
+	return {
+		type: "custom",
+		metavar: "integer",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			if (!/^-?\d+$/.test(value)) throw new TypeError(`Expected an integer, got '${value}'`);
+			const n = Number.parseInt(value, 10);
+			if (isNaN(n)) throw new TypeError(`Expected an integer, got '${value}'`);
+			if (opts?.min != null && n < opts.min) throw new RangeError(`Integer must be >= ${opts.min}, got ${n}`);
+			if (opts?.max != null && n > opts.max) throw new RangeError(`Integer must be <= ${opts.max}, got ${n}`);
+			return n;
+		}
+	};
+}
+/**
+* Create a floating-point argument schema with optional range validation.
+*
+* Rejects `NaN` and `Infinity` values.
+*
+* @param opts - Range options.
+* @returns A combinator schema that resolves to number (float).
+*
+* @example
+* ```ts
+* const args = {
+*   ratio: float({ min: 0, max: 1 })
+* }
+* ```
+*
+* @experimental
+*/
+function float(opts) {
+	return {
+		type: "custom",
+		metavar: "float",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			const trimmed = value.trim();
+			if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(trimmed)) throw new TypeError(`Expected a finite float, got '${value}'`);
+			const n = Number.parseFloat(trimmed);
+			if (isNaN(n) || !isFinite(n)) throw new TypeError(`Expected a finite float, got '${value}'`);
+			if (opts?.min != null && n < opts.min) throw new RangeError(`Float must be >= ${opts.min}, got ${n}`);
+			if (opts?.max != null && n > opts.max) throw new RangeError(`Float must be <= ${opts.max}, got ${n}`);
+			return n;
+		}
+	};
+}
+/**
+* Create a boolean argument schema.
+*
+* Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
+* to the parse function based on the presence or negation of the flag.
+*
+* @param opts - Boolean options.
+* @returns A combinator schema for boolean flags.
+*
+* @example
+* ```ts
+* const args = {
+*   color: boolean({ negatable: true })
+* }
+* // Usage: --color (true), --no-color (false)
+* ```
+*
+* @experimental
+*/
+function boolean(opts) {
+	return {
+		type: "boolean",
+		...opts?.negatable != null ? { negatable: opts.negatable } : {},
+		metavar: "boolean",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			return value === "true";
+		}
+	};
+}
+function positional(parser) {
+	if (parser && "parse" in parser) return {
+		type: "positional",
+		parse: parser.parse,
+		metavar: parser.metavar,
+		...parser.description != null ? { description: parser.description } : {},
+		...parser.required != null ? { required: parser.required } : {}
+	};
+	const opts = parser;
+	return {
+		type: "positional",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {}
+	};
+}
+/**
+* Create an enum-like argument schema with literal type inference.
+*
+* Uses `const T` generic to infer literal union types from the values array.
+*
+* @typeParam T - The readonly array of allowed string values.
+*
+* @param values - Allowed values.
+* @param opts - Common options (description, short, required).
+* @returns A combinator schema that resolves to a union of the allowed values.
+*
+* @example
+* ```ts
+* const args = {
+*   level: choice(['debug', 'info', 'warn', 'error'] as const)
+* }
+* // typeof values.level === 'debug' | 'info' | 'warn' | 'error'
+* ```
+*
+* @experimental
+*/
+function choice(values, opts) {
+	return {
+		type: "enum",
+		metavar: values.join("|"),
+		choices: values,
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			if (!values.includes(value)) throw new Error(`Value must be one of: ${values.join(", ")}`);
+			return value;
+		}
+	};
+}
+/**
+* Create a custom argument schema with a user-defined parse function.
+*
+* This is the most general custom combinator. Use it when none of the built-in
+* base combinators ({@link string}, {@link number}, {@link integer},
+* {@link float}, {@link boolean}, {@link choice}) fit your needs.
+*
+* The returned schema has `type: 'custom'`.
+*
+* @typeParam T - The parsed value type.
+*
+* @param config - Configuration with a parse function and optional metavar.
+* @returns A combinator schema that resolves to the parse function's return type.
+*
+* @example
+* ```ts
+* const date = combinator({
+*   parse: (value) => {
+*     const d = new Date(value)
+*     if (isNaN(d.getTime())) {
+*       throw new Error('Invalid date format')
+*     }
+*     return d
+*   },
+*   metavar: 'date'
+* })
+* ```
+*
+* @experimental
+*/
+function combinator(config) {
+	return {
+		type: "custom",
+		metavar: config.metavar ?? "custom",
+		...config.description != null ? { description: config.description } : {},
+		...config.short != null ? { short: config.short } : {},
+		...config.required != null ? { required: config.required } : {},
+		parse: config.parse
+	};
+}
+/**
+* Transform the output of a combinator schema.
+*
+* Creates a new schema that applies `transform` to the result of `schema.parse`.
+* The original schema is not modified.
+*
+* @typeParam T - The input schema's parsed type.
+* @typeParam U - The transformed type.
+*
+* @param schema - The base combinator schema.
+* @param transform - The transformation function.
+* @returns A new combinator schema that resolves to the transformed type.
+*
+* @example
+* ```ts
+* const args = {
+*   doubled: map(integer(), n => n * 2)
+* }
+* ```
+*
+* @experimental
+*/
+function map(schema, transform) {
+	const baseParse = schema.parse;
+	return {
+		...schema,
+		parse(value) {
+			return transform(baseParse(value));
+		}
+	};
+}
+/**
+* Set a default value on a combinator schema.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+*
+* @param schema - The base combinator schema.
+* @param defaultValue - The default value.
+* @returns A new schema with the default value set.
+*
+* @example
+* ```ts
+* const args = {
+*   port: withDefault(integer({ min: 1, max: 65535 }), 8080)
+* }
+* ```
+*
+* @experimental
+*/
+function withDefault(schema, defaultValue) {
+	return {
+		...schema,
+		default: defaultValue
+	};
+}
+/**
+* Mark a combinator schema as accepting multiple values.
+*
+* The resolved value becomes an array. The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+* @param schema - The base combinator schema.
+* @returns A new schema with `multiple: true`.
+*
+* @example
+* ```ts
+* const args = {
+*   tags: multiple(string())
+* }
+* // typeof values.tags === string[]
+* ```
+*
+* @experimental
+*/
+function multiple(schema) {
+	return {
+		...schema,
+		multiple: true
+	};
+}
+/**
+* Mark a combinator schema as required.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+*
+* @param schema - The base combinator schema.
+* @returns A new schema with `required: true`.
+*
+* @example
+* ```ts
+* const args = {
+*   name: required(string())
+* }
+* ```
+*
+* @experimental
+*/
+function required(schema) {
+	return {
+		...schema,
+		required: true
+	};
+}
+/**
+* Set a short alias on a combinator schema.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+* @typeParam S - The short alias string literal type.
+*
+* @param schema - The base combinator schema.
+* @param alias - Single character short alias.
+* @returns A new schema with the short alias set.
+*
+* @example
+* ```ts
+* const args = {
+*   verbose: short(boolean(), 'v')
+* }
+* // Usage: -v or --verbose
+* ```
+*
+* @experimental
+*/
+function short(schema, alias) {
+	return {
+		...schema,
+		short: alias
+	};
+}
+/**
+* Set a description on a combinator schema for help text generation.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+* @typeParam D - The description string literal type.
+*
+* @param schema - The base combinator schema.
+* @param text - Human-readable description.
+* @returns A new schema with the description set.
+*
+* @example
+* ```ts
+* const args = {
+*   port: describe(integer(), 'Port number to listen on')
+* }
+* ```
+*
+* @experimental
+*/
+function describe(schema, text) {
+	return {
+		...schema,
+		description: text
+	};
+}
+/**
+* Mark a combinator schema as not required.
+*
+* Useful for overriding a base combinator that was created with `required: true`.
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+*
+* @param schema - The base combinator schema.
+* @returns A new schema with `required: false`.
+*
+* @example
+* ```ts
+* const args = {
+*   name: unrequired(string({ required: true }))
+* }
+* ```
+*
+* @experimental
+*/
+function unrequired(schema) {
+	return {
+		...schema,
+		required: false
+	};
+}
+/**
+* Type-safe schema factory.
+*
+* Returns the input unchanged at runtime, but provides type inference
+* so that `satisfies Args` is not needed.
+*
+* @typeParam T - The exact schema type.
+*
+* @param fields - The argument schema object.
+* @returns The same schema object with its type inferred.
+*
+* @example
+* ```ts
+* const common = args({
+*   verbose: boolean(),
+*   help: short(boolean(), 'h')
+* })
+* ```
+*
+* @experimental
+*/
+function args(fields) {
+	return fields;
+}
+function merge(...schemas) {
+	const result = Object.create(null);
+	for (const schema of schemas) for (const key of Object.keys(schema)) result[key] = schema[key];
+	return result;
+}
+/**
+* Extend a schema by overriding or adding fields.
+*
+* Equivalent to `merge(base, overrides)` but communicates the intent of
+* intentional overrides rather than general composition.
+*
+* @typeParam T - Base schema type.
+* @typeParam U - Overrides schema type.
+*
+* @param base - The base schema to extend.
+* @param overrides - Fields to override or add.
+* @returns A new schema with overrides applied.
+*
+* @example
+* ```ts
+* const base = args({ port: withDefault(integer(), 8080) })
+* const strict = extend(base, { port: required(integer({ min: 1, max: 65535 })) })
+* ```
+*
+* @experimental
+*/
+function extend(base, overrides) {
+	const result = Object.create(null);
+	for (const key of Object.keys(base)) result[key] = base[key];
+	for (const key of Object.keys(overrides)) result[key] = overrides[key];
+	return result;
+}
+
+//#endregion
+export { args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };

package/lib/{constants-C7V6-RNo.d.ts → constants-Ddb0iqST.d.ts}

@@ -1,4 +1,4 @@
-import { m as DefaultGunshiParams, n as CliOptions } from "./types-Doxo8g3Y.js";
+import { m as DefaultGunshiParams, n as CliOptions } from "./types-BBvkSkl2.js";
 
 //#region src/constants.d.ts
 /**

package/lib/{context-CHDIbgwd.js → context-Ctl36pNI.js}

@@ -1,4 +1,4 @@
-import { a as log, i as isLazyCommand, n as deepFreeze, t as create } from "./utils-DNS9AIR_.js";
+import { a as log, i as isLazyCommand, n as deepFreeze, t as create } from "./utils-B6TBrE2m.js";
 import { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
 
 //#region src/context.ts

package/lib/context.d.ts

@@ -1,4 +1,5 @@
-import { B as Args, H as ArgToken, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
+import { i as Args, o as ArgToken, r as ArgValues } from "./resolver-BfQ_CoYR.js";
+import { _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams } from "./types-BBvkSkl2.js";
 
 //#region src/context.d.ts
 

package/lib/context.js

@@ -1,3 +1,3 @@
-import { t as createCommandContext } from "./context-CHDIbgwd.js";
+import { t as createCommandContext } from "./context-Ctl36pNI.js";
 
 export { createCommandContext };

package/lib/{core-C9P_Gd_f.js → core-CoMdwsPo.js}

@@ -1,8 +1,8 @@
-import { i as isLazyCommand, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-DNS9AIR_.js";
+import { i as isLazyCommand, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-B6TBrE2m.js";
 import { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
-import { t as createCommandContext } from "./context-CHDIbgwd.js";
+import { t as createCommandContext } from "./context-Ctl36pNI.js";
 
-//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/parser.js
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/parser.js
 const HYPHEN_CHAR = "-";
 const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
 const EQUAL_CHAR = "=";
@@ -200,7 +200,7 @@ function hasOptionValue(value) {
 }
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/resolver.js
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/resolver.js
 /**
 * Entry point of argument options resolver.
 *
@@ -286,13 +286,15 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 				rest.push(token.value);
 				continue;
 			}
-			if (currentShortOption) {
-				if (schemas.find((schema) => schema.short === currentShortOption.name && schema.type === "boolean")) positionalTokens.push({ ...token });
-			} else if (currentLongOption) {
-				if (args[currentLongOption.name]?.type === "boolean") positionalTokens.push({ ...token });
-			} else positionalTokens.push({ ...token });
-			applyLongOptionValue(token.value);
-			applyShortOptionValue(token.value);
+			if (currentShortOption) if (schemas.find((schema) => schema.short === currentShortOption.name && schema.type === "boolean")) {
+				positionalTokens.push({ ...token });
+				applyShortOptionValue();
+			} else applyShortOptionValue(token.value);
+			else if (currentLongOption) if (args[currentLongOption.name]?.type === "boolean") {
+				positionalTokens.push({ ...token });
+				applyLongOptionValue();
+			} else applyLongOptionValue(token.value);
+			else positionalTokens.push({ ...token });
 		} else if (token.kind === "option") if (token.rawName) {
 			if (hasLongOptionPrefix(token.rawName)) {
 				applyLongOptionValue();
@@ -357,14 +359,27 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 			if (schema.multiple) {
 				const remainingPositionals = positionalTokens.slice(positionalsCount);
 				if (remainingPositionals.length > 0) {
-					values[rawArg] = remainingPositionals.map((p) => p.value);
+					if (typeof schema.parse === "function") {
+						const parsed = [];
+						for (const p of remainingPositionals) try {
+							parsed.push(schema.parse(p.value));
+						} catch (error) {
+							errors.push(error);
+						}
+						values[rawArg] = parsed;
+					} else values[rawArg] = remainingPositionals.map((p) => p.value);
 					positionalsCount += remainingPositionals.length;
 					explicit[rawArg] = true;
 				} else if (schema.required) errors.push(createRequireError(arg, schema));
 			} else {
 				const positional = positionalTokens[positionalsCount];
 				if (positional != null) {
-					values[rawArg] = positional.value;
+					if (typeof schema.parse === "function") try {
+						values[rawArg] = schema.parse(positional.value);
+					} catch (error) {
+						errors.push(error);
+					}
+					else values[rawArg] = positional.value;
 					explicit[rawArg] = true;
 				} else errors.push(createRequireError(arg, schema));
 				positionalsCount++;
@@ -390,7 +405,6 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 				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);
 				else if (schema.multiple) {
@@ -412,22 +426,25 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	};
 }
 function parse(token, option, schema) {
+	if (typeof schema.parse === "function") try {
+		if (schema.type === "boolean") {
+			const boolValue = !(schema.negatable && token.name.startsWith("no-"));
+			return [schema.parse(String(boolValue)), void 0];
+		}
+		return [schema.parse(token.value ?? String(schema.default ?? "")), void 0];
+	} catch (error) {
+		return [void 0, error];
+	}
 	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 "boolean": return [!(schema.negatable && token.name.startsWith("no-")), void 0];
 		case "number":
 			if (!isNumeric(token.value)) return [void 0, createTypeError(option, schema)];
 			return token.value ? [+token.value, void 0] : [+(schema.default || ""), void 0];
 		case "enum":
 			if (schema.choices && !schema.choices.includes(token.value)) return [void 0, new ArgResolveError(`Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}should be chosen from '${schema.type}' [${schema.choices.map((c) => JSON.stringify(c)).join(", ")}] values`, option, "type", schema)];
 			return [token.value || schema.default, void 0];
-		case "custom":
-			if (typeof schema.parse !== "function") throw new TypeError(`argument '${option}' should have a 'parse' function`);
-			try {
-				return [schema.parse(token.value || String(schema.default || "")), void 0];
-			} catch (error) {
-				return [void 0, error];
-			}
+		case "custom": throw new TypeError(`argument '${option}' should have a 'parse' function`);
 		default: throw new Error(`Unsupported argument type '${schema.type}' for option '${option}'`);
 	}
 }

package/lib/definition.d.ts

@@ -1,4 +1,5 @@
-import { B as Args, C as Prettify, R as ArgSchema, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
+import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-BfQ_CoYR.js";
+import { C as Prettify, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, x as LazyCommand, y as GunshiParams } from "./types-BBvkSkl2.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 
 //#region src/definition.d.ts

package/lib/definition.js

@@ -1,4 +1,4 @@
-import { t as createCommandContext } from "./context-CHDIbgwd.js";
+import { t as createCommandContext } from "./context-Ctl36pNI.js";
 
 //#region src/definition.ts
 /**

package/lib/generator.d.ts

@@ -1,4 +1,4 @@
-import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-Doxo8g3Y.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-BBvkSkl2.js";
 
 //#region src/generator.d.ts
 

package/lib/generator.js

@@ -1,7 +1,7 @@
-import "./core-C9P_Gd_f.js";
-import { t as create } from "./utils-DNS9AIR_.js";
-import "./src-CfO5ab2f.js";
-import { t as cli } from "./cli-l4AYjN-O.js";
+import "./core-CoMdwsPo.js";
+import { t as create } from "./utils-B6TBrE2m.js";
+import "./src-h66U0DWW.js";
+import { t as cli } from "./cli-C1Yws72G.js";
 
 //#region src/generator.ts
 /**