@guanghechen/commander 4.4.1 → 4.5.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## 4.5.1
+
+### Patch Changes
+
+- Add built-in host and network validators (ip, domain, host), expose is helpers, and extend coerce
+  factories with port and choice support.
+
+## 4.5.0
+
+### Minor Changes
+
+- Add built-in coerce factories for numeric option parsing in commander.
+
 ## 4.4.1
 
 ### Patch Changes

package/README.md

@@ -202,6 +202,96 @@ 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: 'port',
+    type: 'number',
+    args: 'required',
+    coerce: Coerce.port('--port'),
+    desc: 'Server port',
+  })
+  .option({
+    long: 'domain',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.domain('--domain'),
+    desc: 'Domain name',
+  })
+  .option({
+    long: 'ip',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.ip('--ip'),
+    desc: 'IP address',
+  })
+  .option({
+    long: 'host',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.host('--host'),
+    desc: 'Host (IP or domain)',
+  })
+  .option({
+    long: 'mode',
+    type: 'string',
+    args: 'required',
+    coerce: Coerce.choice('--mode', ['dev', 'test', 'prod'] as const),
+    desc: 'Deploy mode',
+  })
+  .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')`.
+
+### Built-in Is Helpers
+
+```typescript
+import { isDomain, isIp, isIpv4, isIpv6 } from '@guanghechen/commander'
+
+isIpv4('127.0.0.1') // true
+isIpv6('::1') // true
+isIp('2001:db8::1') // true
+isDomain('example.com') // true
+```
+
 ### Help Examples
 
 ```typescript
@@ -219,11 +309,11 @@ await cli.run({ argv: ['--help'], envs: process.env })
 
 `usage` 是相对当前 command path 的片段，help 中会自动补齐前缀，例如 `mycli build --watch`。
 
-`--color` / `--no-color` 仅控制 help 文本的终端着色；
-`--log-colorful` / `--no-log-colorful` 控制 `Reporter` 的日志着色。
+`--color` / `--no-color` 仅控制 help 文本的终端着色； `--log-colorful` / `--no-log-colorful` 控制
+`Reporter` 的日志着色。
 
-当环境变量 `NO_COLOR` 存在时，help 渲染默认视为 `--no-color`；
-显式传入 `--color` 可以覆盖这个默认值。
+当环境变量 `NO_COLOR` 存在时，help 渲染默认视为 `--no-color`；显式传入 `--color`
+可以覆盖这个默认值。
 
 ## Reference
 

package/lib/cjs/index.cjs

@@ -1186,6 +1186,156 @@ class Command {
     }
 }
 
+function isIpv4(rawValue) {
+    const parts = rawValue.split('.');
+    if (parts.length !== 4) {
+        return false;
+    }
+    for (const part of parts) {
+        if (part.length < 1 || !/^\d+$/.test(part)) {
+            return false;
+        }
+        if (part.length > 1 && part.startsWith('0')) {
+            return false;
+        }
+        const value = Number(part);
+        if (!Number.isInteger(value) || value < 0 || value > 255) {
+            return false;
+        }
+    }
+    return true;
+}
+function countIpv6Segments(part, allowIpv4Tail) {
+    if (!part) {
+        return { count: 0, hasIpv4Tail: false };
+    }
+    const segments = part.split(':');
+    let count = 0;
+    let hasIpv4Tail = false;
+    for (let i = 0; i < segments.length; ++i) {
+        const segment = segments[i];
+        const isLastSegment = i === segments.length - 1;
+        if (!segment) {
+            return null;
+        }
+        if (segment.includes('.')) {
+            if (!allowIpv4Tail || !isLastSegment || hasIpv4Tail || !isIpv4(segment)) {
+                return null;
+            }
+            hasIpv4Tail = true;
+            count += 2;
+            continue;
+        }
+        if (!/^[0-9A-Fa-f]{1,4}$/.test(segment)) {
+            return null;
+        }
+        count += 1;
+    }
+    return { count, hasIpv4Tail };
+}
+function isIpv6(rawValue) {
+    if (!rawValue || !/^[0-9A-Fa-f:.]+$/.test(rawValue)) {
+        return false;
+    }
+    const doubleColonCount = rawValue.split('::').length - 1;
+    if (doubleColonCount > 1) {
+        return false;
+    }
+    if (doubleColonCount === 0) {
+        const full = countIpv6Segments(rawValue, true);
+        return full !== null && full.count === 8;
+    }
+    const [left, right] = rawValue.split('::');
+    const leftPart = countIpv6Segments(left, right.length === 0);
+    const rightPart = countIpv6Segments(right, true);
+    if (!leftPart || !rightPart) {
+        return false;
+    }
+    const totalSegments = leftPart.count + rightPart.count;
+    return totalSegments < 8;
+}
+function isIp(rawValue) {
+    return isIpv4(rawValue) || isIpv6(rawValue);
+}
+function isDomain(rawValue) {
+    if (rawValue.length < 1 || rawValue.length > 253 || rawValue.endsWith('.')) {
+        return false;
+    }
+    const labels = rawValue.split('.');
+    if (labels.length < 2) {
+        return false;
+    }
+    if (labels.some(label => label.length < 1 || label.length > 63)) {
+        return false;
+    }
+    const labelPattern = /^[A-Za-z0-9-]+$/;
+    if (labels.some(label => !labelPattern.test(label) || label.startsWith('-') || label.endsWith('-'))) {
+        return false;
+    }
+    const topLevelLabel = labels[labels.length - 1];
+    return /[A-Za-z]/.test(topLevelLabel);
+}
+
+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 choice(name, values, errorMessage) {
+        return (rawValue) => {
+            if (values.includes(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as one of [${values.join(', ')}], but got ${rawValue}`);
+        };
+    }
+    static domain(name, errorMessage) {
+        return (rawValue) => {
+            if (isDomain(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid domain, but got ${rawValue}`);
+        };
+    }
+    static host(name, errorMessage) {
+        return (rawValue) => {
+            if (isIp(rawValue) || isDomain(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid host (IP or domain), but got ${rawValue}`);
+        };
+    }
+    static integer(name, errorMessage) {
+        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+    }
+    static ip(name, errorMessage) {
+        return (rawValue) => {
+            if (isIp(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid IP address, but got ${rawValue}`);
+        };
+    }
+    static number(name, errorMessage) {
+        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+    }
+    static port(name, errorMessage) {
+        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, 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());
 }
@@ -1545,11 +1695,16 @@ class PwshCompletion {
 }
 
 exports.BashCompletion = BashCompletion;
+exports.Coerce = Coerce;
 exports.Command = Command;
 exports.CommanderError = CommanderError;
 exports.CompletionCommand = CompletionCommand;
 exports.FishCompletion = FishCompletion;
 exports.PwshCompletion = PwshCompletion;
+exports.isDomain = isDomain;
+exports.isIp = isIp;
+exports.isIpv4 = isIpv4;
+exports.isIpv6 = isIpv6;
 exports.logColorfulOption = logColorfulOption;
 exports.logDateOption = logDateOption;
 exports.logLevelOption = logLevelOption;

package/lib/esm/index.mjs

@@ -1164,6 +1164,156 @@ class Command {
     }
 }
 
+function isIpv4(rawValue) {
+    const parts = rawValue.split('.');
+    if (parts.length !== 4) {
+        return false;
+    }
+    for (const part of parts) {
+        if (part.length < 1 || !/^\d+$/.test(part)) {
+            return false;
+        }
+        if (part.length > 1 && part.startsWith('0')) {
+            return false;
+        }
+        const value = Number(part);
+        if (!Number.isInteger(value) || value < 0 || value > 255) {
+            return false;
+        }
+    }
+    return true;
+}
+function countIpv6Segments(part, allowIpv4Tail) {
+    if (!part) {
+        return { count: 0, hasIpv4Tail: false };
+    }
+    const segments = part.split(':');
+    let count = 0;
+    let hasIpv4Tail = false;
+    for (let i = 0; i < segments.length; ++i) {
+        const segment = segments[i];
+        const isLastSegment = i === segments.length - 1;
+        if (!segment) {
+            return null;
+        }
+        if (segment.includes('.')) {
+            if (!allowIpv4Tail || !isLastSegment || hasIpv4Tail || !isIpv4(segment)) {
+                return null;
+            }
+            hasIpv4Tail = true;
+            count += 2;
+            continue;
+        }
+        if (!/^[0-9A-Fa-f]{1,4}$/.test(segment)) {
+            return null;
+        }
+        count += 1;
+    }
+    return { count, hasIpv4Tail };
+}
+function isIpv6(rawValue) {
+    if (!rawValue || !/^[0-9A-Fa-f:.]+$/.test(rawValue)) {
+        return false;
+    }
+    const doubleColonCount = rawValue.split('::').length - 1;
+    if (doubleColonCount > 1) {
+        return false;
+    }
+    if (doubleColonCount === 0) {
+        const full = countIpv6Segments(rawValue, true);
+        return full !== null && full.count === 8;
+    }
+    const [left, right] = rawValue.split('::');
+    const leftPart = countIpv6Segments(left, right.length === 0);
+    const rightPart = countIpv6Segments(right, true);
+    if (!leftPart || !rightPart) {
+        return false;
+    }
+    const totalSegments = leftPart.count + rightPart.count;
+    return totalSegments < 8;
+}
+function isIp(rawValue) {
+    return isIpv4(rawValue) || isIpv6(rawValue);
+}
+function isDomain(rawValue) {
+    if (rawValue.length < 1 || rawValue.length > 253 || rawValue.endsWith('.')) {
+        return false;
+    }
+    const labels = rawValue.split('.');
+    if (labels.length < 2) {
+        return false;
+    }
+    if (labels.some(label => label.length < 1 || label.length > 63)) {
+        return false;
+    }
+    const labelPattern = /^[A-Za-z0-9-]+$/;
+    if (labels.some(label => !labelPattern.test(label) || label.startsWith('-') || label.endsWith('-'))) {
+        return false;
+    }
+    const topLevelLabel = labels[labels.length - 1];
+    return /[A-Za-z]/.test(topLevelLabel);
+}
+
+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 choice(name, values, errorMessage) {
+        return (rawValue) => {
+            if (values.includes(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as one of [${values.join(', ')}], but got ${rawValue}`);
+        };
+    }
+    static domain(name, errorMessage) {
+        return (rawValue) => {
+            if (isDomain(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid domain, but got ${rawValue}`);
+        };
+    }
+    static host(name, errorMessage) {
+        return (rawValue) => {
+            if (isIp(rawValue) || isDomain(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid host (IP or domain), but got ${rawValue}`);
+        };
+    }
+    static integer(name, errorMessage) {
+        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+    }
+    static ip(name, errorMessage) {
+        return (rawValue) => {
+            if (isIp(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid IP address, but got ${rawValue}`);
+        };
+    }
+    static number(name, errorMessage) {
+        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+    }
+    static port(name, errorMessage) {
+        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, 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());
 }
@@ -1522,4 +1672,4 @@ class PwshCompletion {
     }
 }
 
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
+export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, silentOption };

package/lib/types/index.d.ts

@@ -223,6 +223,56 @@ interface ICommandParseResult {
     /** Raw argument strings */
     rawArgs: string[];
 }
+/** Built-in option resolution result (internal) */
+interface ICommandBuiltinOptionResolved {
+    color: boolean;
+    logLevel: boolean;
+    silent: boolean;
+    logDate: boolean;
+    logColorful: boolean;
+}
+/** Built-in config resolution result (internal) */
+interface ICommandBuiltinResolved {
+    option: ICommandBuiltinOptionResolved;
+    command: {
+        help: boolean;
+    };
+}
+/** Subcommand registry entry (internal) */
+interface ISubcommandEntry<TCommand = ICommand> {
+    name: string;
+    aliases: string[];
+    command: TCommand;
+}
+/** Internal route result */
+interface IInternalRouteResult<TCommand = ICommand> {
+    chain: TCommand[];
+    remaining: string[];
+}
+/** Help option line (internal) */
+interface IHelpOptionLine {
+    sig: string;
+    desc: string;
+}
+/** Help command line (internal) */
+interface IHelpCommandLine {
+    name: string;
+    desc: string;
+}
+/** Help example line (internal) */
+interface IHelpExampleLine {
+    title: string;
+    usage: string;
+    desc: string;
+}
+/** Structured help data for rendering (internal) */
+interface IHelpData {
+    desc: string;
+    usage: string;
+    options: IHelpOptionLine[];
+    commands: IHelpCommandLine[];
+    examples: IHelpExampleLine[];
+}
 /** Error kinds for command parsing */
 type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
 /** Commander error with structured information */
@@ -308,6 +358,30 @@ 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 choice<TValue extends string>(name: string, values: ReadonlyArray<TValue>, errorMessage?: string): (rawValue: string) => TValue;
+    static domain(name: string, errorMessage?: string): (rawValue: string) => string;
+    static host(name: string, errorMessage?: string): (rawValue: string) => string;
+    static integer(name: string, errorMessage?: string): (rawValue: string) => number;
+    static ip(name: string, errorMessage?: string): (rawValue: string) => string;
+    static number(name: string, errorMessage?: string): (rawValue: string) => number;
+    static port(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;
+}
+
+declare function isIpv4(rawValue: string): boolean;
+declare function isIpv6(rawValue: string): boolean;
+declare function isIp(rawValue: string): boolean;
+declare function isDomain(rawValue: string): boolean;
+
 /**
  * Shell completion generators
  *
@@ -436,5 +510,5 @@ declare const logColorfulOption: ICommandOptionConfig<boolean>;
  */
 declare const silentOption: ICommandOptionConfig<boolean>;
 
-export { BashCompletion, 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 };
+export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, silentOption };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinCommandConfig, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandExample, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, IInternalRouteResult, ISubcommandEntry };

package/package.json

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