@guanghechen/commander 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Change Log
 
+## 3.2.0
+
+### Minor Changes
+
+- Change args from string[] to Record<string, unknown> with type/coerce/default support:
+  - `args` is now `Record<string, unknown>` keyed by argument name
+  - Add `rawArgs: string[]` for original argument strings before type conversion
+  - IArgument now supports `type`, `default`, and `coerce` properties
+  - Add `TooManyArguments` error kind for extra arguments validation
+
 ## 3.1.0
 
 ### Minor Changes

package/lib/cjs/index.cjs

@@ -149,13 +149,8 @@ class Command {
             };
             this.#applyChain(chain, optsMap, ctx);
             const mergedOpts = this.#mergeOpts(chain, optsMap);
-            const args = restArgs;
-            const requiredArgs = leafCommand.#arguments.filter(a => a.kind === 'required');
-            if (args.length < requiredArgs.length) {
-                const missing = requiredArgs.slice(args.length).map(a => a.name);
-                throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, leafCommand.#getCommandPath());
-            }
-            const actionParams = { ctx, opts: mergedOpts, args };
+            const { args, rawArgs } = leafCommand.#parseArguments(restArgs);
+            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
             if (leafCommand.#action) {
                 try {
                     await leafCommand.#action(actionParams);
@@ -189,7 +184,7 @@ class Command {
     parse(argv) {
         const allOptions = this.#getMergedOptions();
         const opts = {};
-        const args = [];
+        const rawArgs = [];
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -214,7 +209,7 @@ class Command {
         while (i < remaining.length) {
             const token = remaining[i];
             if (token === '--') {
-                args.push(...remaining.slice(i + 1));
+                rawArgs.push(...remaining.slice(i + 1));
                 break;
             }
             if (token.startsWith('--')) {
@@ -225,7 +220,7 @@ class Command {
                 i = this.#parseShortOption(remaining, i, optionByShort, opts);
                 continue;
             }
-            args.push(token);
+            rawArgs.push(token);
             i += 1;
         }
         for (const opt of allOptions) {
@@ -245,12 +240,8 @@ class Command {
                 }
             }
         }
-        const requiredArgs = this.#arguments.filter(a => a.kind === 'required');
-        if (args.length < requiredArgs.length) {
-            const missing = requiredArgs.slice(args.length).map(a => a.name);
-            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
-        }
-        return { opts, args };
+        const { args } = this.#parseArguments(rawArgs);
+        return { opts, args, rawArgs };
     }
     shift(tokens) {
         return this.#shiftWithShadowed(tokens, new Set());
@@ -662,6 +653,9 @@ class Command {
         }
     }
     #validateArgumentConfig(arg) {
+        if (arg.kind === 'required' && arg.default !== undefined) {
+            throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot have a default value`, this.#getCommandPath());
+        }
         if (arg.kind === 'variadic') {
             if (this.#arguments.some(a => a.kind === 'variadic')) {
                 throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', this.#getCommandPath());
@@ -680,6 +674,61 @@ class Command {
             }
         }
     }
+    #parseArguments(rawArgs) {
+        const argumentDefs = this.#arguments;
+        const args = {};
+        const requiredCount = argumentDefs.filter(a => a.kind === 'required').length;
+        if (rawArgs.length < requiredCount) {
+            const missing = argumentDefs
+                .filter(a => a.kind === 'required')
+                .slice(rawArgs.length)
+                .map(a => a.name);
+            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        }
+        let index = 0;
+        for (const def of argumentDefs) {
+            if (def.kind === 'variadic') {
+                const rest = rawArgs.slice(index);
+                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
+                index = rawArgs.length;
+                break;
+            }
+            const raw = rawArgs[index];
+            if (raw === undefined) {
+                if (def.kind === 'optional') {
+                    args[def.name] = def.default ?? undefined;
+                    continue;
+                }
+            }
+            else {
+                args[def.name] = this.#convertArgument(def, raw);
+                index += 1;
+            }
+        }
+        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
+        if (!hasVariadic && index < rawArgs.length) {
+            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
+        }
+        return { args, rawArgs };
+    }
+    #convertArgument(def, raw) {
+        if (def.coerce) {
+            try {
+                return def.coerce(raw);
+            }
+            catch {
+                throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+        }
+        if (def.type === 'number') {
+            const n = Number(raw);
+            if (Number.isNaN(n)) {
+                throw new CommanderError('InvalidType', `invalid number "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+            return n;
+        }
+        return raw;
+    }
     #buildOptionMaps(allOptions, excludeResolver = false) {
         const optionByLong = new Map();
         const optionByShort = new Map();

package/lib/esm/index.mjs

@@ -127,13 +127,8 @@ class Command {
             };
             this.#applyChain(chain, optsMap, ctx);
             const mergedOpts = this.#mergeOpts(chain, optsMap);
-            const args = restArgs;
-            const requiredArgs = leafCommand.#arguments.filter(a => a.kind === 'required');
-            if (args.length < requiredArgs.length) {
-                const missing = requiredArgs.slice(args.length).map(a => a.name);
-                throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, leafCommand.#getCommandPath());
-            }
-            const actionParams = { ctx, opts: mergedOpts, args };
+            const { args, rawArgs } = leafCommand.#parseArguments(restArgs);
+            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
             if (leafCommand.#action) {
                 try {
                     await leafCommand.#action(actionParams);
@@ -167,7 +162,7 @@ class Command {
     parse(argv) {
         const allOptions = this.#getMergedOptions();
         const opts = {};
-        const args = [];
+        const rawArgs = [];
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -192,7 +187,7 @@ class Command {
         while (i < remaining.length) {
             const token = remaining[i];
             if (token === '--') {
-                args.push(...remaining.slice(i + 1));
+                rawArgs.push(...remaining.slice(i + 1));
                 break;
             }
             if (token.startsWith('--')) {
@@ -203,7 +198,7 @@ class Command {
                 i = this.#parseShortOption(remaining, i, optionByShort, opts);
                 continue;
             }
-            args.push(token);
+            rawArgs.push(token);
             i += 1;
         }
         for (const opt of allOptions) {
@@ -223,12 +218,8 @@ class Command {
                 }
             }
         }
-        const requiredArgs = this.#arguments.filter(a => a.kind === 'required');
-        if (args.length < requiredArgs.length) {
-            const missing = requiredArgs.slice(args.length).map(a => a.name);
-            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
-        }
-        return { opts, args };
+        const { args } = this.#parseArguments(rawArgs);
+        return { opts, args, rawArgs };
     }
     shift(tokens) {
         return this.#shiftWithShadowed(tokens, new Set());
@@ -640,6 +631,9 @@ class Command {
         }
     }
     #validateArgumentConfig(arg) {
+        if (arg.kind === 'required' && arg.default !== undefined) {
+            throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot have a default value`, this.#getCommandPath());
+        }
         if (arg.kind === 'variadic') {
             if (this.#arguments.some(a => a.kind === 'variadic')) {
                 throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', this.#getCommandPath());
@@ -658,6 +652,61 @@ class Command {
             }
         }
     }
+    #parseArguments(rawArgs) {
+        const argumentDefs = this.#arguments;
+        const args = {};
+        const requiredCount = argumentDefs.filter(a => a.kind === 'required').length;
+        if (rawArgs.length < requiredCount) {
+            const missing = argumentDefs
+                .filter(a => a.kind === 'required')
+                .slice(rawArgs.length)
+                .map(a => a.name);
+            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        }
+        let index = 0;
+        for (const def of argumentDefs) {
+            if (def.kind === 'variadic') {
+                const rest = rawArgs.slice(index);
+                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
+                index = rawArgs.length;
+                break;
+            }
+            const raw = rawArgs[index];
+            if (raw === undefined) {
+                if (def.kind === 'optional') {
+                    args[def.name] = def.default ?? undefined;
+                    continue;
+                }
+            }
+            else {
+                args[def.name] = this.#convertArgument(def, raw);
+                index += 1;
+            }
+        }
+        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
+        if (!hasVariadic && index < rawArgs.length) {
+            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
+        }
+        return { args, rawArgs };
+    }
+    #convertArgument(def, raw) {
+        if (def.coerce) {
+            try {
+                return def.coerce(raw);
+            }
+            catch {
+                throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+        }
+        if (def.type === 'number') {
+            const n = Number(raw);
+            if (Number.isNaN(n)) {
+                throw new CommanderError('InvalidType', `invalid number "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+            return n;
+        }
+        return raw;
+    }
     #buildOptionMaps(allOptions, excludeResolver = false) {
         const optionByLong = new Map();
         const optionByShort = new Map();

package/lib/types/index.d.ts

@@ -46,14 +46,25 @@ interface IOption<T = unknown> {
 }
 /** Argument kind */
 type IArgumentKind = 'required' | 'optional' | 'variadic';
-/** Positional argument definition */
-interface IArgument {
+/** Argument value type */
+type IArgumentType = 'string' | 'number';
+/**
+ * Positional argument definition.
+ * @template T - The type of the argument value
+ */
+interface IArgument<T = unknown> {
     /** Argument name */
     name: string;
     /** Argument description */
     description: string;
     /** Argument kind: required / optional / variadic */
     kind: IArgumentKind;
+    /** Value type, defaults to 'string' */
+    type?: IArgumentType;
+    /** Default value when not provided (only effective for optional arguments) */
+    default?: T;
+    /** Custom value transformation (takes precedence over type conversion) */
+    coerce?: (rawValue: string) => T;
 }
 /** Command configuration */
 interface ICommandConfig {
@@ -91,8 +102,10 @@ interface IActionParams {
     ctx: ICommandContext;
     /** Parsed options */
     opts: Record<string, unknown>;
-    /** Parsed positional arguments */
-    args: string[];
+    /** Parsed positional arguments (keyed by argument name) */
+    args: Record<string, unknown>;
+    /** Raw positional argument strings (before type conversion) */
+    rawArgs: string[];
 }
 /** Action handler function */
 type IAction = (params: IActionParams) => void | Promise<void>;
@@ -109,8 +122,10 @@ interface IRunParams {
 interface IParseResult {
     /** Parsed options */
     opts: Record<string, unknown>;
-    /** Parsed positional arguments */
-    args: string[];
+    /** Parsed positional arguments (keyed by argument name) */
+    args: Record<string, unknown>;
+    /** Raw positional argument strings (before type conversion) */
+    rawArgs: string[];
 }
 /** shift() method result */
 interface IShiftResult {
@@ -120,7 +135,7 @@ interface IShiftResult {
     remaining: string[];
 }
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'ConfigurationError';
+type ICommanderErrorKind = 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
 /** Commander error with structured information */
 declare class CommanderError extends Error {
     readonly kind: ICommanderErrorKind;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",