argv2object 1.0.1 → 1.1.0

package/index.cjs

@@ -0,0 +1,23 @@
+/**
+ * @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.
+ *
+ * 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").
+ *
+ * @version 1.0.0
+ * @author Victor Giovanni Beltrán Rodríguez
+ * @module argv2Object
+ */
+const argv2Object = require('#argv2Object');
+
+// ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+module.exports = argv2Object.default;

package/package.json

@@ -1,70 +1,72 @@
-{
-  "name": "argv2object",
-  "version": "1.0.1",
-  "private": false,
-  "description": "A utility function for converting command-line arguments to a key-value object.",
-  "keywords": [
-    "arguments",
-    "command-line",
-    "conversion",
-    "key-value",
-    "nodejs",
-    "object",
-    "parse",
-    "process.argv",
-    "unix-style"
-  ],
-  "homepage": "https://github.com/vgbr-dev/argv2object#readme",
-  "bugs": {
-    "url": "https://github.com/vgbr-dev/argv2object/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vgbr-dev/argv2object.git"
-  },
-  "author": {
-    "name": "Victor Giovanni Beltrán Rodríguez",
-    "email": "vgbr.dev@gmail.com",
-    "url": "https://vgbr-dev.blogspot.com"
-  },
-  "contributors": [
-    {
-      "name": "Victor Giovanni Beltrán Rodriguez",
-      "email": "vgbr.dev@gmail.com",
-      "url": "https://vgbr-dev.blogspot.com"
-    }
-  ],
-  "license": "MIT",
-  "type": "module",
-  "main": "index.js",
-  "imports": {
-    "#argv2Object": "./src/argv2Object.mjs",
-    "#constants": "./src/constants.mjs",
-    "#functions": "./src/functions.mjs"
-  },
-  "scripts": {
-    "test": "cross-env NODE_ENV=test node --watch --test test/*.test.mjs",
-    "lint": "npx eslint",
-    "prepare": "husky install",
-    "prepublish": "npm test"
-  },
-  "devDependencies": {
-    "@commitlint/cli": "^17.6.1",
-    "@commitlint/config-conventional": "^17.6.1",
-    "cross-env": "^7.0.3",
-    "eslint": "^8.42.0",
-    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-config-prettier": "^8.8.0",
-    "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"
-  },
-  "engines": {
-    "node": ">=12.0.0"
-  }
-}
+{
+  "name": "argv2object",
+  "version": "1.1.0",
+  "private": false,
+  "description": "A utility function for converting command-line arguments to a key-value object.",
+  "keywords": [
+    "arguments",
+    "command-line",
+    "conversion",
+    "key-value",
+    "nodejs",
+    "object",
+    "parse",
+    "process.argv",
+    "unix-style"
+  ],
+  "homepage": "https://github.com/vgbr-dev/argv2object#readme",
+  "bugs": {
+    "url": "https://github.com/vgbr-dev/argv2object/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vgbr-dev/argv2object.git"
+  },
+  "author": {
+    "name": "Victor Giovanni Beltrán Rodríguez",
+    "email": "vgbr.dev@gmail.com",
+    "url": "https://vgbr-dev.blogspot.com"
+  },
+  "contributors": [
+    {
+      "name": "Victor Giovanni Beltrán Rodriguez",
+      "email": "vgbr.dev@gmail.com",
+      "url": "https://vgbr-dev.blogspot.com"
+    }
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    "import": "./index.mjs",
+    "require": "./index.cjs"
+  },
+  "imports": {
+    "#argv2Object": "./src/argv2Object.mjs",
+    "#constants": "./src/constants.mjs",
+    "#functions": "./src/functions.mjs"
+  },
+  "scripts": {
+    "test": "cross-env NODE_ENV=test node --test test/*.test.mjs",
+    "lint": "npx eslint . --ext .mjs --ext .js --ext .cjs",
+    "prepare": "husky install",
+    "prepublish": "npm test"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.57.1",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-prettier": "^8.10.0",
+    "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"
+  },
+  "engines": {
+    "node": ">=12.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").
+ *
+ * @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 }
+ */
+// ━━ 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 {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,85 @@
+/**
+ * @file TODO ADD SHORT MODULE DESCRIPTION.
+ *
+ * @module Functions
+ */
+
+// ━━ 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 };