@nu-art/cli-params 0.401.2

package/CLIParamsResolver.d.ts

@@ -0,0 +1,80 @@
+import { BaseCliParam, CliParams } from './types.js';
+/**
+ * Type-safe CLI parameter resolver and parser.
+ *
+ * Parses command-line arguments (`process.argv`) into a typed object based on
+ * parameter definitions. Supports:
+ * - Multiple keys/aliases per parameter
+ * - Type validation and conversion
+ * - Default values and initial values
+ * - Option validation (restrict to specific values)
+ * - Array parameters (collect multiple values)
+ * - Dependencies (set other params based on current param)
+ * - Quoted string handling
+ *
+ * **Usage**:
+ * ```typescript
+ * const resolver = CLIParamsResolver.create(
+ *   { keys: ['--name', '-n'], keyName: 'name', type: 'string', description: 'Name' },
+ *   { keys: ['--count'], keyName: 'count', type: 'number', defaultValue: 1 }
+ * );
+ * const params = resolver.resolveParamValue();
+ * // params.name: string, params.count: number
+ * ```
+ *
+ * @template T - Array of BaseCliParam definitions
+ * @template Output - Resolved parameters object type
+ */
+export declare class CLIParamsResolver<T extends BaseCliParam<string, any>[], Output extends CliParams<T> = CliParams<T>> {
+    /** Processed parameters with all required fields filled */
+    private params;
+    /**
+     * Creates a CLIParamsResolver instance.
+     *
+     * @template T - Array of BaseCliParam definitions
+     * @param params - Parameter definitions
+     * @returns New CLIParamsResolver instance
+     */
+    static create<T extends BaseCliParam<string, any>[]>(...params: T): CLIParamsResolver<T, CliParams<T>>;
+    /**
+     * Creates a CLIParamsResolver and processes parameters.
+     *
+     * @param params - Parameter definitions (may be incomplete)
+     */
+    private constructor();
+    /**
+     * Parses command-line arguments into a typed parameters object.
+     *
+     * **Parsing Behavior**:
+     * - Splits arguments by `=` (e.g., `--key=value`)
+     * - Strips quotes from values and unescapes quotes
+     * - Processes values using parameter processors
+     * - Validates against options if provided
+     * - Handles dependencies (sets dependent params)
+     * - Accumulates array values (removes duplicates)
+     * - Applies initial values for missing params
+     * - Warns when overriding non-array values
+     *
+     * **Input Format**: `--key=value` or `--key value` (space-separated not supported)
+     *
+     * @param inputParams - Command-line arguments (default: `process.argv.slice(2)`)
+     * @returns Typed object with resolved parameter values
+     * @throws Error if value not in options, or if required value missing
+     */
+    resolveParamValue(inputParams?: string[]): Output;
+    /**
+     * Find the matching param by finding it's key in the current argument
+     * Go over the app params and find the CLIParam object representing it
+     * @param inputParam The current console argument being parsed
+     * @returns The CliParam or undefined if not found
+     * @private
+     */
+    private findMatchingParamToResolve;
+    /**
+     * Translate BaseCLIParams passed to the constructor to CLIParams
+     * @param params User input of CLI params being passed to the constructor
+     * @private
+     * @returns CLI Params filled with all mandatory data
+     */
+    private translate;
+}

package/CLIParamsResolver.js

