argv2object 1.1.0 → 1.1.2

package/README.md

@@ -7,6 +7,7 @@ A utility function for converting command-line arguments to a key-value object.
 - [Installation](#installation)
 - [Importing](#importing)
 - [Usage](#usage)
+- [Dual Module Support](#dual-module-support)
 - [Examples](#examples)
   - [Simple key-value pairs](#simple-key-value-pairs)
   - [Unix-style command-line options](#unix-style-command-line-options)
@@ -61,34 +62,49 @@ console.log(args.name); // "John"
 
 ```
 
+## Dual Module Support
+
+This package supports both:
+
+- ES Modules: `import argv2object from 'argv2object'`
+- CommonJS: `const argv2object = require('argv2object')`
+
+The architecture uses separate entry points while sharing the same implementation.
+
+## System Requirements
+
+- **Node.js 14+** (Recommended for full support)
+- **Node.js 12.x** (Experimental support)
+- **Versiones anteriores**: Use version 1.x of this package
+
 ## Examples
 
 ### Simple key-value pairs
 
 ```sh
 # Command line input:
-node script.js task=some-task name=John level=admin
+node script.js task=some-task age=30 name=John level=admin
 
 ```
 
 ```js
 const args = argv2Object();
 console.log(args);
-// Output: { name: 'John', age: '30', level: 'admin' }
+// Output: { name: 'John', age: 30, level: 'admin' }
 ```
 
 ### Unix-style command-line options
 
 ```sh
 # Command line input:
-node --watch script.js -h --name=John --is-admin
+node --watch script.js -h --help --name=John --is-admin
 
 ```
 
 ```js
 const args = argv2Object(true);
 console.log(args);
-// Output: { h: true, name: 'John', is_admin: true }
+// Output: { h: true, help: true, name: 'John', is_admin: true }
 ```
 
 ## API
@@ -113,11 +129,12 @@ Returns an `Object` with keys and values corresponding to the provided arguments
 
 Throws
 
-| Type    | Description                                                                                 |
-|---------|---------------------------------------------------------------------------------------------|
-| `Error` | If no arguments are provided from command line.                                             |
-| `Error` | If `unixmode` is `true` and an argument does not follow the Unix-style command-line format. |
-| `Error` | If `unixmode` is `false` and an argument does not follow the "key=value" format.            |
+| Type    | Description                                                                                     |
+|---------|-------------------------------------------------------------------------------------------------|
+| `TypeError` | If `unixmode` is not of type `boolean`.                                                     |
+| `Error`     | If no arguments are provided from command line.                                             |
+| `Error`     | If `unixmode` is `true` and an argument does not follow the Unix-style command-line format. |
+| `Error`     | If `unixmode` is `false` and an argument does not follow the "key=value" format.            |
 
 ## Contributing
 

package/index.cjs

@@ -1,22 +1,22 @@
 /**
- * @author Victor Giovanni Beltrán Rodríguez
- * @file Manages main entry point.
- */
-
-// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-/**
- * The `argv2Object()` function, converts command-line arguments to a key-value
- * object.
+ * @file Entry point for CommonJS consumers.
  *
- * This function takes an array of command-line arguments and converts them to a
- * JavaScript object with keys and values based on the provided argument format.
- * The format can be either simple key-value pairs (e.g. "key=value") or
- * Unix-style command-line options (e.g. "-o --option=value").
+ * Provides compatibility layer for Node.js environments
+ * using CommonJS require() system.
  *
- * @version 1.0.0
- * @author Victor Giovanni Beltrán Rodríguez
- * @module argv2Object
+ * This wrapper adapts the ESM default export to CommonJS
+ * module.exports pattern.
+ *
+ * @module argv2object/cjs
+ * @see module:argv2Object
+ * @since 1.1.0
+ * @example
+ * // CJS Usage
+ * const argv2object = require('argv2object');
  */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
 const argv2Object = require('#argv2Object');
 
 // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/index.mjs

@@ -1,22 +1,22 @@
 /**
- * @author Victor Giovanni Beltrán Rodríguez
- * @file Manages main entry point.
- */
-
-// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-/**
- * The `argv2Object()` function, converts command-line arguments to a key-value
- * object.
+ * @file Entry point for ES Module consumers.
  *
- * This function takes an array of command-line arguments and converts them to a
- * JavaScript object with keys and values based on the provided argument format.
- * The format can be either simple key-value pairs (e.g. "key=value") or
- * Unix-style command-line options (e.g. "-o --option=value").
+ * Provides the default export of argv2object functionality
+ * for modern JavaScript environments using ES Modules.
  *
- * @version 1.0.0
- * @author Victor Giovanni Beltrán Rodríguez
- * @module argv2Object
+ * This file re-exports the main functionality from the
+ * implementation module while maintaining ESM compatibility.
+ *
+ * @module argv2object/esm
+ * @see module:argv2Object
+ * @since 1.1.0
+ * @example
+ * // ESM Usage
+ * import argv2object from 'argv2object';
  */
+
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
 import argv2Object from '#argv2Object';
 
 // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argv2object",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "private": false,
   "description": "A utility function for converting command-line arguments to a key-value object.",
   "keywords": [
@@ -49,24 +49,29 @@
   "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": ">=12.0.0"
+    "node": ">=14.0.0"
   }
 }

package/src/argv2Object.mjs

@@ -10,8 +10,7 @@
  * arguments: simple key-value pairs (e.g. "key=value") and Unix-style
  * command-line arguments (e.g. "-k value" or "--key=value").
  *
- * @author Victor Giovanni Beltrán Rodríguez
- * @version 1.0.0
+ * @version 1.1.0
  *
  * @example
  *  Simple key-value pairs
@@ -25,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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 /**
@@ -47,8 +46,9 @@ 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.
  * @throws {Error} If `unixmode` is `true` and argument does not follow Unix-style command-line format.
  * @throws {Error} If `unixmode` is `false` and argument does not follow 'key=value' format.
@@ -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

@@ -1,7 +1,12 @@
 /**
- * @file TODO ADD SHORT MODULE DESCRIPTION.
+ * @file Module containing utility functions for argument processing.
+ *
+ * Provides formatting and type conversion functions used internally
+ * by the argv2object library to normalize and transform command-line
+ * arguments into consistent JavaScript data structures.
  *
  * @module Functions
+ * @since 1.0.0
  */
 
 // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -12,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') {
@@ -50,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;
@@ -74,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.
@@ -82,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 };