args-tokens 0.0.0 โ†’ 0.2.1

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 (6) hide show
  1. package/README.md +200 -1
  2. package/package.json +5 -1
  3. package/lib/cjs/index.d.ts +0 -1
  4. package/lib/cjs/index.js +0 -6
  5. package/lib/esm/index.d.ts +0 -1
  6. package/lib/esm/index.js +0 -3
package/README.md CHANGED
@@ -1 +1,200 @@
1
- # args
1
+ # args-tokens
2
+
3
+ [![Version][npm-version-src]][npm-version-href]
4
+ [![CI][ci-src]][ci-href]
5
+
6
+ > [`parseArgs` tokens](https://nodejs.org/api/util.html#parseargs-tokens) compatibility and more high-performance parser
7
+
8
+ ## ๐Ÿฑ Motivation
9
+
10
+ - Although Node.js's [`parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig) can return tokens, tokens that the short options are not in the format I expect. Of course, I recoginize the background of [this issue](https://github.com/pkgjs/parseargs/issues/78).
11
+ - `parseArgs` gives the command line args parser a useful util, so the resolution of the options values and the parsing of the tokens are tightly coupled. As a result, Performance is sacrificed. Of course, I recoginize that's the trade-off.
12
+
13
+ ## โฑ๏ธ Benchmark
14
+
15
+ With [mitata](https://github.com/evanwashere/mitata):
16
+
17
+ ```
18
+ pnpm bench:mitata
19
+
20
+ > args-tokens@0.0.0 bench:mitata /path/to/projects/args-tokens
21
+ > node --expose-gc bench/index.mjs
22
+
23
+ clk: ~2.87 GHz
24
+ cpu: Apple M1 Max
25
+ runtime: node 18.19.1 (arm64-darwin)
26
+
27
+ benchmark avg (min โ€ฆ max) p75 / p99 (min โ€ฆ top 1%)
28
+ ------------------------------------------- -------------------------------
29
+ node:util parseArgs 4.69 ยตs/iter 4.78 ยตs โ–ˆ โ–ˆ โ–ˆโ–ˆ
30
+ (4.49 ยตs โ€ฆ 4.91 ยตs) 4.85 ยตs โ–ˆ โ–ˆ โ–ˆโ–ˆ โ–ˆ โ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆ
31
+ ( 1.32 kb โ€ฆ 1.49 kb) 1.33 kb โ–ˆโ–โ–ˆโ–ˆโ–โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ
32
+
33
+ args-tokens parseArgs 842.98 ns/iter 882.65 ns โ–„โ–„โ–„โ–‡โ–ƒ โ–„โ–ƒ โ–ˆ
34
+ (734.10 ns โ€ฆ 984.32 ns) 966.06 ns โ–‚โ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–…โ–…โ–„
35
+ ( 3.11 kb โ€ฆ 3.41 kb) 3.12 kb โ–ˆโ–‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–†โ–†โ–†โ–‚
36
+
37
+ โ”Œ โ”
38
+ node:util parseArgs โ”คโ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ–  4.69 ยตs
39
+ args-tokens parseArgs โ”ค 842.98 ns
40
+ โ”” โ”˜
41
+ ```
42
+
43
+ With [vitest](https://vitest.dev/guide/features.html#benchmarking):
44
+
45
+ ```
46
+ pnpm bench:vitest
47
+
48
+ > args-tokens@0.0.0 bench:vitest /path/to/projects/args-tokens
49
+ > vitest bench --run
50
+
51
+ Benchmarking is an experimental feature.
52
+ Breaking changes might not follow SemVer, please pin Vitest's version when using it.
53
+
54
+ RUN v3.0.5 /path/to/projects/args-tokens
55
+
56
+
57
+ โœ“ bench/vitest.bench.mjs > parseArgs 1466ms
58
+ name hz min max mean p75 p99 p995 p999 rme samples
59
+ ยท node:util 194,911.34 0.0042 0.6821 0.0051 0.0046 0.0151 0.0292 0.1079 ยฑ0.82% 97456
60
+ ยท args-tokens 1,101,845.21 0.0007 0.1883 0.0009 0.0009 0.0012 0.0031 0.0140 ยฑ0.32% 550923 fastest
61
+
62
+ BENCH Summary
63
+
64
+ args-tokens - bench/vitest.bench.mjs > parseArgs
65
+ 5.65x faster than node:util
66
+ ```
67
+
68
+ ## โ“ What's different about parseArgs tokens?
69
+
70
+ The token output for the short option `-x=v` is different:
71
+
72
+ ```js
73
+ import { parseArgs as parseArgsNode } from 'node:util'
74
+ import { parseArgs } from 'args-tokens'
75
+
76
+ // Node.js parseArgs tokens
77
+ const { tokens: tokensNode } = parseArgsNode({
78
+ allowPositionals: true,
79
+ strict: false,
80
+ args: ['-a=1'],
81
+ tokens: true
82
+ })
83
+ console.log(tokensNode)
84
+
85
+ // ({
86
+ // kind: 'option',
87
+ // name: 'a',
88
+ // rawName: '-a',
89
+ // index: 0,
90
+ // value: undefined,
91
+ // inlineValue: undefined
92
+ // },
93
+ // {
94
+ // kind: 'option',
95
+ // name: '=',
96
+ // rawName: '-=',
97
+ // index: 0,
98
+ // value: undefined,
99
+ // inlineValue: undefined
100
+ // },
101
+ // {
102
+ // kind: 'option',
103
+ // name: '1',
104
+ // rawName: '-1',
105
+ // index: 0,
106
+ // value: undefined,
107
+ // inlineValue: undefined
108
+ // })
109
+ // ]
110
+
111
+ // args-tokens parseArgs tokens
112
+ const tokens = parseArgs(['-a=1'])
113
+ console.log(tokens)
114
+
115
+ // [
116
+ // {
117
+ // kind: 'option',
118
+ // name: 'a',
119
+ // rawName: '-a',
120
+ // index: 0,
121
+ // value: undefined,
122
+ // inlineValue: undefined
123
+ // },
124
+ // { kind: 'option', index: 0, value: '1', inlineValue: true }
125
+ // ]
126
+ ```
127
+
128
+ ## ๐Ÿš€ Usage
129
+
130
+ ### ๐Ÿ’ฟ Installation
131
+
132
+ ```sh
133
+ # npm
134
+ npm install --save args-tokens
135
+
136
+ ## yarn
137
+ yarn add args-tokens
138
+
139
+ ## pnpm
140
+ pnpm add args-tokens
141
+ ```
142
+
143
+ ### ๐Ÿญ Codes
144
+
145
+ ```js
146
+ import { parseArgs } from 'args-tokens'
147
+
148
+ const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
149
+ // do something with using tokens
150
+ // ...
151
+ console.log('tokens:', tokens)
152
+ ```
153
+
154
+ ## Node.js `parseArgs` tokens compatible
155
+
156
+ If you want to use the same short options tokens as returned Node.js `parseArgs`, you can use `allowCompatible` parse option on `parseArgs`:
157
+
158
+ ```js
159
+ import { parseArgs as parseArgsNode } from 'node:util'
160
+ import { parseArgs } from 'args-tokens'
161
+ import { deepStrictEqual } from 'node:assert'
162
+
163
+ const args = ['-a=1', '2']
164
+
165
+ // Node.js parseArgs tokens
166
+ const { tokens: tokensNode } = parseArgsNode({
167
+ allowPositionals: true,
168
+ strict: false,
169
+ args,
170
+ tokens: true
171
+ })
172
+
173
+ // args-tokens parseArgs tokens
174
+ const tokens = parseArgs(['-a=1'], { allowCompatible: true }) // add `allowCompatible` option
175
+
176
+ // validate
177
+ deepStrictEqual(tokensNode, tokens)
178
+ ```
179
+
180
+ ## ๐Ÿ™Œ Contributing guidelines
181
+
182
+ If you are interested in contributing to `args-tokens`, I highly recommend checking out [the contributing guidelines](/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](/CONTRIBUTING.md#development-setup)) etc., there.
183
+
184
+ ## ๐Ÿ’– Credits
185
+
186
+ This project is inspired by:
187
+
188
+ - [`utils.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig), created by Node.js contributors and [OpenJS Foundation](https://openjsf.org/)
189
+ - [`pkgjs/parseargs`](https://github.com/pkgjs/parseargs), created by Node.js CLI package maintainers and Node.js community.
190
+
191
+ ## ยฉ๏ธ License
192
+
193
+ [MIT](http://opensource.org/licenses/MIT)
194
+
195
+ <!-- Badges -->
196
+
197
+ [npm-version-src]: https://img.shields.io/npm/v/args-tokens?style=flat
198
+ [npm-version-href]: https://npmjs.com/package/args-tokens
199
+ [ci-src]: https://github.com/kazupon/args-tokens/actions/workflows/ci.yml/badge.svg
200
+ [ci-href]: https://github.com/kazupon/args-tokens/actions/workflows/ci.yml
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "args-tokens",
3
3
  "description": "parseArgs tokens compatibility and more high-performance parser",
4
- "version": "0.0.0",
4
+ "version": "0.2.1",
5
5
  "author": {
6
6
  "name": "kazuya kawaguchi",
7
7
  "email": "kawakazu80@gmail.com"
@@ -28,6 +28,7 @@
28
28
  "engines": {
29
29
  "node": ">= 18.18"
30
30
  },
31
+ "type": "module",
31
32
  "files": [
32
33
  "lib"
33
34
  ],
@@ -70,6 +71,7 @@
70
71
  "gh-changelogen": "^0.2.8",
71
72
  "knip": "^5.44.0",
72
73
  "lint-staged": "^15.4.3",
74
+ "mitata": "^1.0.34",
73
75
  "pkg-pr-new": "^0.0.39",
74
76
  "prettier": "^3.5.0",
75
77
  "typescript": "^5.7.3",
@@ -91,6 +93,8 @@
91
93
  ]
92
94
  },
93
95
  "scripts": {
96
+ "bench:mitata": "node --expose-gc bench/index.mjs",
97
+ "bench:vitest": "vitest bench --run",
94
98
  "build": "pnpm run --parallel --color \"/^build:/\"",
95
99
  "build:cjs": "tsc -p ./tsconfig.cjs.json",
96
100
  "build:esm": "tsc -p ./tsconfig.esm.json",
package/lib/cjs/index.d.ts DELETED
@@ -1 +0,0 @@
1
- export declare function add(a: number, b: number): number;
package/lib/cjs/index.js DELETED
@@ -1,6 +0,0 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.add = add;
4
- function add(a, b) {
5
- return a + b;
6
- }
package/lib/esm/index.d.ts DELETED
@@ -1 +0,0 @@
1
- export declare function add(a: number, b: number): number;
package/lib/esm/index.js DELETED
@@ -1,3 +0,0 @@
1
- export function add(a, b) {
2
- return a + b;
3
- }