argv2object 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argv2object",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "private": false,
   "description": "A utility function for converting command-line arguments to a key-value object.",
   "keywords": [
@@ -49,22 +49,27 @@
   "scripts": {
     "test": "cross-env NODE_ENV=test node --test test/*.test.mjs",
     "lint": "npx eslint . --ext .mjs --ext .js --ext .cjs",
-    "prepare": "husky install",
+    "prepare": "husky",
     "prepublish": "npm test"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.8.0",
-    "@commitlint/config-conventional": "^19.8.0",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.57.1",
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/compat": "^1.4.1",
+    "@eslint/core": "^0.17.0",
+    "@eslint/eslintrc": "^3.3.3",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.1",
     "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-config-prettier": "^8.10.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-alias": "^1.1.2",
     "eslint-import-resolver-node": "^0.3.9",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-prettier": "^4.2.1",
-    "husky": "^8.0.3",
-    "lint-staged": "^15.5.2",
-    "prettier": "^2.8.8"
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jsdoc": "^61.4.1",
+    "eslint-plugin-prettier": "^5.5.4",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.3"
   },
   "engines": {
     "node": ">=14.0.0"

package/src/argv2Object.mjs

@@ -24,8 +24,8 @@
  */
 // ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // » IMPORT LOCAL MODULES
-import { REGEXPS, THROWS_ERRORS_MESSAGES } from '#constants';
-import { formatKey, convertValue } from '#functions';
+import { COMMAND_LINE_PATTERNS, ERROR_MESSAGES } from '#constants';
+import { createObjectFromArguments } from '#functions';
 
 // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
@@ -46,7 +46,7 @@ import { formatKey, convertValue } from '#functions';
  * Unix-style command-line options (e.g. "-o --option=value").
  *
  * @function
- * @param {boolean} [unixmode=false] - Whether to parse Unix-style command-line options, the default value is `false`.
+ * @param {boolean} [unixmode] - Whether to parse Unix-style command-line options, the default value is `false`.
  * @returns {ArgvObject} Returns an object with keys and values corresponding to the provided arguments.
  * @throws {TypeError} If `unixmode` is not is not of type `boolean`.
  * @throws {Error} If no arguments are provided from command line.
@@ -56,38 +56,33 @@ import { formatKey, convertValue } from '#functions';
  * ```js
  * // Command line input: node script.js --task=some-task --execute=true
  *
- * const args = argv2Object();
- * console.log(args.task); // prints 'some-task'
- * console.log(args.execute); // prints 'true'
+ * const argumentsv = argv2Object();
+ * console.log(argumentsv.task); // prints 'some-task'
+ * console.log(argumentsv.execute); // prints true
  * ```
  */
 const argv2Object = (unixmode = false) => {
   if (typeof unixmode !== 'boolean') {
-    throw new TypeError(THROWS_ERRORS_MESSAGES.INVALID_UNIXMODE_TYPE);
+    throw new TypeError(ERROR_MESSAGES.INVALID_UNIXMODE_TYPE);
   }
 
   const argumentsv = process.argv.slice(2);
   if (argumentsv.length === 0) {
-    throw new Error(THROWS_ERRORS_MESSAGES.NO_ARGUMENTS);
+    throw new Error(ERROR_MESSAGES.NO_ARGUMENTS);
   }
 
-  const regexp = unixmode ? REGEXPS.UNIXMODE : REGEXPS.SIMPLE;
+  const patterns = unixmode
+    ? [COMMAND_LINE_PATTERNS.UNIX_LONG, COMMAND_LINE_PATTERNS.UNIX_SHORT]
+    : [COMMAND_LINE_PATTERNS.SIMPLE];
 
-  if (!argumentsv.every(argumentv => regexp.test(argumentv))) {
-    const message = unixmode
-      ? THROWS_ERRORS_MESSAGES.NO_MATCH_UNIXMODE
-      : THROWS_ERRORS_MESSAGES.NO_MATCH_SIMPLE;
+  const isValid = argumentsv.every(argument => patterns.some(pattern => pattern.test(argument)));
+
+  if (!isValid) {
+    const message = unixmode ? ERROR_MESSAGES.NO_MATCH_UNIXMODE : ERROR_MESSAGES.NO_MATCH_SIMPLE;
     throw new Error(message);
   }
 
-  const entries = [...argumentsv].map(argumentv => {
-    const [k, v] = argumentv.split('=');
-    const key = formatKey(k, 'snakecase');
-    const value = convertValue(v);
-    return [key, value];
-  });
-
-  return Object.fromEntries(entries);
+  return createObjectFromArguments(argumentsv, 'snakecase');
 };
 
 // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/src/constants.mjs

@@ -12,11 +12,12 @@
 
 // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
- * Regular expression patterns for argument validation.
+ * Type definition for command line argument patterns.
  *
- * @typedef  {object} Regexps
- * @property {RegExp} UNIXMODE - Pattern for Unix-style arguments (-a, --arg=value).
- * @property {RegExp} SIMPLE   - Pattern for simple key=value arguments.
+ * @typedef  {object} CommandLinePatterns
+ * @property {RegExp} UNIX_SHORT          - Matches short Unix flags: `-a`, `-v`, `-f=value`.
+ * @property {RegExp} UNIX_LONG           - Matches long Unix flags: `--help`, `--output=json`.
+ * @property {RegExp} SIMPLE              - Pattern for simple key=value arguments: key=value, multi-part-key=value.
  */
 
 /**
@@ -25,30 +26,60 @@
  * @typedef  {object} ErrorMessages
  * @property {string} INVALID_UNIXMODE_TYPE - When unixmode parameter is not boolean.
  * @property {string} NO_ARGUMENTS          - When no arguments are provided.
- * @property {string} NO_MATCH_SIMPLE       - When simple args don't match key=value format
- * @property {string} NO_MATCH_UNIXMODE     - When args don't match Unix-style format
+ * @property {string} NO_MATCH_SIMPLE       - When simple args don't match key=value format.
+ * @property {string} NO_MATCH_UNIXMODE     - When args don't match Unix-style format.
  */
 
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
- * Regular expressions for validating different argument formats.
+ * Regular expression patterns for validating command line argument formats.
+ *
+ * Provides comprehensive pattern matching for different command line argument
+ * styles commonly used in Node.js applications and CLI tools.
  *
  * @exports
  * @private
- * @constant REGEXPS
- * @type {Regexps}
+ * @constant COMMAND_LINE_PATTERNS
+ * @type {CommandLinePatterns}
+ *
  * @example
- * // Unix-style pattern matches:
- * // -a, -b=value, --flag, --option=value
- * REGEXPS.UNIXMODE.test('--output=json') // true
+ * ```js
+ * // Valid short flags:
+ * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-h')    // true
+ * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-v')    // true
+ * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-f=json') // true
+ *
+ * // Invalid short flags:
+ * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('--help') // false
+ * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-abc')   // false
+ * ```
  *
  * @example
- * // Simple pattern matches:
- * // key=value, multi-part-key=value
- * REGEXPS.SIMPLE.test('output_format=json') // true
+ * ```js
+ * // Valid long flags:
+ * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--help')        // true
+ * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--output=json') // true
+ * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--dry-run')     // true
+ *
+ * // Invalid long flags:
+ * COMMAND_LINE_PATTERNS.UNIX_LONG.test('-h')           // false
+ * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--123')        // false
+ * ```
+ *
+ * @example
+ * ```js
+ * // Valid simple arguments:
+ * COMMAND_LINE_PATTERNS.SIMPLE.test('output=json')          // true
+ * COMMAND_LINE_PATTERNS.SIMPLE.test('config-file=settings') // true
+ *
+ * // Invalid simple arguments:
+ * COMMAND_LINE_PATTERNS.SIMPLE.test('--output=json')        // false
+ * COMMAND_LINE_PATTERNS.SIMPLE.test('output')               // false
+ * ```
  */
-const REGEXPS = {
-  UNIXMODE: /^-[a-z]{1}|-[a-z]{1}=.*$|--[a-zA-Z]+|--[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
+const COMMAND_LINE_PATTERNS = {
+  UNIX_SHORT: /^-[a-zA-Z](=.*)?$/,
+  UNIX_LONG: /^--[a-zA-Z][a-zA-Z0-9-]*(=.*)?$/,
   SIMPLE: /^[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
 };
 
@@ -60,11 +91,13 @@ const REGEXPS = {
  * @constant THROWS_ERRORS_MESSAGES
  * @type {ErrorMessages}
  * @example
+ * ```js
  * // Error cases:
- * throw new Error(THROWS_ERRORS_MESSAGES.INVALID_UNIXMODE_TYPE);
- * throw new Error(THROWS_ERRORS_MESSAGES.NO_ARGUMENTS);
+ * throw new Error(ERROR_MESSAGES.INVALID_UNIXMODE_TYPE);
+ * throw new Error(ERROR_MESSAGES.NO_ARGUMENTS);
+ * ```
  */
-const THROWS_ERRORS_MESSAGES = {
+const ERROR_MESSAGES = {
   INVALID_UNIXMODE_TYPE: 'The "unixmode" parameter must be a boolean value',
   NO_ARGUMENTS: 'No command-line arguments were provided',
   NO_MATCH_SIMPLE: 'Arguments must follow "key=value" format',
@@ -76,7 +109,7 @@ const THROWS_ERRORS_MESSAGES = {
  * Exported constants for argument validation.
  *
  * @type {object}
- * @property {Regexps}       REGEXPS                - Validation patterns.
- * @property {ErrorMessages} THROWS_ERRORS_MESSAGES - Standard error messages.
+ * @property {CommandLinePatterns} REGEXPS                - Validation patterns.
+ * @property {ErrorMessages}       THROWS_ERRORS_MESSAGES - Standard error messages.
  */
-export { REGEXPS, THROWS_ERRORS_MESSAGES };
+export { COMMAND_LINE_PATTERNS, ERROR_MESSAGES };

package/src/functions.mjs

@@ -17,21 +17,23 @@
  *
  * Supports:
  *
- * - camelCase conversion (--some-flag → someFlag)
- * - snake_case conversion (--some-flag → some_flag)
- * - No conversion (--some-flag → some-flag)
+ * - camelCase conversion (--some-flag → someFlag).
+ * - snake_case conversion (--some-flag → some_flag).
+ * - No conversion (--some-flag → some-flag).
  *
  * @exports
  * @private
  * @function formatKey
- * @param {string} key - The raw key from command-line arguments
- * @param {'camelcase'|'snakecase'} [mode] - Target formatting mode
- * @returns {string} Normalized and formatted key
- * @throws {TypeError} If key is not a string
+ * @param {string} key - The raw key from command-line arguments.
+ * @param {'camelcase'|'snakecase'} [mode] - Target formatting mode.
+ * @returns {string} Normalized and formatted key.
+ * @throws {TypeError} If key is not a string.
  * @example
+ * ```js
  * formatKey('--output-format', 'camelcase') // returns 'outputFormat'
  * formatKey('-v', 'snakecase') // returns 'v' (no underscores needed)
  * formatKey('--enable-logging') // returns 'enable-logging'
+ * ```
  */
 const formatKey = (key, mode) => {
   if (typeof key !== 'string') {
@@ -55,21 +57,23 @@ const formatKey = (key, mode) => {
  *
  * Performs automatic conversion of:
  *
- * - 'true'/'false' strings → boolean
- * - Numeric strings → number
- * - undefined values → true (for flag arguments)
- * - All other values remain as strings
+ * - 'true'/'false' strings → boolean.
+ * - Numeric strings → number.
+ * - undefined values → true (for flag arguments).
+ * - All other values remain as strings.
  *
  * @exports
  * @private
  * @function convertValue
- * @param {string} [value] - The value to convert
- * @returns {string|boolean|number} Converted value
+ * @param {string} [value] - The value to convert.
+ * @returns {string|boolean|number} Converted value.
  * @example
+ * ```js
  * convertValue('true') // returns true
  * convertValue('42') // returns 42
  * convertValue() // returns true (for flag arguments)
  * convertValue('text') // returns 'text'
+ * ```
  */
 const convertValue = value => {
   if (value === undefined) return true;
@@ -79,6 +83,36 @@ const convertValue = value => {
   return value;
 };
 
+/**
+ * Creates an object from command line arguments by parsing key-value pairs.
+ *
+ * @param {string[]} argumentsv - Array of command line arguments to process.
+ * @param {'camelcase'|'snakecase'} mode - Target formatting mode.
+ * @returns {object} Object with parsed keys and converted values.
+ * @throws {Error} When arguments cannot be parsed into valid key-value pairs.
+ *
+ * @example
+ * ```js
+ * // Simple mode: key=value pairs
+ * createObjectFromArguments(['name=John', 'age=30'], 'snakecase');
+ * // Returns: { name: 'John', age: 30 }
+ *
+ * // Unix mode: flags and options
+ * createObjectFromArguments(['--name=John', '-a'], 'snakecase');
+ * // Returns: { name: 'John', a: true }
+ * ```
+ */
+const createObjectFromArguments = (argumentsv, mode) => {
+  const entries = [...argumentsv].map(argumentv => {
+    const [k, v] = argumentv.split('=');
+    const key = formatKey(k, mode);
+    const value = convertValue(v);
+    return [key, value];
+  });
+
+  return Object.fromEntries(entries);
+};
+
 // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
  * Utility functions for argument processing.
@@ -87,4 +121,4 @@ const convertValue = value => {
  * @property {Function} formatKey    - Key formatting/normalization function.
  * @property {Function} convertValue - Value type conversion function.
  */
-export { formatKey, convertValue };
+export { formatKey, convertValue, createObjectFromArguments };