argv2object 1.0.2 → 1.1.1

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

@@ -0,0 +1,23 @@
+/**
+ * @file Entry point for CommonJS consumers.
+ *
+ * Provides compatibility layer for Node.js environments
+ * using CommonJS require() system.
+ *
+ * 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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+module.exports = argv2Object.default;

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.0.2",
+  "version": "1.1.1",
   "private": false,
   "description": "A utility function for converting command-line arguments to a key-value object.",
   "keywords": [
@@ -38,7 +38,8 @@
   "type": "module",
   "main": "index.mjs",
   "exports": {
-    ".": "./index.mjs"
+    "import": "./index.mjs",
+    "require": "./index.cjs"
   },
   "imports": {
     "#argv2Object": "./src/argv2Object.mjs",
@@ -47,7 +48,7 @@
   },
   "scripts": {
     "test": "cross-env NODE_ENV=test node --test test/*.test.mjs",
-    "lint": "npx eslint",
+    "lint": "npx eslint . --ext .mjs --ext .js --ext .cjs",
     "prepare": "husky install",
     "prepublish": "npm test"
   },
@@ -55,19 +56,17 @@
     "@commitlint/cli": "^19.8.0",
     "@commitlint/config-conventional": "^19.8.0",
     "cross-env": "^7.0.3",
-    "eslint": "^8.42.0",
+    "eslint": "^8.57.1",
     "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-config-prettier": "^8.8.0",
+    "eslint-config-prettier": "^8.10.0",
+    "eslint-import-resolver-node": "^0.3.9",
     "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jsdoc": "^46.2.6",
     "eslint-plugin-prettier": "^4.2.1",
     "husky": "^8.0.3",
-    "jsdoc": "^4.0.2",
-    "jsdoc-to-markdown": "^8.0.0",
-    "lint-staged": "^13.2.1",
-    "prettier": "^2.8.7"
+    "lint-staged": "^15.5.2",
+    "prettier": "^2.8.8"
   },
   "engines": {
-    "node": ">=12.0.0"
+    "node": ">=14.0.0"
   }
 }

package/src/argv2Object.mjs

@@ -1,134 +1,94 @@
-/**
- * @file Converts command-line arguments to a key-value object.
- *
- * A utility function for converting command-line arguments to a key-value
- * object.
- *
- * This file defines a single function, `argv2Object`, which parses
- * command-line arguments and returns an object with keys and values
- * corresponding to the provided arguments. The function can handle two types of
- * 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
- *
- * @example
- *  Simple key-value pairs
- *  Command line input: node script.js name=John age=30 level=admin
- *  Output: { name: 'John', age: '30', level: "admin" }
- *
- * @example
- * Unix-style command-line options
- * Command line input: node script.js -h --name=John --is-admin
- * Output: { h: true, name: 'John', is_admin: true }
- */
-
-// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-/**
- * Regular expressions used to validate command-line arguments.
- *
- * @private
- * @typedef  {object} Regexps
- * @property {RegExp} UNIXMODE - Regular expression for validating Unix-style command-line arguments.
- * @property {RegExp} SIMPLE   - Regular expression for validating simple key-value arguments.
- */
-
-/**
- * Error messages used in case of invalid command-line arguments.
- *
- * @private
- * @typedef  {object} Errors
- * @property {string} NO_ARGS           - Error message for when no arguments are provided.
- * @property {string} NO_MATCH_SIMPLE   - Error message for when one or more simple key-value arguments do not follow the expected format.
- * @property {string} NO_MATCH_UNIXMODE - Error message for when one or more Unix-style command-line arguments do not follow the expected format.
- */
-
-/**
- * An `Object` with keys and values corresponding to the provided arguments.
- *
- * @typedef  {object}         ArgvObject
- * @property {string|boolean} [key=value] - The key-value pairs in the provided arguments.
- */
-
-// ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-/**
- * Regular expressions used to validate command-line arguments.
- *
- * @private
- * @type {Regexps}
- */
-const REGEXPS = {
-  UNIXMODE: /^-[a-z]{1}|-[a-z]{1}=.*$|--[a-zA-Z]+|--[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
-  SIMPLE: /^[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
-};
-
-/**
- * Error messages used in case of invalid command-line arguments.
- *
- * @private
- * @type {Errors}
- */
-const THROWS_ERRORS_MESSAGES = {
-  INVALID_UNIXMODE_TYPE: 'The "unixmode" value must be a boolean type',
-  NO_ARGUMENTS: 'No arguments added',
-  NO_MATCH_SIMPLE: `Some argument(s) do not follow the 'key=value' format.`,
-  NO_MATCH_UNIXMODE: `Some argument(s) do not follow the Unix-style command-line format.`,
-};
-
-// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-/**
- * The `argv2Object()` function, converts command-line arguments to a key-value
- * object.
- *
- * 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").
- *
- * @function
- * @param {boolean} [unixmode=false] - 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 {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.
- * @example
- * ```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 argv2Object = (unixmode = false) => {
-  if (typeof unixmode !== 'boolean') {
-    throw new TypeError(THROWS_ERRORS_MESSAGES.INVALID_UNIXMODE_TYPE);
-  }
-
-  const argumentsv = process.argv.slice(2);
-  if (argumentsv.length === 0) {
-    throw new Error(THROWS_ERRORS_MESSAGES.NO_ARGUMENTS);
-  }
-
-  const regexp = unixmode ? REGEXPS.UNIXMODE : REGEXPS.SIMPLE;
-
-  if (!argumentsv.every(argumentv => regexp.test(argumentv))) {
-    const message = unixmode
-      ? THROWS_ERRORS_MESSAGES.NO_MATCH_UNIXMODE
-      : THROWS_ERRORS_MESSAGES.NO_MATCH_SIMPLE;
-    throw new Error(message);
-  }
-
-  const entries = [...argumentsv].map(argumentv => {
-    const [k, v] = argumentv.split('=');
-    const key = k.replace(/^-{1,2}/, '').replace(/-/g, '_');
-    const value = v === undefined ? true : v;
-    return [key, value];
-  });
-
-  return Object.fromEntries(entries);
-};
-
-// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-export default argv2Object;
+/**
+ * @file Converts command-line arguments to a key-value object.
+ *
+ * A utility function for converting command-line arguments to a key-value
+ * object.
+ *
+ * This file defines a single function, `argv2Object`, which parses
+ * command-line arguments and returns an object with keys and values
+ * corresponding to the provided arguments. The function can handle two types of
+ * arguments: simple key-value pairs (e.g. "key=value") and Unix-style
+ * command-line arguments (e.g. "-k value" or "--key=value").
+ *
+ * @version 1.1.0
+ *
+ * @example
+ *  Simple key-value pairs
+ *  Command line input: node script.js name=John age=30 level=admin
+ *  Output: { name: 'John', age: '30', level: "admin" }
+ *
+ * @example
+ * Unix-style command-line options
+ * Command line input: node script.js -h --name=John --is-admin
+ * Output: { h: true, name: 'John', is_admin: true }
+ */
+// ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// » IMPORT LOCAL MODULES
+import { REGEXPS, THROWS_ERRORS_MESSAGES } from '#constants';
+import { formatKey, convertValue } from '#functions';
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * An `Object` with keys and values corresponding to the provided arguments.
+ *
+ * @typedef  {object}         ArgvObject
+ * @property {string|boolean} [key=value] - The key-value pairs in the provided arguments.
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * The `argv2Object()` function, converts command-line arguments to a key-value
+ * object.
+ *
+ * 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").
+ *
+ * @function
+ * @param {boolean} [unixmode=false] - 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.
+ * @example
+ * ```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 argv2Object = (unixmode = false) => {
+  if (typeof unixmode !== 'boolean') {
+    throw new TypeError(THROWS_ERRORS_MESSAGES.INVALID_UNIXMODE_TYPE);
+  }
+
+  const argumentsv = process.argv.slice(2);
+  if (argumentsv.length === 0) {
+    throw new Error(THROWS_ERRORS_MESSAGES.NO_ARGUMENTS);
+  }
+
+  const regexp = unixmode ? REGEXPS.UNIXMODE : REGEXPS.SIMPLE;
+
+  if (!argumentsv.every(argumentv => regexp.test(argumentv))) {
+    const message = unixmode
+      ? THROWS_ERRORS_MESSAGES.NO_MATCH_UNIXMODE
+      : THROWS_ERRORS_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);
+};
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export default argv2Object;

package/src/constants.mjs

@@ -0,0 +1,82 @@
+/**
+ * @file Module containing constants for argument validation.
+ *
+ * This module exports regular expressions for argument pattern matching
+ * and standardized error messages used throughout the argv2object library.
+ * These constants ensure consistent validation and error reporting when
+ * parsing command-line arguments.
+ *
+ * @module constants
+ * @since 1.0.0
+ */
+
+// ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Regular expression patterns for argument validation.
+ *
+ * @typedef  {object} Regexps
+ * @property {RegExp} UNIXMODE - Pattern for Unix-style arguments (-a, --arg=value).
+ * @property {RegExp} SIMPLE   - Pattern for simple key=value arguments.
+ */
+
+/**
+ * Standardized error messages for argument validation failures.
+ *
+ * @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
+ */
+
+// ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Regular expressions for validating different argument formats.
+ *
+ * @exports
+ * @private
+ * @constant REGEXPS
+ * @type {Regexps}
+ * @example
+ * // Unix-style pattern matches:
+ * // -a, -b=value, --flag, --option=value
+ * REGEXPS.UNIXMODE.test('--output=json') // true
+ *
+ * @example
+ * // Simple pattern matches:
+ * // key=value, multi-part-key=value
+ * REGEXPS.SIMPLE.test('output_format=json') // true
+ */
+const REGEXPS = {
+  UNIXMODE: /^-[a-z]{1}|-[a-z]{1}=.*$|--[a-zA-Z]+|--[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
+  SIMPLE: /^[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
+};
+
+/**
+ * Standardized error messages for consistent validation feedback.
+ *
+ * @exports
+ * @private
+ * @constant THROWS_ERRORS_MESSAGES
+ * @type {ErrorMessages}
+ * @example
+ * // Error cases:
+ * throw new Error(THROWS_ERRORS_MESSAGES.INVALID_UNIXMODE_TYPE);
+ * throw new Error(THROWS_ERRORS_MESSAGES.NO_ARGUMENTS);
+ */
+const THROWS_ERRORS_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',
+  NO_MATCH_UNIXMODE: 'Arguments must follow Unix-style format (-a, --option=value)',
+};
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Exported constants for argument validation.
+ *
+ * @type {object}
+ * @property {Regexps}       REGEXPS                - Validation patterns.
+ * @property {ErrorMessages} THROWS_ERRORS_MESSAGES - Standard error messages.
+ */
+export { REGEXPS, THROWS_ERRORS_MESSAGES };

package/src/functions.mjs

@@ -0,0 +1,90 @@
+/**
+ * @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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Normalizes and formats argument keys according to specified casing convention.
+ *
+ * Removes leading dashes from command-line flags and applies optional case conversion.
+ *
+ * Supports:
+ *
+ * - 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
+ * @example
+ * 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') {
+    throw new TypeError('Key must be a string');
+  }
+  const sanitizedKey = key.replace(/^-{1,2}/, '');
+
+  if (mode === 'camelcase') {
+    return sanitizedKey.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+  }
+
+  if (mode === 'snakecase') {
+    return sanitizedKey.replace(/-/g, '_');
+  }
+
+  return sanitizedKey;
+};
+
+/**
+ * Converts string values from command-line arguments to proper JavaScript types.
+ *
+ * Performs automatic conversion of:
+ *
+ * - '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
+ * @example
+ * 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;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (!Number.isNaN(value) && !Number.isNaN(parseFloat(value))) return Number(value);
+  return value;
+};
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+/**
+ * Utility functions for argument processing.
+ *
+ * @namespace
+ * @property {Function} formatKey    - Key formatting/normalization function.
+ * @property {Function} convertValue - Value type conversion function.
+ */
+export { formatKey, convertValue };