@@ -0,0 +1,150 @@
+import { asArray, exists, filterDuplicates, StaticLogger } from '@nu-art/ts-common';
+import { DefaultProcessorsMapper } from './consts.js';
+/**
+ * Type-safe CLI parameter resolver and parser.
+ *
+ * Parses command-line arguments (`process.argv`) into a typed object based on
+ * parameter definitions. Supports:
+ * - Multiple keys/aliases per parameter
+ * - Type validation and conversion
+ * - Default values and initial values
+ * - Option validation (restrict to specific values)
+ * - Array parameters (collect multiple values)
+ * - Dependencies (set other params based on current param)
+ * - Quoted string handling
+ *
+ * **Usage**:
+ * ```typescript
+ * const resolver = CLIParamsResolver.create(
+ *   { keys: ['--name', '-n'], keyName: 'name', type: 'string', description: 'Name' },
+ *   { keys: ['--count'], keyName: 'count', type: 'number', defaultValue: 1 }
+ * );
+ * const params = resolver.resolveParamValue();
+ * // params.name: string, params.count: number
+ * ```
+ *
+ * @template T - Array of BaseCliParam definitions
+ * @template Output - Resolved parameters object type
+ */
+export class CLIParamsResolver {
+    /** Processed parameters with all required fields filled */
+    params;
+    /**
+     * Creates a CLIParamsResolver instance.
+     *
+     * @template T - Array of BaseCliParam definitions
+     * @param params - Parameter definitions
+     * @returns New CLIParamsResolver instance
+     */
+    static create(...params) {
+        return new CLIParamsResolver(params);
+    }
+    /**
+     * Creates a CLIParamsResolver and processes parameters.
+     *
+     * @param params - Parameter definitions (may be incomplete)
+     */
+    constructor(params) {
+        this.params = this.translate(params);
+    }
+    /**
+     * Parses command-line arguments into a typed parameters object.
+     *
+     * **Parsing Behavior**:
+     * - Splits arguments by `=` (e.g., `--key=value`)
+     * - Strips quotes from values and unescapes quotes
+     * - Processes values using parameter processors
+     * - Validates against options if provided
+     * - Handles dependencies (sets dependent params)
+     * - Accumulates array values (removes duplicates)
+     * - Applies initial values for missing params
+     * - Warns when overriding non-array values
+     *
+     * **Input Format**: `--key=value` or `--key value` (space-separated not supported)
+     *
+     * @param inputParams - Command-line arguments (default: `process.argv.slice(2)`)
+     * @returns Typed object with resolved parameter values
+     * @throws Error if value not in options, or if required value missing
+     */
+    resolveParamValue(inputParams = process.argv.slice(2, process.argv.length)) {
+        const runtimeParams = inputParams.reduce((output, inputParam) => {
+            let [key, value] = inputParam.split('=');
+            const cliParamToResolve = this.findMatchingParamToResolve(key);
+            if (!cliParamToResolve)
+                return output;
+            if (value && value.startsWith('"') && value.endsWith('"')) {
+                value = value.slice(1, -1);
+                value = value.replace(/\\"/g, '"');
+            }
+            const finalValue = cliParamToResolve.process(value, cliParamToResolve.defaultValue);
+            // validate options if exits
+            if (cliParamToResolve.options && !cliParamToResolve.options.includes(finalValue))
+                throw new Error(`value not supported for param: ${cliParamToResolve.name}, supported values: ${cliParamToResolve.options.join(', ')}`);
+            const keyName = cliParamToResolve.keyName;
+            if (exists(cliParamToResolve.dependencies))
+                cliParamToResolve.dependencies?.forEach(dependency => {
+                    // If dependency value is a function, call it with the current param's processed value
+                    const dependencyValue = typeof dependency.value === 'function'
+                        ? dependency.value(finalValue)
+                        : dependency.value;
+                    output[dependency.param.keyName] = dependencyValue;
+                });
+            if (cliParamToResolve.isArray) {
+                let currentValues = output[keyName];
+                currentValues = filterDuplicates([...(currentValues ?? []), ...asArray(finalValue)]);
+                output[keyName] = currentValues;
+                return output;
+            }
+            //if already exists and the value ain't an array warn that the value will be overridden
+            if (output[keyName])
+                StaticLogger.logWarning(`this param does not accept multiple values, overriding prev value: ${output[keyName]}`);
+            //Apply a single value to the object
+            output[keyName] = finalValue;
+            return output;
+        }, {});
+        this.params.filter(param => exists(param.initialValue) && !exists(runtimeParams[param.keyName])).forEach(param => {
+            runtimeParams[param.keyName] = param.initialValue;
+        });
+        return runtimeParams;
+    }
+    /**
+     * Find the matching param by finding it's key in the current argument
+     * Go over the app params and find the CLIParam object representing it
+     * @param inputParam The current console argument being parsed
+     * @returns The CliParam or undefined if not found
+     * @private
+     */
+    findMatchingParamToResolve(inputParam) {
+        let matchingParam;
+        this.params.forEach((param) => {
+            param.keys.forEach((key) => {
+                if (inputParam === key)
+                    matchingParam = param;
+                if (inputParam.startsWith(`${key}=`))
+                    matchingParam = param;
+            });
+        });
+        return matchingParam;
+    }
+    /**
+     * Translate BaseCLIParams passed to the constructor to CLIParams
+     * @param params User input of CLI params being passed to the constructor
+     * @private
+     * @returns CLI Params filled with all mandatory data
+     */
+    translate(params) {
+        return params.map(param => {
+            //If name is not defined apply key name as the param name
+            if (!param.name)
+                param.name = param.keyName;
+            //If no processor is passed apply default by type
+            if (!param.process) {
+                param.process = DefaultProcessorsMapper[param.type.split('[')[0].trim()];
+            }
+            //Determine if value is array by the param type TODO: improve this chunk of code, this is not strict enough
+            if (!exists(param.isArray) && param.type.includes('[]'))
+                param.isArray = true;
+            return param;
+        });
+    }
+}

package/consts.d.ts

@@ -0,0 +1,43 @@
+import { TypedMap } from '@nu-art/ts-common';
+import { CliParam } from './types.js';
+/**
+ * Default processor for boolean CLI parameters.
+ *
+ * Returns the defaultValue or `true` if the flag is present
+ *
+ * @param input - Optional input string (flag presence indicator)
+ * @param defaultValue - Optional default value if flag is absent
+ * @returns `true` if flag is present, otherwise `defaultValue ?? false`
+ */
+export declare const DefaultProcessor_Boolean: CliParam<any, boolean>['process'];
+/**
+ * Default processor for string CLI parameters.
+ *
+ * Returns the input string, or defaultValue if input is empty/missing.
+ * Throws if input is empty and no default is provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Processed string value
+ * @throws Error if input is empty and no default provided
+ */
+export declare const DefaultProcessor_String: CliParam<any, string>['process'];
+/**
+ * Default processor for number CLI parameters.
+ *
+ * Parses the input as a number, or returns defaultValue if input is missing.
+ * Throws if input is not a valid number or if input is empty and no default provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Parsed number value
+ * @throws Error if input is not a number or missing with no default
+ */
+export declare const DefaultProcessor_Number: CliParam<any, number>['process'];
+/**
+ * Map of default processors by type name.
+ *
+ * Used by CLIParamsResolver to assign processors when not provided.
+ * Keys match the type strings from `TypeOfTypeAsString`.
+ */
+export declare const DefaultProcessorsMapper: TypedMap<CliParam<any, any>['process']>;

package/consts.js

@@ -0,0 +1,64 @@
+import { exists } from '@nu-art/ts-common';
+/**
+ * Default processor for boolean CLI parameters.
+ *
+ * Returns the defaultValue or `true` if the flag is present
+ *
+ * @param input - Optional input string (flag presence indicator)
+ * @param defaultValue - Optional default value if flag is absent
+ * @returns `true` if flag is present, otherwise `defaultValue ?? false`
+ */
+export const DefaultProcessor_Boolean = (input, defaultValue) => {
+    return defaultValue ?? true;
+};
+/**
+ * Default processor for string CLI parameters.
+ *
+ * Returns the input string, or defaultValue if input is empty/missing.
+ * Throws if input is empty and no default is provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Processed string value
+ * @throws Error if input is empty and no default provided
+ */
+export const DefaultProcessor_String = (input, defaultValue) => {
+    if (!input || !input.length) {
+        if (!exists(defaultValue))
+            throw new Error('expected string value');
+        return defaultValue;
+    }
+    return input;
+};
+/**
+ * Default processor for number CLI parameters.
+ *
+ * Parses the input as a number, or returns defaultValue if input is missing.
+ * Throws if input is not a valid number or if input is empty and no default provided.
+ *
+ * @param input - Optional input string
+ * @param defaultValue - Optional default value
+ * @returns Parsed number value
+ * @throws Error if input is not a number or missing with no default
+ */
+export const DefaultProcessor_Number = (input, defaultValue) => {
+    if (!input) {
+        if (!exists(defaultValue))
+            throw new Error('expected number value');
+        return defaultValue;
+    }
+    if (isNaN(Number(input)))
+        throw new Error('expected number value');
+    return Number(input);
+};
+/**
+ * Map of default processors by type name.
+ *
+ * Used by CLIParamsResolver to assign processors when not provided.
+ * Keys match the type strings from `TypeOfTypeAsString`.
+ */
+export const DefaultProcessorsMapper = {
+    string: DefaultProcessor_String,
+    boolean: DefaultProcessor_Boolean,
+    number: DefaultProcessor_Number,
+};

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './consts.js';
+export * from './CLIParamsResolver.js';

package/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './consts.js';
+export * from './CLIParamsResolver.js';

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nu-art/cli-params",
+  "version": "0.401.2",
+  "description": "Shell command execution framework with interactive sessions, CLI parameter resolution, and plugin system for building and executing shell scripts programmatically",
+  "type": "module",
+  "keywords": [
+    "shell",
+    "command-execution",
+    "cli",
+    "bash",
+    "interactive-shell",
+    "shell-scripts",
+    "cli-params",
+    "command-line",
+    "nu-art",
+    "thunderstorm",
+    "cli-params",
+    "typescript"
+  ],
+  "homepage": "https://github.com/nu-art-js/thunderstorm",
+  "bugs": {
+    "url": "https://github.com/nu-art-js/thunderstorm/issues?q=is%3Aissue+label%3Acli-params"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:nu-art-js/thunderstorm.git",
+    "directory": "_thunderstorm/cli-params"
+  },
+  "publishConfig": {
+    "directory": "dist"
+  },
+  "license": "Apache-2.0",
+  "author": "TacB0sS",
+  "files": [
+    "**/*"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@nu-art/ts-common": "0.401.2"
+  },
+  "devDependencies": {
+    "@nu-art/testalot": "0.401.2"
+  },
+  "unitConfig": {
+    "type": "typescript-lib"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  }
+}

