args-tokens 0.8.0 → 0.10.0

package/README.md

@@ -2,10 +2,20 @@
 
 [![Version][npm-version-src]][npm-version-href]
 [![JSR][jsr-src]][jsr-href]
+[![InstallSize][install-size-src]][install-size-src]
 [![CI][ci-src]][ci-href]
 
 > [`parseArgs` tokens](https://nodejs.org/api/util.html#parseargs-tokens) compatibility and more high-performance parser
 
+## ✨ Features
+
+- ✅ High performance
+- ✅ `util.parseArgs` token compatibility
+- ✅ ES Modules and modern JavaScript
+- ✅ Type safe
+- ✅ Zero dependencies
+- ✅ Universal runtime
+
 ## 🐱 Motivation
 
 - Although Node.js [`parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig) can return 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).
@@ -19,26 +29,36 @@ With [mitata](https://github.com/evanwashere/mitata):
 pnpm bench:mitata
 
 > args-tokens@0.0.0 bench:mitata /path/to/projects/args-tokens
-> node --expose-gc bench/index.mjs
+> node --expose-gc bench/mitata.js
 
 clk: ~2.87 GHz
 cpu: Apple M1 Max
 runtime: node 18.19.1 (arm64-darwin)
 
-benchmark                   avg (min … max) p75 / p99    (min … top 1%)
-------------------------------------------- -------------------------------
-node:util parseArgs            4.69 µs/iter   4.78 µs      █ █     ██
-                        (4.49 µs … 4.91 µs)   4.85 µs    █ █ ██ █  ██  ███
-                    (  1.32 kb …   1.49 kb)   1.33 kb █▁██▁██████▁█████████
-
-args-tokens parseArgs        842.98 ns/iter 882.65 ns     ▄▄▄▇▃ ▄▃ █
-                    (734.10 ns … 984.32 ns) 966.06 ns   ▂▄█████▄████▅▅▄
-                    (  3.11 kb …   3.41 kb)   3.12 kb █▂███████████████▆▆▆▂
-
-                             ┌                                            ┐
-         node:util parseArgs ┤■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 4.69 µs
-       args-tokens parseArgs ┤ 842.98 ns
-                             └                                            ┘
+benchmark                                       avg (min … max) p75 / p99    (min … top 1%)
+--------------------------------------------------------------- -------------------------------
+util.parseArgs                                     4.16 µs/iter   4.20 µs █
+                                            (4.09 µs … 4.29 µs)   4.28 µs ██ ▅▅▅       ▅
+                                        (  1.36 kb …   1.52 kb)   1.37 kb ██▁████▅▅█▅▁██▁▁▅▁█▅█
+
+args-tokens parse (equivalent to util.parseArgs)   1.65 µs/iter   1.66 µs    █
+                                            (1.61 µs … 1.80 µs)   1.79 µs ▅▃ █▂ ▄
+                                        (  1.95 kb …   2.66 kb)   1.97 kb █████▆█▄▃▃▅▃▁▃▃▁▄▁▁▁▂
+
+args-tokens parseArgs                            729.56 ns/iter 734.11 ns         █
+                                        (697.43 ns … 797.08 ns) 774.93 ns        ▂█▅▂
+                                        (  2.87 kb …   3.54 kb)   3.11 kb ▂▂▃▇▆▅▆████▃▃▄▂▂▂▂▂▁▂
+
+args-tokens resolveArgs                          886.78 ns/iter 887.70 ns       █
+                                        (853.96 ns … 978.89 ns) 957.24 ns       █
+                                        (  2.51 kb …   2.87 kb)   2.79 kb ▂▃█▃▄▅█▄▃▂▂▃▃▂▂▂▂▂▁▁▁
+
+                                                 ┌                                            ┐
+                                  util.parseArgs ┤■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 4.16 µs
+args-tokens parse (equivalent to util.parseArgs) ┤■■■■■■■■■ 1.65 µs
+                           args-tokens parseArgs ┤ 729.56 ns
+                         args-tokens resolveArgs ┤■■ 886.78 ns
+                                                 └                                            ┘
 ```
 
 With [vitest](https://vitest.dev/guide/features.html#benchmarking):
@@ -55,15 +75,24 @@ Breaking changes might not follow SemVer, please pin Vitest's version when using
  RUN  v3.0.5 /path/to/projects/args-tokens
 
 
- ✓ bench/vitest.bench.mjs > parseArgs 1466ms
+ ✓ bench/vitest.bench.js > parse and resolve 1350ms
+     name                       hz     min     max    mean     p75     p99    p995    p999     rme  samples
+   · util.parseArgs     221,285.36  0.0041  0.2700  0.0045  0.0044  0.0054  0.0063  0.0629  ±0.38%   110643
+   · args-tokens parse  527,127.11  0.0017  0.2153  0.0019  0.0019  0.0023  0.0027  0.0055  ±0.38%   263564   fastest
+
+ ✓ bench/vitest.bench.js > parseArgs 1434ms
      name                   hz     min     max    mean     p75     p99    p995    p999     rme  samples
-   · node:util      194,911.34  0.0042  0.6821  0.0051  0.0046  0.0151  0.0292  0.1079  ±0.82%    97456
-   · args-tokens  1,101,845.21  0.0007  0.1883  0.0009  0.0009  0.0012  0.0031  0.0140  ±0.32%   550923   fastest
+   · node:util      235,217.05  0.0039  0.2665  0.0043  0.0042  0.0048  0.0058  0.0139  ±0.43%   117609
+   · args-tokens  1,307,135.24  0.0006  0.1737  0.0008  0.0008  0.0009  0.0010  0.0016  ±0.43%   653568   fastest
 
  BENCH  Summary
 
-  args-tokens - bench/vitest.bench.mjs > parseArgs
-    5.65x faster than node:util
+  args-tokens parse - bench/vitest.bench.js > parse and resolve
+    2.38x faster than util.parseArgs
+
+  args-tokens - bench/vitest.bench.js > parseArgs
+    5.56x faster than node:util
+
 ```
 
 ## ❓ What's different about parseArgs tokens?
@@ -273,6 +302,10 @@ const tokens = parseArgs(['-a=1'], { allowCompatible: true }) // add `allowCompa
 deepStrictEqual(tokensNode, tokens)
 ```
 
+## 💁‍♀️ Showcases
+
+- [pnpmc](https://github.com/kazupon/pnpmc): PNPM Catalogs Tooling
+
 ## 🙌 Contributing guidelines
 
 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.
@@ -294,5 +327,7 @@ This project is inspired by:
 [npm-version-href]: https://npmjs.com/package/args-tokens
 [jsr-src]: https://jsr.io/badges/@kazupon/args-tokens
 [jsr-href]: https://jsr.io/@kazupon/args-tokens
+[install-size-src]: https://pkg-size.dev/badge/install/35082
+[install-size-href]: https://pkg-size.dev/args-tokens
 [ci-src]: https://github.com/kazupon/args-tokens/actions/workflows/ci.yml/badge.svg
 [ci-href]: https://github.com/kazupon/args-tokens/actions/workflows/ci.yml

package/lib/parse.d.ts

@@ -21,6 +21,10 @@ export type ParsedArgs<T extends ArgOptions> = {
      * Positional arguments, same as `positionals` in {@link resolveArgs}
      */
     positionals: string[];
+    /**
+     * Validation errors, same as `errors` in {@link resolveArgs}
+     */
+    error: AggregateError | undefined;
 };
 /**
  * Parse command line arguments
@@ -33,8 +37,8 @@ export type ParsedArgs<T extends ArgOptions> = {
  * console.log('values', values)
  * console.log('positionals', positionals)
  * ```
- * @param args command line arguments
- * @param options parse options, about details see {@link ParseOptions}
- * @returns parsed values
+ * @param args - command line arguments
+ * @param options - parse options, about details see {@link ParseOptions}
+ * @returns An object that contains the values of the arguments, positional arguments, and {@link AggregateError | validation errors}.
  */
 export declare function parse<O extends ArgOptions>(args: string[], options?: ParseOptions<O>): ParsedArgs<O>;

package/lib/parse.js

@@ -23,9 +23,9 @@ const DEFAULT_OPTIONS = {
  * console.log('values', values)
  * console.log('positionals', positionals)
  * ```
- * @param args command line arguments
- * @param options parse options, about details see {@link ParseOptions}
- * @returns parsed values
+ * @param args - command line arguments
+ * @param options - parse options, about details see {@link ParseOptions}
+ * @returns An object that contains the values of the arguments, positional arguments, and {@link AggregateError | validation errors}.
  */
 export function parse(args, options = {}) {
     const { options: argOptions, allowCompatible = false } = options;

package/lib/resolver.d.ts

@@ -43,8 +43,15 @@ type ResolveArgValues<O extends ArgOptions, V extends Record<keyof O, unknown>>
 type FilterArgs<O extends ArgOptions, V extends Record<keyof O, unknown>, K extends keyof ArgOptionSchema> = {
     [Option in keyof O as O[Option][K] extends {} ? Option : never]: V[Option];
 };
+/**
+ * Resolve command line arguments
+ * @param options - An options that contains {@link ArgOptionSchema | options schema}.
+ * @param tokens - An array of {@link ArgToken | tokens}.
+ * @returns An object that contains the values of the arguments, positional arguments, and {@link AggregateError | validation errors}.
+ */
 export declare function resolveArgs<T extends ArgOptions>(options: T, tokens: ArgToken[]): {
     values: ArgValues<T>;
     positionals: string[];
+    error: AggregateError | undefined;
 };
 export {};

package/lib/resolver.js

@@ -1,6 +1,12 @@
 // SPDX-License-Identifier: MIT
 // Modifier: kazuya kawaguchi (a.k.a. kazupon)
 import { hasLongOptionPrefix, isShortOption } from './parser.js';
+/**
+ * Resolve command line arguments
+ * @param options - An options that contains {@link ArgOptionSchema | options schema}.
+ * @param tokens - An array of {@link ArgToken | tokens}.
+ * @returns An object that contains the values of the arguments, positional arguments, and {@link AggregateError | validation errors}.
+ */
 export function resolveArgs(options, tokens) {
     const values = {};
     const positionals = [];
@@ -103,22 +109,36 @@ export function resolveArgs(options, tokens) {
     /**
      * resolve values
      */
+    const errors = [];
     for (const [option, schema] of Object.entries(options)) {
-        if (longOptionTokens.length === 0 && shortOptionTokens.length === 0 && schema.required) {
-            throw createRequireError(option, schema);
+        if (schema.required) {
+            const found = longOptionTokens.find(token => token.name === option) ||
+                (schema.short && shortOptionTokens.find(token => token.name === schema.short));
+            if (!found) {
+                errors.push(createRequireError(option, schema));
+                continue;
+            }
         }
         // eslint-disable-next-line unicorn/no-for-loop
         for (let i = 0; i < longOptionTokens.length; i++) {
             const token = longOptionTokens[i];
             // eslint-disable-next-line unicorn/no-null
             if (option === token.name && token.rawName != null && hasLongOptionPrefix(token.rawName)) {
-                validateRequire(token, option, schema);
+                const invalid = validateRequire(token, option, schema);
+                if (invalid) {
+                    errors.push(invalid);
+                    continue;
+                }
                 if (schema.type === 'boolean') {
                     // NOTE: re-set value to undefined, because long boolean type option is set on analyze phase
                     token.value = undefined;
                 }
                 else {
-                    validateValue(token, option, schema);
+                    const invalid = validateValue(token, option, schema);
+                    if (invalid) {
+                        errors.push(invalid);
+                        continue;
+                    }
                 }
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
                 ;
@@ -131,13 +151,21 @@ export function resolveArgs(options, tokens) {
             const token = shortOptionTokens[i];
             // eslint-disable-next-line unicorn/no-null
             if (schema.short === token.name && token.rawName != null && isShortOption(token.rawName)) {
-                validateRequire(token, option, schema);
+                const invalid = validateRequire(token, option, schema);
+                if (invalid) {
+                    errors.push(invalid);
+                    continue;
+                }
                 if (schema.type === 'boolean') {
                     // NOTE: re-set value to undefined, because short boolean type option is set on analyze phase
                     token.value = undefined;
                 }
                 else {
-                    validateValue(token, option, schema);
+                    const invalid = validateValue(token, option, schema);
+                    if (invalid) {
+                        errors.push(invalid);
+                        continue;
+                    }
                 }
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
                 ;
@@ -153,27 +181,28 @@ export function resolveArgs(options, tokens) {
             values[option] = schema.default;
         }
     }
-    return { values, positionals };
+    // eslint-disable-next-line unicorn/error-message
+    return { values, positionals, error: errors.length > 0 ? new AggregateError(errors) : undefined };
 }
 function createRequireError(option, schema) {
     return new Error(`Option '--${option}' ${schema.short ? `or '-${schema.short}'` : ''} is required`);
 }
 function validateRequire(token, option, schema) {
     if (schema.required && schema.type !== 'boolean' && !token.value) {
-        throw createRequireError(option, schema);
+        return createRequireError(option, schema);
     }
 }
 function validateValue(token, option, schema) {
     switch (schema.type) {
         case 'number': {
             if (!isNumeric(token.value)) {
-                throw createTypeError(option, schema);
+                return createTypeError(option, schema);
             }
             break;
         }
         case 'string': {
             if (typeof token.value !== 'string') {
-                throw createTypeError(option, schema);
+                return createTypeError(option, schema);
             }
             break;
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"