@guanghechen/commander 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## 4.5.0
+
+### Minor Changes
+
+- Add built-in coerce factories for numeric option parsing in commander.
+
+## 4.4.1
+
+### Patch Changes
+
+- fix(commander): centralize option policy and enforce version flag semantics — subcommands with
+  their own `version` now correctly expose `--version`; commands without `version` reject
+  `--version` instead of treating it as a boolean option.
+
 ## 4.4.0
 
 ### Minor Changes

package/README.md

@@ -202,6 +202,50 @@ new Command({ name: 'example', description: 'Option types demo' })
   })
 ```
 
+### Built-in Coerce Factories
+
+```typescript
+import { Coerce, Command } from '@guanghechen/commander'
+
+new Command({ name: 'example', desc: 'Coerce demo' })
+  .option({
+    long: 'offset',
+    type: 'number',
+    args: 'required',
+    coerce: Coerce.integer('--offset'),
+    desc: 'Signed offset',
+  })
+  .option({
+    long: 'parallel',
+    type: 'number',
+    args: 'required',
+    coerce: Coerce.positiveInteger('--parallel'),
+    desc: 'Parallel workers',
+  })
+  .option({
+    long: 'duration',
+    type: 'number',
+    args: 'required',
+    coerce: Coerce.positiveNumber('--duration'),
+    desc: 'Duration in seconds',
+  })
+  .option({
+    long: 'scale',
+    type: 'number',
+    args: 'required',
+    coerce: Coerce.number('--scale'),
+    desc: 'Scale factor',
+  })
+```
+
+Default error message format:
+
+```text
+{name} is expected as {coerce type}, but got {raw}
+```
+
+You can still override the message via `Coerce.xxx(name, 'custom error message')`.
+
 ### Help Examples
 
 ```typescript

package/lib/cjs/index.cjs