package/types.d.ts

@@ -0,0 +1,56 @@
+import { Primitive, TypeOfTypeAsString } from '@nu-art/ts-common';
+export type CliParams<T extends BaseCliParam<string, any>[]> = {
+    [K in T[number]['keyName']]: NonNullable<Extract<T[number], {
+        keyName: K;
+    }>['defaultValue']>;
+};
+export type DependencyParam<T extends Primitive | Primitive[]> = {
+    param: BaseCliParam<string, T>;
+    value: T | ((currentValue: any) => T);
+};
+/**
+ * Base CLI parameter definition (before processing).
+ *
+ * Defines a command-line parameter with keys, type, and optional features.
+ * Can be incomplete (missing name/process) and will be filled by CLIParamsResolver.
+ *
+ * **Features**:
+ * - Multiple keys (aliases): `['--help', '-h']`
+ * - Type validation: `'string'`, `'number'`, `'boolean'`, `'string[]'`, etc.
+ * - Options validation: Restrict values to specific options
+ * - Dependencies: Set other params based on this param's value
+ * - Array support: Collect multiple values
+ *
+ * @template K - Key name type (string literal)
+ * @template V - Value type (primitive or array)
+ */
+export type BaseCliParam<K extends string, V extends Primitive | Primitive[]> = {
+    /** Array of CLI keys/aliases (e.g., `['--help', '-h']`) */
+    keys: string[];
+    /** Unique key name for the resolved object */
+    keyName: K;
+    /** Type string representation (e.g., `'string'`, `'number[]'`) */
+    type: TypeOfTypeAsString<V>;
+    /** Human-readable description */
+    description: string;
+    /** Optional parameter name (defaults to keyName) */
+    name?: string;
+    /** Optional array of allowed values (validates input) */
+    options?: string[];
+    /** Initial value if param not provided */
+    initialValue?: V;
+    /** Default value if param provided but empty */
+    defaultValue?: V;
+    /** Optional processor function (defaults by type) */
+    process?: (value?: string, defaultValue?: V) => V;
+    /** Whether this param accepts multiple values (array) */
+    isArray?: true;
+    /** Optional grouping for help/validation */
+    group?: string;
+    /** Parameters that depend on this one */
+    dependencies?: DependencyParam<any>[];
+};
+export type CliParam<K extends string, V extends Primitive | Primitive[]> = BaseCliParam<K, V> & {
+    name: string;
+    process: (value?: string, defaultValue?: V) => V;
+};

package/types.js

@@ -0,0 +1 @@
+export {};