@guanghechen/commander 4.4.1 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## 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,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

@@ -1186,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());
 }
@@ -1545,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

@@ -1164,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());
 }
@@ -1522,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

@@ -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.1",
+  "version": "4.5.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",