@@ -368,30 +368,29 @@ class Command {
             const routeResult = this.#route(processedArgv);
             const { chain, remaining } = routeResult;
             const leafCommand = chain[chain.length - 1];
-            const rootCommand = chain[0];
             const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
             const { optionTokens, restArgs } = tokenizeResult;
-            const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
-            const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
-            if (!hasUserHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+            const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+            const leafPolicy = this.#mustGetOptionPolicy(optionPolicyMap, leafCommand);
+            if (leafPolicy.enableBuiltinHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
-            if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
+            if (leafPolicy.enableBuiltinVersion) {
                 if (this.#hasFlag(optionTokens, 'version', 'V')) {
                     console.log(leafCommand.#version);
                     return;
                 }
             }
-            const resolveResult = this.#resolve(chain, optionTokens);
+            const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
             const ctx = {
                 cmd: leafCommand,
                 envs,
                 reporter: reporter$1 ?? this.#reporter ?? new reporter.Reporter(),
                 argv,
             };
-            const parseResult = this.#parse(chain, resolveResult, ctx, restArgs);
+            const parseResult = this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
             const actionParams = {
                 ctx: parseResult.ctx,
                 opts: parseResult.opts,
@@ -402,7 +401,7 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
@@ -426,14 +425,15 @@ class Command {
         const leafCommand = chain[chain.length - 1];
         const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
         const { optionTokens, restArgs } = tokenizeResult;
-        const resolveResult = this.#resolve(chain, optionTokens);
+        const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+        const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
         const ctx = {
             cmd: leafCommand,
             envs,
             reporter: reporter$1 ?? this.#reporter ?? new reporter.Reporter(),
             argv,
         };
-        return this.#parse(chain, resolveResult, ctx, restArgs);
+        return this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
     }
     formatHelp() {
         return this.#renderHelpPlain(this.#buildHelpData());
@@ -450,7 +450,7 @@ class Command {
         return color && process.stdout.isTTY === true;
     }
     #buildHelpData() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -587,7 +587,7 @@ class Command {
         return lines.join('\n');
     }
     getCompletionMeta() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const options = [];
         for (const opt of allOptions) {
             options.push({
@@ -675,14 +675,14 @@ class Command {
         }
         return { chain, remaining: argv.slice(idx) };
     }
-    #resolve(chain, tokens) {
+    #resolve(chain, tokens, optionPolicyMap) {
         const consumedTokens = new Map();
         let remaining = [...tokens];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const includeVersion = i === 0;
-            const result = cmd.#shift(remaining, shadowed, includeVersion);
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            const result = cmd.#shift(remaining, shadowed, policy.mergedOptions);
             consumedTokens.set(cmd, result.consumed);
             remaining = result.remaining;
             for (const opt of cmd.#options) {
@@ -699,8 +699,7 @@ class Command {
         }
         return { consumedTokens, argTokens };
     }
-    #shift(tokens, shadowed, includeVersion) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #shift(tokens, shadowed, allOptions) {
         const effectiveOptions = allOptions.filter(o => !shadowed.has(o.long));
         const optionByLong = new Map();
         const optionByShort = new Map();
@@ -768,18 +767,17 @@ class Command {
         }
         return { consumed, remaining };
     }
-    #parse(chain, resolveResult, ctx, restArgs) {
+    #parse(chain, resolveResult, optionPolicyMap, ctx, restArgs) {
         const { consumedTokens, argTokens } = resolveResult;
         const leafCommand = chain[chain.length - 1];
-        this.#validateMergedShortOptions(chain);
+        this.#validateMergedShortOptions(chain, optionPolicyMap);
         const optsMap = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
             const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, includeVersion, ctx.envs);
+            const opts = cmd.#parseOptions(tokens, policy.mergedOptions, ctx.envs);
             optsMap.set(cmd, opts);
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+            for (const opt of policy.mergedOptions) {
                 if (opt.apply && opts[opt.long] !== undefined) {
                     opt.apply(opts[opt.long], ctx);
                 }
@@ -793,8 +791,7 @@ class Command {
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion, envs) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #parseOptions(tokens, allOptions, envs) {
         const opts = {};
         let sawColorToken = false;
         for (const opt of allOptions) {
@@ -976,22 +973,30 @@ class Command {
         }
         return raw;
     }
-    #getMergedOptions(includeVersion = !this.#parent) {
+    #hasUserOption(long) {
+        return this.#options.some(option => option.long === long);
+    }
+    #canUseBuiltinVersion() {
+        return this.#version !== undefined;
+    }
+    #resolveOptionPolicy() {
         const optionMap = new Map();
-        const hasUserColor = this.#options.some(o => o.long === 'color');
-        const hasUserHelp = this.#options.some(o => o.long === 'help');
-        const hasUserVersion = this.#options.some(o => o.long === 'version');
-        const hasUserLogLevel = this.#options.some(o => o.long === 'logLevel');
-        const hasUserSilent = this.#options.some(o => o.long === 'silent');
-        const hasUserLogDate = this.#options.some(o => o.long === 'logDate');
-        const hasUserLogColorful = this.#options.some(o => o.long === 'logColorful');
+        const hasUserColor = this.#hasUserOption('color');
+        const hasUserHelp = this.#hasUserOption('help');
+        const hasUserVersion = this.#hasUserOption('version');
+        const hasUserLogLevel = this.#hasUserOption('logLevel');
+        const hasUserSilent = this.#hasUserOption('silent');
+        const hasUserLogDate = this.#hasUserOption('logDate');
+        const hasUserLogColorful = this.#hasUserOption('logColorful');
+        const enableBuiltinHelp = !hasUserHelp;
+        const enableBuiltinVersion = !hasUserVersion && this.#canUseBuiltinVersion();
         if (this.#builtin.option.color && !hasUserColor) {
             optionMap.set('color', BUILTIN_COLOR_OPTION);
         }
-        if (!hasUserHelp) {
+        if (enableBuiltinHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
-        if (!hasUserVersion && includeVersion) {
+        if (enableBuiltinVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
         if (this.#builtin.option.logLevel && !hasUserLogLevel) {
@@ -1009,14 +1014,31 @@ class Command {
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
-        return Array.from(optionMap.values());
+        return {
+            mergedOptions: Array.from(optionMap.values()),
+            enableBuiltinHelp,
+            enableBuiltinVersion,
+        };
+    }
+    #buildOptionPolicyMap(chain) {
+        const optionPolicyMap = new Map();
+        for (const cmd of chain) {
+            optionPolicyMap.set(cmd, cmd.#resolveOptionPolicy());
+        }
+        return optionPolicyMap;
+    }
+    #mustGetOptionPolicy(optionPolicyMap, cmd) {
+        const policy = optionPolicyMap.get(cmd);
+        if (policy !== undefined) {
+            return policy;
+        }
+        throw new CommanderError('ConfigurationError', `missing option policy for command "${cmd.#getCommandPath()}"`, this.#getCommandPath());
     }
-    #validateMergedShortOptions(chain) {
+    #validateMergedShortOptions(chain, optionPolicyMap) {
         const mergedByLong = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            for (const opt of policy.mergedOptions) {
                 mergedByLong.set(opt.long, opt);
             }
         }
@@ -1112,8 +1134,8 @@ class Command {
             process.exit(1);
         }
     }
-    #resolveHelpColorOption(tokens, envs) {
-        const colorOption = this.#getMergedOptions().find(opt => opt.long === 'color');
+    #resolveHelpColorOption(tokens, envs, policy = this.#resolveOptionPolicy()) {
+        const colorOption = policy.mergedOptions.find(opt => opt.long === 'color');
         let color = !isNoColorEnabled(envs);
         if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
             return color;
@@ -1164,6 +1186,31 @@ class Command {
     }
 }
 
+class Coerce {
+    constructor() { }
+    static create(name, expectedType, validator, errorMessage) {
+        return (rawValue) => {
+            const value = Number(rawValue);
+            if (!validator(value)) {
+                throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
+            }
+            return value;
+        };
+    }
+    static number(name, errorMessage) {
+        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+    }
+    static integer(name, errorMessage) {
+        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+    }
+    static positiveInteger(name, errorMessage) {
+        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+    }
+    static positiveNumber(name, errorMessage) {
+        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+    }
+}
+
 function camelToKebabCase(str) {
     return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
 }
@@ -1523,6 +1570,7 @@ class PwshCompletion {
 }
 
 exports.BashCompletion = BashCompletion;
+exports.Coerce = Coerce;
 exports.Command = Command;
 exports.CommanderError = CommanderError;
 exports.CompletionCommand = CompletionCommand;

package/lib/esm/index.mjs

@@ -346,30 +346,29 @@ class Command {
             const routeResult = this.#route(processedArgv);
             const { chain, remaining } = routeResult;
             const leafCommand = chain[chain.length - 1];
-            const rootCommand = chain[0];
             const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
             const { optionTokens, restArgs } = tokenizeResult;
-            const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
-            const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
-            if (!hasUserHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+            const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+            const leafPolicy = this.#mustGetOptionPolicy(optionPolicyMap, leafCommand);
+            if (leafPolicy.enableBuiltinHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
-            if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
+            if (leafPolicy.enableBuiltinVersion) {
                 if (this.#hasFlag(optionTokens, 'version', 'V')) {
                     console.log(leafCommand.#version);
                     return;
                 }
             }
-            const resolveResult = this.#resolve(chain, optionTokens);
+            const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
             const ctx = {
                 cmd: leafCommand,
                 envs,
                 reporter: reporter ?? this.#reporter ?? new Reporter(),
                 argv,
             };
-            const parseResult = this.#parse(chain, resolveResult, ctx, restArgs);
+            const parseResult = this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
             const actionParams = {
                 ctx: parseResult.ctx,
                 opts: parseResult.opts,
@@ -380,7 +379,7 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
@@ -404,14 +403,15 @@ class Command {
         const leafCommand = chain[chain.length - 1];
         const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
         const { optionTokens, restArgs } = tokenizeResult;
-        const resolveResult = this.#resolve(chain, optionTokens);
+        const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+        const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
         const ctx = {
             cmd: leafCommand,
             envs,
             reporter: reporter ?? this.#reporter ?? new Reporter(),
             argv,
         };
-        return this.#parse(chain, resolveResult, ctx, restArgs);
+        return this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
     }
     formatHelp() {
         return this.#renderHelpPlain(this.#buildHelpData());
@@ -428,7 +428,7 @@ class Command {
         return color && process.stdout.isTTY === true;
     }
     #buildHelpData() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -565,7 +565,7 @@ class Command {
         return lines.join('\n');
     }
     getCompletionMeta() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const options = [];
         for (const opt of allOptions) {
             options.push({
@@ -653,14 +653,14 @@ class Command {
         }
         return { chain, remaining: argv.slice(idx) };
     }
-    #resolve(chain, tokens) {
+    #resolve(chain, tokens, optionPolicyMap) {
         const consumedTokens = new Map();
         let remaining = [...tokens];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const includeVersion = i === 0;
-            const result = cmd.#shift(remaining, shadowed, includeVersion);
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            const result = cmd.#shift(remaining, shadowed, policy.mergedOptions);
             consumedTokens.set(cmd, result.consumed);
             remaining = result.remaining;
             for (const opt of cmd.#options) {
@@ -677,8 +677,7 @@ class Command {
         }
         return { consumedTokens, argTokens };
     }
-    #shift(tokens, shadowed, includeVersion) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #shift(tokens, shadowed, allOptions) {
         const effectiveOptions = allOptions.filter(o => !shadowed.has(o.long));
         const optionByLong = new Map();
         const optionByShort = new Map();
@@ -746,18 +745,17 @@ class Command {
         }
         return { consumed, remaining };
     }
-    #parse(chain, resolveResult, ctx, restArgs) {
+    #parse(chain, resolveResult, optionPolicyMap, ctx, restArgs) {
         const { consumedTokens, argTokens } = resolveResult;
         const leafCommand = chain[chain.length - 1];
-        this.#validateMergedShortOptions(chain);
+        this.#validateMergedShortOptions(chain, optionPolicyMap);
         const optsMap = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
             const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, includeVersion, ctx.envs);
+            const opts = cmd.#parseOptions(tokens, policy.mergedOptions, ctx.envs);
             optsMap.set(cmd, opts);
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+            for (const opt of policy.mergedOptions) {
                 if (opt.apply && opts[opt.long] !== undefined) {
                     opt.apply(opts[opt.long], ctx);
                 }
@@ -771,8 +769,7 @@ class Command {
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion, envs) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #parseOptions(tokens, allOptions, envs) {
         const opts = {};
         let sawColorToken = false;
         for (const opt of allOptions) {
@@ -954,22 +951,30 @@ class Command {
         }
         return raw;
     }
-    #getMergedOptions(includeVersion = !this.#parent) {
+    #hasUserOption(long) {
+        return this.#options.some(option => option.long === long);
+    }
+    #canUseBuiltinVersion() {
+        return this.#version !== undefined;
+    }
+    #resolveOptionPolicy() {
         const optionMap = new Map();
-        const hasUserColor = this.#options.some(o => o.long === 'color');
-        const hasUserHelp = this.#options.some(o => o.long === 'help');
-        const hasUserVersion = this.#options.some(o => o.long === 'version');
-        const hasUserLogLevel = this.#options.some(o => o.long === 'logLevel');
-        const hasUserSilent = this.#options.some(o => o.long === 'silent');
-        const hasUserLogDate = this.#options.some(o => o.long === 'logDate');
-        const hasUserLogColorful = this.#options.some(o => o.long === 'logColorful');
+        const hasUserColor = this.#hasUserOption('color');
+        const hasUserHelp = this.#hasUserOption('help');
+        const hasUserVersion = this.#hasUserOption('version');
+        const hasUserLogLevel = this.#hasUserOption('logLevel');
+        const hasUserSilent = this.#hasUserOption('silent');
+        const hasUserLogDate = this.#hasUserOption('logDate');
+        const hasUserLogColorful = this.#hasUserOption('logColorful');
+        const enableBuiltinHelp = !hasUserHelp;
+        const enableBuiltinVersion = !hasUserVersion && this.#canUseBuiltinVersion();
         if (this.#builtin.option.color && !hasUserColor) {
             optionMap.set('color', BUILTIN_COLOR_OPTION);
         }
-        if (!hasUserHelp) {
+        if (enableBuiltinHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
-        if (!hasUserVersion && includeVersion) {
+        if (enableBuiltinVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
         if (this.#builtin.option.logLevel && !hasUserLogLevel) {
@@ -987,14 +992,31 @@ class Command {
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
-        return Array.from(optionMap.values());
+        return {
+            mergedOptions: Array.from(optionMap.values()),
+            enableBuiltinHelp,
+            enableBuiltinVersion,
+        };
+    }
+    #buildOptionPolicyMap(chain) {
+        const optionPolicyMap = new Map();
+        for (const cmd of chain) {
+            optionPolicyMap.set(cmd, cmd.#resolveOptionPolicy());
+        }
+        return optionPolicyMap;
+    }
+    #mustGetOptionPolicy(optionPolicyMap, cmd) {
+        const policy = optionPolicyMap.get(cmd);
+        if (policy !== undefined) {
+            return policy;
+        }
+        throw new CommanderError('ConfigurationError', `missing option policy for command "${cmd.#getCommandPath()}"`, this.#getCommandPath());
     }
-    #validateMergedShortOptions(chain) {
+    #validateMergedShortOptions(chain, optionPolicyMap) {
         const mergedByLong = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            for (const opt of policy.mergedOptions) {
                 mergedByLong.set(opt.long, opt);
             }
         }
@@ -1090,8 +1112,8 @@ class Command {
             process.exit(1);
         }
     }
-    #resolveHelpColorOption(tokens, envs) {
-        const colorOption = this.#getMergedOptions().find(opt => opt.long === 'color');
+    #resolveHelpColorOption(tokens, envs, policy = this.#resolveOptionPolicy()) {
+        const colorOption = policy.mergedOptions.find(opt => opt.long === 'color');
         let color = !isNoColorEnabled(envs);
         if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
             return color;
@@ -1142,6 +1164,31 @@ class Command {
     }
 }
 
+class Coerce {
+    constructor() { }
+    static create(name, expectedType, validator, errorMessage) {
+        return (rawValue) => {
+            const value = Number(rawValue);
+            if (!validator(value)) {
+                throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
+            }
+            return value;
+        };
+    }
+    static number(name, errorMessage) {
+        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+    }
+    static integer(name, errorMessage) {
+        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+    }
+    static positiveInteger(name, errorMessage) {
+        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+    }
+    static positiveNumber(name, errorMessage) {
+        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+    }
+}
+
 function camelToKebabCase(str) {
     return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
 }
@@ -1500,4 +1547,4 @@ class PwshCompletion {
     }
 }
 
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
+export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };

package/lib/types/index.d.ts

@@ -129,7 +129,7 @@ interface ICommandConfig {
     name?: string;
     /** Command description */
     desc: string;
-    /** Version (for root --version) */
+    /** Version (for built-in --version on this command) */
     version?: string;
     /** Built-in features configuration */
     builtin?: boolean | ICommandBuiltinConfig;
@@ -308,6 +308,20 @@ declare class Command implements ICommand {
     getCompletionMeta(): ICompletionMeta;
 }
 
+/**
+ * Pre-defined coerce factory methods for @guanghechen/commander.
+ *
+ * @module @guanghechen/commander/coerce
+ */
+declare class Coerce {
+    private constructor();
+    private static create;
+    static number(name: string, errorMessage?: string): (rawValue: string) => number;
+    static integer(name: string, errorMessage?: string): (rawValue: string) => number;
+    static positiveInteger(name: string, errorMessage?: string): (rawValue: string) => number;
+    static positiveNumber(name: string, errorMessage?: string): (rawValue: string) => number;
+}
+
 /**
  * Shell completion generators
  *
@@ -436,5 +450,5 @@ declare const logColorfulOption: ICommandOptionConfig<boolean>;
  */
 declare const silentOption: ICommandOptionConfig<boolean>;
 
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
+export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
 export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinCommandConfig, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandConfig, ICommandContext, ICommandExample, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };

package/package.json

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