argv2object 1.1.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +169 -64
  2. package/index.cjs +15 -9
  3. package/index.mjs +9 -7
  4. package/package.json +32 -23
  5. package/source/argv2Object.mjs +85 -0
  6. package/source/constants.mjs +56 -0
  7. package/source/functions.mjs +126 -0
  8. package/types/index.d.cts +22 -0
  9. package/types/index.d.mts +22 -0
  10. package/src/argv2Object.mjs +0 -89
  11. package/src/constants.mjs +0 -115
  12. package/src/functions.mjs +0 -124
package/README.md CHANGED
@@ -1,25 +1,27 @@
1
1
  # argv2Object
2
2
 
3
- A utility function for converting command-line arguments to a key-value object.
3
+ A lightweight utility for converting command-line arguments into a JavaScript key-value object.
4
4
 
5
5
  ## Table of Contents
6
6
 
7
7
  - [Installation](#installation)
8
8
  - [Importing](#importing)
9
9
  - [Usage](#usage)
10
- - [Dual Module Support](#dual-module-support)
11
- - [Examples](#examples)
10
+ - [Supported Argument Formats](#supported-argument-formats)
12
11
  - [Simple key-value pairs](#simple-key-value-pairs)
13
12
  - [Unix-style command-line options](#unix-style-command-line-options)
13
+ - [Value Conversion](#value-conversion)
14
+ - [Key Formatting](#key-formatting)
14
15
  - [API](#api)
15
16
  - [Type Definitions](#type-definitions)
16
- - [`argv2Object()`](#argv2object-1)
17
+ - [`argv2Object()`](#argv2object)
18
+ - [Error Handling](#error-handling)
17
19
  - [Contributing](#contributing)
18
20
  - [License](#license)
19
21
 
20
22
  ## Installation
21
23
 
22
- You can install argv2Object via [npm](https://www.npmjs.com/package/argv2Object):
24
+ Install `argv2object` using npm:
23
25
 
24
26
  ```sh
25
27
  npm install argv2object
@@ -27,119 +29,222 @@ npm install argv2object
27
29
 
28
30
  ## Importing
29
31
 
30
- To use argv2Object in your JavaScript application, first import it:
32
+ Import the default export into your application:
31
33
 
32
34
  ```js
33
- // Using ES6 imports
34
35
  import argv2Object from 'argv2object';
35
-
36
- // Using Node.js `require()`
37
- const argv2Object = require('argv2object');
38
36
  ```
39
37
 
38
+ > CommonJS support depends on the package entry points and exports configuration.
39
+
40
40
  ## Usage
41
41
 
42
- Converts command-line arguments to a key-value object.
42
+ `argv2Object` reads command-line arguments from `process.argv`, starting after the Node.js executable and script path.
43
+
44
+ It supports two parsing modes:
45
+
46
+ - **Simple mode:** Parses `key=value` arguments.
47
+ - **Unix mode:** Parses Unix-style flags and long options.
48
+
49
+ ## Supported Argument Formats
50
+
51
+ ### Simple key-value pairs
52
+
53
+ Run your application with key-value arguments:
43
54
 
44
55
  ```sh
45
- # Command line input:
46
- node script.js --task=some-task --execute -h --name=John
56
+ node script.js name=John age=30 level=admin api2=production
57
+ ```
58
+
59
+ Parse the arguments:
60
+
61
+ ```js
62
+ import argv2Object from 'argv2object';
63
+
64
+ const args = argv2Object();
47
65
 
66
+ console.log(args);
67
+ // {
68
+ // name: 'John',
69
+ // age: 30,
70
+ // level: 'admin',
71
+ // api2: 'production'
72
+ // }
48
73
  ```
49
74
 
75
+ In simple mode, every argument must contain an `=`. Bare keys such as `name` are rejected.
76
+
77
+ Keys must start with a letter and may contain letters, digits, and hyphen-separated segments.
78
+
79
+ ### Unix-style command-line options
80
+
81
+ Enable Unix mode by passing `true`:
82
+
83
+ ```sh
84
+ node script.js -h --help --name=John --age=30 --is-admin
85
+ ```
86
+
87
+ Parse the arguments:
88
+
50
89
  ```js
51
- const argv2Object = require('argv2object');
90
+ import argv2Object from 'argv2object';
52
91
 
53
- // UNIX command line mode true
54
92
  const args = argv2Object(true);
55
- console.log(args.task); // "some-task"
56
93
 
57
- console.log(args.execute); // true
94
+ console.log(args);
95
+ // {
96
+ // h: true,
97
+ // help: true,
98
+ // name: 'John',
99
+ // age: 30,
100
+ // is_admin: true
101
+ // }
102
+ ```
58
103
 
59
- console.log(args.h); // true
104
+ Unix mode supports:
60
105
 
61
- console.log(args.name); // "John"
106
+ | Format | Description | Example |
107
+ | ---------------- | ------------------------- | ------------- |
108
+ | `-x` | Short flag | `-h` |
109
+ | `-x=value` | Short option with a value | `-p=3000` |
110
+ | `--option` | Long flag | `--help` |
111
+ | `--option=value` | Long option with a value | `--port=3000` |
62
112
 
63
- ```
113
+ Long option keys must start with a letter and may contain letters, digits, and hyphens.
64
114
 
65
- ## Dual Module Support
115
+ Short options consist of exactly one letter.
66
116
 
67
- This package supports both:
117
+ **Important:** Arguments must use the equals sign to provide values. Separate key-value arguments such as `--port 3000` are not supported.
68
118
 
69
- - ES Modules: `import argv2object from 'argv2object'`
70
- - CommonJS: `const argv2object = require('argv2object')`
119
+ Argument values are converted using the same rules as simple mode. For example, `--age=30` produces the number `30`, and `--active=true` produces the boolean `true`.
71
120
 
72
- The architecture uses separate entry points while sharing the same implementation.
121
+ **Grammar differences between modes:**
73
122
 
74
- ## System Requirements
123
+ - Simple mode keys cannot contain consecutive hyphens (`key--value`) or a trailing hyphen (`key-=value`).
124
+ - Unix long option keys allow consecutive hyphens (`--key--value`) and a trailing hyphen (`--key-`), matching common Unix CLI conventions.
75
125
 
76
- - **Node.js 14+** (Recommended for full support)
77
- - **Node.js 12.x** (Experimental support)
78
- - **Versiones anteriores**: Use version 1.x of this package
126
+ ## Value Conversion
79
127
 
80
- ## Examples
128
+ Argument values are automatically converted when they match supported formats.
81
129
 
82
- ### Simple key-value pairs
130
+ | Input | Result | JavaScript type |
131
+ | --------------- | -------- | --------------- |
132
+ | `name=John` | `'John'` | `string` |
133
+ | `age=30` | `30` | `number` |
134
+ | `price=3.14` | `3.14` | `number` |
135
+ | `active=true` | `true` | `boolean` |
136
+ | `enabled=false` | `false` | `boolean` |
137
+ | `empty=` | `''` | `string` |
138
+ | `--verbose` | `true` | `boolean` |
83
139
 
84
- ```sh
85
- # Command line input:
86
- node script.js task=some-task age=30 name=John level=admin
140
+ Numeric conversion supports signed decimal numbers, fractional values, and scientific notation.
141
+
142
+ Examples:
87
143
 
144
+ ```text
145
+ count=42
146
+ temperature=-3.5
147
+ ratio=.75
148
+ price=5.
149
+ distance=1e3
88
150
  ```
89
151
 
90
- ```js
91
- const args = argv2Object();
92
- console.log(args);
93
- // Output: { name: 'John', age: 30, level: 'admin' }
152
+ Values that do not match the supported numeric format remain strings.
153
+
154
+ For example:
155
+
156
+ ```text
157
+ hex=0xFF
158
+ infinity=Infinity
159
+ version=1.2.3
94
160
  ```
95
161
 
96
- ### Unix-style command-line options
162
+ Values may contain additional equals signs. Only the first equals sign separates the key from its value.
97
163
 
98
164
  ```sh
99
- # Command line input:
100
- node --watch script.js -h --help --name=John --is-admin
165
+ node script.js url=https://example.com?name=John&active=true
166
+ ```
167
+
168
+ A key without an explicit value in Unix mode is interpreted as a boolean flag with the value `true`.
169
+
170
+ ## Key Formatting
171
+
172
+ Parsed keys are normalized to `snake_case`.
173
+
174
+ For example:
175
+
176
+ | Original key | Result |
177
+ | ------------- | ----------- |
178
+ | `--is-admin` | `is_admin` |
179
+ | `--user-name` | `user_name` |
180
+ | `--api2-key` | `api2_key` |
181
+ | `-h` | `h` |
182
+
183
+ When multiple arguments produce the same key, the last value takes precedence.
101
184
 
185
+ ## API
186
+
187
+ ### Type Definitions
188
+
189
+ The library uses the following JSDoc types:
190
+
191
+ ```js
192
+ /**
193
+ * Supported values produced by command-line argument parsing.
194
+ * @typedef {string|number|boolean} ArgumentValue
195
+ */
196
+
197
+ /**
198
+ * Object containing parsed command-line arguments.
199
+ * @typedef {Record<string, ArgumentValue>} ArgvObject
200
+ */
102
201
  ```
103
202
 
203
+ > `CaseMode` is an internal type used by `formatKey` and is not part of the public API.
204
+
205
+ ### `argv2Object(unixmode = false)`
206
+
104
207
  ```js
105
- const args = argv2Object(true);
106
- console.log(args);
107
- // Output: { h: true, help: true, name: 'John', is_admin: true }
208
+ argv2Object(unixmode = false): ArgvObject
108
209
  ```
109
210
 
110
- ## API
211
+ Reads command-line arguments from `process.argv` and converts them into an object.
111
212
 
112
- ### Type Definitions
213
+ **Arguments:**
113
214
 
114
- - `ArgvObject`: An `Object` with keys and values corresponding to the provided arguments.
215
+ | Name | Type | Default | Description |
216
+ | ---------- | --------- | ------- | ------------------------------------------------------- |
217
+ | `unixmode` | `boolean` | `false` | Enables Unix-style argument parsing when set to `true`. |
115
218
 
116
- ### `argv2Object()`
219
+ **Returns:**
117
220
 
118
- The `argv2Object(unixmode = false): => ArgvObject` function takes the 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").
221
+ Returns an `ArgvObject` containing the parsed command-line arguments.
119
222
 
120
- Arguments
223
+ **Examples:**
121
224
 
122
- | Name | Type | Default | Description |
123
- |------------|-----------|---------|---------------------------------------------------|
124
- | `unixmode` | `boolean` | `false` | Whether to parse Unix-style command-line options. |
225
+ ```js
226
+ const simpleArguments = argv2Object();
227
+ const unixArguments = argv2Object(true);
228
+ ```
125
229
 
126
- Returns
230
+ ## Error Handling
127
231
 
128
- Returns an `Object` with keys and values corresponding to the provided arguments.
232
+ The function throws errors when its input or command-line arguments do not satisfy the expected format.
129
233
 
130
- Throws
234
+ | Error type | Condition |
235
+ | ----------- | --------------------------------------------------------------- |
236
+ | `TypeError` | `unixmode` is not a boolean. |
237
+ | `Error` | No command-line arguments were provided. |
238
+ | `Error` | At least one argument does not match the selected parsing mode. |
131
239
 
132
- | Type | Description |
133
- |---------|-------------------------------------------------------------------------------------------------|
134
- | `TypeError` | If `unixmode` is not of type `boolean`. |
135
- | `Error` | If no arguments are provided from command line. |
136
- | `Error` | If `unixmode` is `true` and an argument does not follow the Unix-style command-line format. |
137
- | `Error` | If `unixmode` is `false` and an argument does not follow the "key=value" format. |
240
+ All arguments must match the selected mode. If any argument is invalid, parsing is rejected.
138
241
 
139
242
  ## Contributing
140
243
 
141
- Contributions, issues and feature requests are welcome. Feel free to check [issues page](https://github.com/vgbr-dev/argv2object/issues) if you want to contribute.
244
+ Contributions, issues, and feature requests are welcome.
245
+
246
+ Visit the [issues page](https://github.com/vgbr-dev/argv2object/issues) to report problems or suggest improvements.
142
247
 
143
248
  ## License
144
249
 
145
- Distributed under the MIT License. See LICENSE for more information.
250
+ Distributed under the MIT License. See the [LICENSE](LICENSE) file for more information.
package/index.cjs CHANGED
@@ -1,5 +1,6 @@
1
+ /* eslint-disable import/no-commonjs */
1
2
  /**
2
- * @file Entry point for CommonJS consumers.
3
+ * @file Entry point for `CommonJS` consumers.
3
4
  *
4
5
  * Provides compatibility layer for Node.js environments
5
6
  * using CommonJS require() system.
@@ -7,17 +8,22 @@
7
8
  * This wrapper adapts the ESM default export to CommonJS
8
9
  * module.exports pattern.
9
10
  *
10
- * @module argv2object/cjs
11
- * @see module:argv2Object
12
- * @since 1.1.0
13
- * @example
14
- * // CJS Usage
15
- * const argv2object = require('argv2object');
11
+ * @module argv2Object/cjs
12
+ * @see {@link argv2Object}
13
+ * @since 1.0.0
14
+ */
15
+
16
+ // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
17
+ /**
18
+ * @typedef {import('#argv2Object').default} argv2Object
16
19
  */
17
20
 
18
21
  // ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
19
22
  // » IMPORT LOCAL MODULES
20
- const argv2Object = require('#argv2Object');
23
+ /**
24
+ * @type {argv2Object}
25
+ */
26
+ const argv2Object = require('#argv2Object').default;
21
27
 
22
28
  // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
23
- module.exports = argv2Object.default;
29
+ module.exports = argv2Object;
package/index.mjs CHANGED
@@ -1,18 +1,20 @@
1
1
  /**
2
- * @file Entry point for ES Module consumers.
2
+ * @file Entry point for `ES Module` consumers.
3
3
  *
4
- * Provides the default export of argv2object functionality
4
+ * Provides the default export of `argv2Object` functionality
5
5
  * for modern JavaScript environments using ES Modules.
6
6
  *
7
7
  * This file re-exports the main functionality from the
8
8
  * implementation module while maintaining ESM compatibility.
9
9
  *
10
- * @module argv2object/esm
11
- * @see module:argv2Object
10
+ * @module argv2Object/esm
11
+ * @see {@link argv2Object}
12
12
  * @since 1.1.0
13
- * @example
14
- * // ESM Usage
15
- * import argv2object from 'argv2object';
13
+ */
14
+
15
+ // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
16
+ /**
17
+ * @typedef {import('#argv2Object').default} argv2Object
16
18
  */
17
19
 
18
20
  // ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "argv2object",
3
- "version": "1.1.2",
3
+ "version": "1.2.0",
4
4
  "private": false,
5
5
  "description": "A utility function for converting command-line arguments to a key-value object.",
6
6
  "keywords": [
@@ -37,41 +37,50 @@
37
37
  "license": "MIT",
38
38
  "type": "module",
39
39
  "main": "index.mjs",
40
+ "types": "./types/index.d.mts",
40
41
  "exports": {
41
- "import": "./index.mjs",
42
- "require": "./index.cjs"
42
+ ".": {
43
+ "import": {
44
+ "types": "./types/index.d.mts",
45
+ "default": "./index.mjs"
46
+ },
47
+ "require": {
48
+ "types": "./types/index.d.cts",
49
+ "default": "./index.cjs"
50
+ }
51
+ }
43
52
  },
44
53
  "imports": {
45
- "#argv2Object": "./src/argv2Object.mjs",
46
- "#constants": "./src/constants.mjs",
47
- "#functions": "./src/functions.mjs"
54
+ "#argv2Object": "./source/argv2Object.mjs",
55
+ "#constants": "./source/constants.mjs",
56
+ "#functions": "./source/functions.mjs"
48
57
  },
49
58
  "scripts": {
50
59
  "test": "cross-env NODE_ENV=test node --test test/*.test.mjs",
51
- "lint": "npx eslint . --ext .mjs --ext .js --ext .cjs",
60
+ "lint": "npx eslint .",
52
61
  "prepare": "husky",
53
- "prepublish": "npm test"
62
+ "prepublishOnly": "npm test"
54
63
  },
55
64
  "devDependencies": {
56
- "@commitlint/cli": "^20.1.0",
57
- "@commitlint/config-conventional": "^20.0.0",
58
- "@eslint/compat": "^1.4.1",
59
- "@eslint/core": "^0.17.0",
60
- "@eslint/eslintrc": "^3.3.3",
65
+ "@commitlint/cli": "^21.2.4",
66
+ "@commitlint/config-conventional": "^21.2.4",
67
+ "@eslint/compat": "^2.1.1",
68
+ "@eslint/eslintrc": "^3.3.7",
69
+ "@eslint/js": "^10.0.1",
70
+ "@types/node": "^26.6.6",
61
71
  "cross-env": "^10.1.0",
62
- "eslint": "^9.39.1",
63
- "eslint-config-airbnb-base": "^15.0.0",
72
+ "eslint": "^10.14.0",
64
73
  "eslint-config-prettier": "^10.1.8",
65
- "eslint-import-resolver-alias": "^1.1.2",
66
- "eslint-import-resolver-node": "^0.3.9",
67
- "eslint-plugin-import": "^2.32.0",
68
- "eslint-plugin-jsdoc": "^61.4.1",
69
- "eslint-plugin-prettier": "^5.5.4",
74
+ "eslint-import-resolver-node": "^0.4.0",
75
+ "eslint-plugin-import-x": "^4.17.1",
76
+ "eslint-plugin-jsdoc": "^63.3.3",
77
+ "eslint-plugin-prettier": "^5.5.7",
78
+ "globals": "^17.14.0",
70
79
  "husky": "^9.1.7",
71
- "lint-staged": "^16.2.7",
72
- "prettier": "^3.7.3"
80
+ "lint-staged": "^17.6.0",
81
+ "prettier": "^3.9.10"
73
82
  },
74
83
  "engines": {
75
- "node": ">=14.0.0"
84
+ "node": ">=22.12.0"
76
85
  }
77
86
  }
package/source/argv2Object.mjs ADDED
@@ -0,0 +1,85 @@
1
+ // @ts-check
2
+ /**
3
+ * @file Converts command-line arguments into a key-value object.
4
+ *
5
+ * @description Parses arguments from `process.argv` as simple `key=value`
6
+ * pairs or Unix-style options.
7
+ *
8
+ * @module argv2Object
9
+ */
10
+
11
+ // ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
12
+ // » IMPORT LOCAL MODULES
13
+ import { COMMAND_LINE_PATTERNS, ERROR_MESSAGES } from '#constants';
14
+ import { createObjectFromArguments } from '#functions';
15
+
16
+ // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
17
+ /**
18
+ * Value produced by converting a raw command-line argument.
19
+ *
20
+ * @typedef {string|number|boolean} ArgumentValue
21
+ */
22
+
23
+ /**
24
+ * Parsed command-line arguments keyed by their normalized names.
25
+ *
26
+ * @typedef {Record<string, ArgumentValue>} ArgvObject
27
+ */
28
+
29
+ // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
30
+ /**
31
+ * Converts command-line arguments into an object.
32
+ *
33
+ * Simple mode accepts `key=value` arguments. Unix mode accepts short options
34
+ * such as `-v` and long options such as `--verbose` or `--output=json`.
35
+ * Argument values are converted to booleans or finite decimal numbers when
36
+ * their complete string representation matches the supported format.
37
+ *
38
+ * @param {boolean} [unixmode] - Whether to parse Unix-style options. Defaults to `false`.
39
+ * @returns {ArgvObject} The object created from the command-line arguments.
40
+ * @throws {TypeError} If `unixmode` is not a boolean.
41
+ * @throws {Error} If no arguments are provided or an argument has an invalid format.
42
+ *
43
+ * @example
44
+ * ```js
45
+ * // Command: node script.mjs name=John age=30
46
+ * const argumentsv = argv2Object();
47
+ * console.log(argumentsv.name); // 'John'
48
+ * console.log(argumentsv.age); // 30
49
+ * ```
50
+ *
51
+ * @example
52
+ * ```js
53
+ * // Command: node script.mjs --name=John --verbose
54
+ * const argumentsv = argv2Object(true);
55
+ * console.log(argumentsv.name); // 'John'
56
+ * console.log(argumentsv.verbose); // true
57
+ * ```
58
+ */
59
+ const argv2Object = (unixmode = false) => {
60
+ if (typeof unixmode !== 'boolean') {
61
+ throw new TypeError(ERROR_MESSAGES.INVALID_UNIXMODE_TYPE);
62
+ }
63
+
64
+ const argumentsv = process.argv.slice(2);
65
+
66
+ if (argumentsv.length === 0) {
67
+ throw new Error(ERROR_MESSAGES.NO_ARGUMENTS);
68
+ }
69
+
70
+ const patterns = unixmode
71
+ ? [COMMAND_LINE_PATTERNS.UNIX_LONG, COMMAND_LINE_PATTERNS.UNIX_SHORT]
72
+ : [COMMAND_LINE_PATTERNS.SIMPLE];
73
+
74
+ const isValid = argumentsv.every(argument => patterns.some(pattern => pattern.test(argument)));
75
+
76
+ if (!isValid) {
77
+ const message = unixmode ? ERROR_MESSAGES.NO_MATCH_UNIXMODE : ERROR_MESSAGES.NO_MATCH_SIMPLE;
78
+ throw new Error(message);
79
+ }
80
+
81
+ return createObjectFromArguments(argumentsv, 'snakecase');
82
+ };
83
+
84
+ // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
85
+ export default argv2Object;
package/source/constants.mjs ADDED
@@ -0,0 +1,56 @@
1
+ // @ts-check
2
+ /**
3
+ * @file Defines argument patterns and validation messages.
4
+ *
5
+ * @description Centralizes the syntax accepted by each argument format and the
6
+ * messages used when public input validation fails.
7
+ *
8
+ * @module constants
9
+ */
10
+
11
+ // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
12
+ /**
13
+ * Regular expressions used to validate command-line arguments.
14
+ *
15
+ * @typedef {object} CommandLinePatterns
16
+ * @property {RegExp} UNIX_SHORT - Matches short Unix options such as `-a` and `-f=value`.
17
+ * @property {RegExp} UNIX_LONG - Matches long Unix options such as `--help` and `--output=json`.
18
+ * @property {RegExp} SIMPLE - Matches `key=value` arguments with letters, digits, and hyphens.
19
+ */
20
+
21
+ /**
22
+ * Error messages used by the argument parser.
23
+ *
24
+ * @typedef {object} ErrorMessages
25
+ * @property {string} INVALID_UNIXMODE_TYPE - The Unix mode argument is not boolean.
26
+ * @property {string} NO_ARGUMENTS - No command-line arguments were provided.
27
+ * @property {string} NO_MATCH_SIMPLE - An argument does not match the simple format.
28
+ * @property {string} NO_MATCH_UNIXMODE - An argument does not match the Unix format.
29
+ */
30
+
31
+ // ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
32
+ /**
33
+ * Regular expressions used to validate command-line arguments.
34
+ *
35
+ * @type {Readonly<CommandLinePatterns>}
36
+ */
37
+ const COMMAND_LINE_PATTERNS = Object.freeze({
38
+ UNIX_SHORT: /^-[a-zA-Z](=.*)?$/,
39
+ UNIX_LONG: /^--[a-zA-Z][a-zA-Z0-9-]*(=.*)?$/,
40
+ SIMPLE: /^[a-zA-Z][a-zA-Z0-9]*(?:-[a-zA-Z0-9]+)*=.*$/,
41
+ });
42
+
43
+ /**
44
+ * Error messages used by the argument parser.
45
+ *
46
+ * @type {Readonly<ErrorMessages>}
47
+ */
48
+ const ERROR_MESSAGES = Object.freeze({
49
+ INVALID_UNIXMODE_TYPE: 'The "unixmode" parameter must be a boolean value',
50
+ NO_ARGUMENTS: 'No command-line arguments were provided',
51
+ NO_MATCH_SIMPLE: 'Arguments must follow "key=value" format',
52
+ NO_MATCH_UNIXMODE: 'Arguments must follow Unix-style format (-a, --option=value)',
53
+ });
54
+
55
+ // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
56
+ export { COMMAND_LINE_PATTERNS, ERROR_MESSAGES };
package/source/functions.mjs ADDED
@@ -0,0 +1,126 @@
1
+ // @ts-check
2
+ /**
3
+ * @file Provides internal argument formatting and conversion functions.
4
+ *
5
+ * @description Normalizes argument keys, converts supported primitive values,
6
+ * and builds the object returned by the public parser.
7
+ *
8
+ * @module functions
9
+ */
10
+
11
+ // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
12
+ /**
13
+ * Supported key formatting modes.
14
+ *
15
+ * @typedef {'camelcase'|'snakecase'} CaseMode
16
+ */
17
+
18
+ /**
19
+ * Supported values produced by command-line argument parsing.
20
+ *
21
+ * @typedef {string|number|boolean} ArgumentValue
22
+ */
23
+
24
+ /**
25
+ * Object containing parsed command-line arguments.
26
+ *
27
+ * @typedef {Record<string, ArgumentValue>} ArgvObject
28
+ */
29
+
30
+ // ━━ CONSTANTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
31
+ /**
32
+ * Matches finite decimal numbers, including signed, fractional, and
33
+ * scientific notation. Rejects hexadecimal, binary, and numeric separators.
34
+ *
35
+ * @type {RegExp}
36
+ */
37
+ const NUMERIC_VALUE_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
38
+
39
+ // ━━ FUNCTIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
40
+ /**
41
+ * Removes option prefixes and applies the requested key casing.
42
+ *
43
+ * @private
44
+ * @param {string} key - The raw argument key.
45
+ * @param {CaseMode} [mode] - The target casing convention.
46
+ * @returns {string} The normalized key.
47
+ * @throws {TypeError} If the key or casing mode is invalid.
48
+ */
49
+ const formatKey = (key, mode) => {
50
+ if (typeof key !== 'string') {
51
+ throw new TypeError('Key must be a string');
52
+ }
53
+
54
+ if (mode !== undefined && mode !== 'camelcase' && mode !== 'snakecase') {
55
+ throw new TypeError('Key mode must be "camelcase" or "snakecase"');
56
+ }
57
+
58
+ const normalizedKey = key.replace(/^-{1,2}/, '');
59
+
60
+ if (mode === 'camelcase') {
61
+ return normalizedKey.replace(/-([a-z])/gi, (_, character) => character.toUpperCase());
62
+ }
63
+
64
+ if (mode === 'snakecase') {
65
+ return normalizedKey.replace(/-/g, '_');
66
+ }
67
+
68
+ return normalizedKey;
69
+ };
70
+
71
+ /**
72
+ * Converts boolean and finite decimal strings while preserving other text.
73
+ *
74
+ * @private
75
+ * @param {string|undefined} value - The raw argument value.
76
+ * @returns {ArgumentValue} The converted value.
77
+ */
78
+ const convertValue = value => {
79
+ if (value === undefined || value === 'true') {
80
+ return true;
81
+ }
82
+
83
+ if (value === 'false') {
84
+ return false;
85
+ }
86
+
87
+ if (value !== undefined && NUMERIC_VALUE_PATTERN.test(value) && Number.isFinite(Number(value))) {
88
+ return Number(value);
89
+ }
90
+
91
+ return value ?? '';
92
+ };
93
+
94
+ /**
95
+ * Parses one argument into its normalized key and converted value.
96
+ *
97
+ * @private
98
+ * @param {string} argument - The argument to parse.
99
+ * @param {CaseMode} mode - The target key casing convention.
100
+ * @returns {[string, ArgumentValue]} The normalized key and converted value.
101
+ */
102
+ const parseArgument = (argument, mode) => {
103
+ const separatorIndex = argument.indexOf('=');
104
+ const rawKey = separatorIndex === -1 ? argument : argument.slice(0, separatorIndex);
105
+ const rawValue = separatorIndex === -1 ? undefined : argument.slice(separatorIndex + 1);
106
+
107
+ return [formatKey(rawKey, mode), convertValue(rawValue)];
108
+ };
109
+
110
+ /**
111
+ * Builds an object from validated command-line arguments.
112
+ *
113
+ * Repeated keys use the last supplied value. Values are split at the first `=`;
114
+ * additional separators remain part of the value.
115
+ *
116
+ * @private
117
+ * @param {string[]} argumentsv - The validated arguments to process.
118
+ * @param {CaseMode} mode - The target key casing convention.
119
+ * @returns {ArgvObject} The parsed argument object.
120
+ */
121
+ const createObjectFromArguments = (argumentsv, mode) => {
122
+ return Object.fromEntries(argumentsv.map(argument => parseArgument(argument, mode)));
123
+ };
124
+
125
+ // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
126
+ export { formatKey, convertValue, createObjectFromArguments };
package/types/index.d.cts ADDED
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Value produced by converting a raw command-line argument.
3
+ */
4
+ type ArgumentValue = string | number | boolean;
5
+
6
+ /**
7
+ * Parsed command-line arguments keyed by their normalized names.
8
+ */
9
+ type ArgvObject = Record<string, ArgumentValue>;
10
+
11
+ /**
12
+ * Converts command-line arguments from `process.argv` into an object.
13
+ *
14
+ * @param unixmode - Whether to parse Unix-style options. Defaults to `false`.
15
+ * @returns The object created from the command-line arguments.
16
+ * @throws {TypeError} If `unixmode` is not a boolean.
17
+ * @throws {Error} If no command-line arguments are provided.
18
+ * @throws {Error} If any argument does not match the selected format.
19
+ */
20
+ declare function argv2Object(unixmode?: boolean): ArgvObject;
21
+
22
+ export = argv2Object;
package/types/index.d.mts ADDED
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Value produced by converting a raw command-line argument.
3
+ */
4
+ export type ArgumentValue = string | number | boolean;
5
+
6
+ /**
7
+ * Parsed command-line arguments keyed by their normalized names.
8
+ */
9
+ export type ArgvObject = Record<string, ArgumentValue>;
10
+
11
+ /**
12
+ * Converts command-line arguments from `process.argv` into an object.
13
+ *
14
+ * @param unixmode - Whether to parse Unix-style options. Defaults to `false`.
15
+ * @returns The object created from the command-line arguments.
16
+ * @throws {TypeError} If `unixmode` is not a boolean.
17
+ * @throws {Error} If no command-line arguments are provided.
18
+ * @throws {Error} If any argument does not match the selected format.
19
+ */
20
+ declare function argv2Object(unixmode?: boolean): ArgvObject;
21
+
22
+ export default argv2Object;
package/src/argv2Object.mjs DELETED
@@ -1,89 +0,0 @@
1
- /**
2
- * @file Converts command-line arguments to a key-value object.
3
- *
4
- * A utility function for converting command-line arguments to a key-value
5
- * object.
6
- *
7
- * This file defines a single function, `argv2Object`, which parses
8
- * command-line arguments and returns an object with keys and values
9
- * corresponding to the provided arguments. The function can handle two types of
10
- * arguments: simple key-value pairs (e.g. "key=value") and Unix-style
11
- * command-line arguments (e.g. "-k value" or "--key=value").
12
- *
13
- * @version 1.1.0
14
- *
15
- * @example
16
- * Simple key-value pairs
17
- * Command line input: node script.js name=John age=30 level=admin
18
- * Output: { name: 'John', age: '30', level: "admin" }
19
- *
20
- * @example
21
- * Unix-style command-line options
22
- * Command line input: node script.js -h --name=John --is-admin
23
- * Output: { h: true, name: 'John', is_admin: true }
24
- */
25
- // ━━ IMPORT MODULES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
26
- // » IMPORT LOCAL MODULES
27
- import { COMMAND_LINE_PATTERNS, ERROR_MESSAGES } from '#constants';
28
- import { createObjectFromArguments } from '#functions';
29
-
30
- // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
31
- /**
32
- * An `Object` with keys and values corresponding to the provided arguments.
33
- *
34
- * @typedef {object} ArgvObject
35
- * @property {string|boolean} [key=value] - The key-value pairs in the provided arguments.
36
- */
37
-
38
- // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
39
- /**
40
- * The `argv2Object()` function, converts command-line arguments to a key-value
41
- * object.
42
- *
43
- * This function takes an array of command-line arguments and converts them to a
44
- * JavaScript object with keys and values based on the provided argument format.
45
- * The format can be either simple key-value pairs (e.g. "key=value") or
46
- * Unix-style command-line options (e.g. "-o --option=value").
47
- *
48
- * @function
49
- * @param {boolean} [unixmode] - Whether to parse Unix-style command-line options, the default value is `false`.
50
- * @returns {ArgvObject} Returns an object with keys and values corresponding to the provided arguments.
51
- * @throws {TypeError} If `unixmode` is not is not of type `boolean`.
52
- * @throws {Error} If no arguments are provided from command line.
53
- * @throws {Error} If `unixmode` is `true` and argument does not follow Unix-style command-line format.
54
- * @throws {Error} If `unixmode` is `false` and argument does not follow 'key=value' format.
55
- * @example
56
- * ```js
57
- * // Command line input: node script.js --task=some-task --execute=true
58
- *
59
- * const argumentsv = argv2Object();
60
- * console.log(argumentsv.task); // prints 'some-task'
61
- * console.log(argumentsv.execute); // prints true
62
- * ```
63
- */
64
- const argv2Object = (unixmode = false) => {
65
- if (typeof unixmode !== 'boolean') {
66
- throw new TypeError(ERROR_MESSAGES.INVALID_UNIXMODE_TYPE);
67
- }
68
-
69
- const argumentsv = process.argv.slice(2);
70
- if (argumentsv.length === 0) {
71
- throw new Error(ERROR_MESSAGES.NO_ARGUMENTS);
72
- }
73
-
74
- const patterns = unixmode
75
- ? [COMMAND_LINE_PATTERNS.UNIX_LONG, COMMAND_LINE_PATTERNS.UNIX_SHORT]
76
- : [COMMAND_LINE_PATTERNS.SIMPLE];
77
-
78
- const isValid = argumentsv.every(argument => patterns.some(pattern => pattern.test(argument)));
79
-
80
- if (!isValid) {
81
- const message = unixmode ? ERROR_MESSAGES.NO_MATCH_UNIXMODE : ERROR_MESSAGES.NO_MATCH_SIMPLE;
82
- throw new Error(message);
83
- }
84
-
85
- return createObjectFromArguments(argumentsv, 'snakecase');
86
- };
87
-
88
- // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
89
- export default argv2Object;
package/src/constants.mjs DELETED
@@ -1,115 +0,0 @@
1
- /**
2
- * @file Module containing constants for argument validation.
3
- *
4
- * This module exports regular expressions for argument pattern matching
5
- * and standardized error messages used throughout the argv2object library.
6
- * These constants ensure consistent validation and error reporting when
7
- * parsing command-line arguments.
8
- *
9
- * @module constants
10
- * @since 1.0.0
11
- */
12
-
13
- // ━━ TYPE DEFINITIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
14
- /**
15
- * Type definition for command line argument patterns.
16
- *
17
- * @typedef {object} CommandLinePatterns
18
- * @property {RegExp} UNIX_SHORT - Matches short Unix flags: `-a`, `-v`, `-f=value`.
19
- * @property {RegExp} UNIX_LONG - Matches long Unix flags: `--help`, `--output=json`.
20
- * @property {RegExp} SIMPLE - Pattern for simple key=value arguments: key=value, multi-part-key=value.
21
- */
22
-
23
- /**
24
- * Standardized error messages for argument validation failures.
25
- *
26
- * @typedef {object} ErrorMessages
27
- * @property {string} INVALID_UNIXMODE_TYPE - When unixmode parameter is not boolean.
28
- * @property {string} NO_ARGUMENTS - When no arguments are provided.
29
- * @property {string} NO_MATCH_SIMPLE - When simple args don't match key=value format.
30
- * @property {string} NO_MATCH_UNIXMODE - When args don't match Unix-style format.
31
- */
32
-
33
- // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
34
- /**
35
- * Regular expression patterns for validating command line argument formats.
36
- *
37
- * Provides comprehensive pattern matching for different command line argument
38
- * styles commonly used in Node.js applications and CLI tools.
39
- *
40
- * @exports
41
- * @private
42
- * @constant COMMAND_LINE_PATTERNS
43
- * @type {CommandLinePatterns}
44
- *
45
- * @example
46
- * ```js
47
- * // Valid short flags:
48
- * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-h') // true
49
- * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-v') // true
50
- * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-f=json') // true
51
- *
52
- * // Invalid short flags:
53
- * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('--help') // false
54
- * COMMAND_LINE_PATTERNS.UNIX_SHORT.test('-abc') // false
55
- * ```
56
- *
57
- * @example
58
- * ```js
59
- * // Valid long flags:
60
- * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--help') // true
61
- * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--output=json') // true
62
- * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--dry-run') // true
63
- *
64
- * // Invalid long flags:
65
- * COMMAND_LINE_PATTERNS.UNIX_LONG.test('-h') // false
66
- * COMMAND_LINE_PATTERNS.UNIX_LONG.test('--123') // false
67
- * ```
68
- *
69
- * @example
70
- * ```js
71
- * // Valid simple arguments:
72
- * COMMAND_LINE_PATTERNS.SIMPLE.test('output=json') // true
73
- * COMMAND_LINE_PATTERNS.SIMPLE.test('config-file=settings') // true
74
- *
75
- * // Invalid simple arguments:
76
- * COMMAND_LINE_PATTERNS.SIMPLE.test('--output=json') // false
77
- * COMMAND_LINE_PATTERNS.SIMPLE.test('output') // false
78
- * ```
79
- */
80
- const COMMAND_LINE_PATTERNS = {
81
- UNIX_SHORT: /^-[a-zA-Z](=.*)?$/,
82
- UNIX_LONG: /^--[a-zA-Z][a-zA-Z0-9-]*(=.*)?$/,
83
- SIMPLE: /^[a-zA-Z]+(?:-[a-zA-Z]+)*=.*$/,
84
- };
85
-
86
- /**
87
- * Standardized error messages for consistent validation feedback.
88
- *
89
- * @exports
90
- * @private
91
- * @constant THROWS_ERRORS_MESSAGES
92
- * @type {ErrorMessages}
93
- * @example
94
- * ```js
95
- * // Error cases:
96
- * throw new Error(ERROR_MESSAGES.INVALID_UNIXMODE_TYPE);
97
- * throw new Error(ERROR_MESSAGES.NO_ARGUMENTS);
98
- * ```
99
- */
100
- const ERROR_MESSAGES = {
101
- INVALID_UNIXMODE_TYPE: 'The "unixmode" parameter must be a boolean value',
102
- NO_ARGUMENTS: 'No command-line arguments were provided',
103
- NO_MATCH_SIMPLE: 'Arguments must follow "key=value" format',
104
- NO_MATCH_UNIXMODE: 'Arguments must follow Unix-style format (-a, --option=value)',
105
- };
106
-
107
- // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
108
- /**
109
- * Exported constants for argument validation.
110
- *
111
- * @type {object}
112
- * @property {CommandLinePatterns} REGEXPS - Validation patterns.
113
- * @property {ErrorMessages} THROWS_ERRORS_MESSAGES - Standard error messages.
114
- */
115
- export { COMMAND_LINE_PATTERNS, ERROR_MESSAGES };
package/src/functions.mjs DELETED
@@ -1,124 +0,0 @@
1
- /**
2
- * @file Module containing utility functions for argument processing.
3
- *
4
- * Provides formatting and type conversion functions used internally
5
- * by the argv2object library to normalize and transform command-line
6
- * arguments into consistent JavaScript data structures.
7
- *
8
- * @module Functions
9
- * @since 1.0.0
10
- */
11
-
12
- // ━━ MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
13
- /**
14
- * Normalizes and formats argument keys according to specified casing convention.
15
- *
16
- * Removes leading dashes from command-line flags and applies optional case conversion.
17
- *
18
- * Supports:
19
- *
20
- * - camelCase conversion (--some-flag → someFlag).
21
- * - snake_case conversion (--some-flag → some_flag).
22
- * - No conversion (--some-flag → some-flag).
23
- *
24
- * @exports
25
- * @private
26
- * @function formatKey
27
- * @param {string} key - The raw key from command-line arguments.
28
- * @param {'camelcase'|'snakecase'} [mode] - Target formatting mode.
29
- * @returns {string} Normalized and formatted key.
30
- * @throws {TypeError} If key is not a string.
31
- * @example
32
- * ```js
33
- * formatKey('--output-format', 'camelcase') // returns 'outputFormat'
34
- * formatKey('-v', 'snakecase') // returns 'v' (no underscores needed)
35
- * formatKey('--enable-logging') // returns 'enable-logging'
36
- * ```
37
- */
38
- const formatKey = (key, mode) => {
39
- if (typeof key !== 'string') {
40
- throw new TypeError('Key must be a string');
41
- }
42
- const sanitizedKey = key.replace(/^-{1,2}/, '');
43
-
44
- if (mode === 'camelcase') {
45
- return sanitizedKey.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
46
- }
47
-
48
- if (mode === 'snakecase') {
49
- return sanitizedKey.replace(/-/g, '_');
50
- }
51
-
52
- return sanitizedKey;
53
- };
54
-
55
- /**
56
- * Converts string values from command-line arguments to proper JavaScript types.
57
- *
58
- * Performs automatic conversion of:
59
- *
60
- * - 'true'/'false' strings → boolean.
61
- * - Numeric strings → number.
62
- * - undefined values → true (for flag arguments).
63
- * - All other values remain as strings.
64
- *
65
- * @exports
66
- * @private
67
- * @function convertValue
68
- * @param {string} [value] - The value to convert.
69
- * @returns {string|boolean|number} Converted value.
70
- * @example
71
- * ```js
72
- * convertValue('true') // returns true
73
- * convertValue('42') // returns 42
74
- * convertValue() // returns true (for flag arguments)
75
- * convertValue('text') // returns 'text'
76
- * ```
77
- */
78
- const convertValue = value => {
79
- if (value === undefined) return true;
80
- if (value === 'true') return true;
81
- if (value === 'false') return false;
82
- if (!Number.isNaN(value) && !Number.isNaN(parseFloat(value))) return Number(value);
83
- return value;
84
- };
85
-
86
- /**
87
- * Creates an object from command line arguments by parsing key-value pairs.
88
- *
89
- * @param {string[]} argumentsv - Array of command line arguments to process.
90
- * @param {'camelcase'|'snakecase'} mode - Target formatting mode.
91
- * @returns {object} Object with parsed keys and converted values.
92
- * @throws {Error} When arguments cannot be parsed into valid key-value pairs.
93
- *
94
- * @example
95
- * ```js
96
- * // Simple mode: key=value pairs
97
- * createObjectFromArguments(['name=John', 'age=30'], 'snakecase');
98
- * // Returns: { name: 'John', age: 30 }
99
- *
100
- * // Unix mode: flags and options
101
- * createObjectFromArguments(['--name=John', '-a'], 'snakecase');
102
- * // Returns: { name: 'John', a: true }
103
- * ```
104
- */
105
- const createObjectFromArguments = (argumentsv, mode) => {
106
- const entries = [...argumentsv].map(argumentv => {
107
- const [k, v] = argumentv.split('=');
108
- const key = formatKey(k, mode);
109
- const value = convertValue(v);
110
- return [key, value];
111
- });
112
-
113
- return Object.fromEntries(entries);
114
- };
115
-
116
- // ━━ EXPORT MODULE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
117
- /**
118
- * Utility functions for argument processing.
119
- *
120
- * @namespace
121
- * @property {Function} formatKey - Key formatting/normalization function.
122
- * @property {Function} convertValue - Value type conversion function.
123
- */
124
- export { formatKey, convertValue, createObjectFromArguments };