args-tokens 0.0.0 → 0.1.0

package/README.md

@@ -1 +1,200 @@
-# args
+# args-tokens
+
+[![Version][npm-version-src]][npm-version-href]
+[![CI][ci-src]][ci-href]
+
+> [`parseArgs` tokens](https://nodejs.org/api/util.html#parseargs-tokens) compatibility and more high-performance parser
+
+## 🐱 Motivation
+
+- Although Node.js's [`parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig) can return tokens, tokens that the shot options are not in the format I expect. Of course, I know the background of [this issue](https://github.com/pkgjs/parseargs/issues/78).
+- `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 know that's a trade-off.
+
+## ⏱️ Benchmark
+
+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
+
+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
+                             └                                            ┘
+```
+
+With [vitest](https://vitest.dev/guide/features.html#benchmarking):
+
+```
+pnpm bench:vitest
+
+> args-tokens@0.0.0 bench:vitest /path/to/projects/args-tokens
+> vitest bench --run
+
+Benchmarking is an experimental feature.
+Breaking changes might not follow SemVer, please pin Vitest's version when using it.
+
+ RUN  v3.0.5 /path/to/projects/args-tokens
+
+
+ ✓ bench/vitest.bench.mjs > parseArgs 1466ms
+     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
+
+ BENCH  Summary
+
+  args-tokens - bench/vitest.bench.mjs > parseArgs
+    5.65x faster than node:util
+```
+
+## ❓ What's different about parseArgs tokens?
+
+The token output for the short option `-x=v` is different:
+
+```js
+import { parseArgs as parseArgsNode } from 'node:util'
+import { parseArgs } from 'args-tokens'
+
+// Node.js parseArgs tokens
+const { tokens: tokensNode } = parseArgsNode({
+  allowPositionals: true,
+  strict: false,
+  args: ['-a=1'],
+  tokens: true
+})
+console.log(tokensNode)
+
+//   ({
+//     kind: 'option',
+//     name: 'a',
+//     rawName: '-a',
+//     index: 0,
+//     value: undefined,
+//     inlineValue: undefined
+//   },
+//   {
+//     kind: 'option',
+//     name: '=',
+//     rawName: '-=',
+//     index: 0,
+//     value: undefined,
+//     inlineValue: undefined
+//   },
+//   {
+//     kind: 'option',
+//     name: '1',
+//     rawName: '-1',
+//     index: 0,
+//     value: undefined,
+//     inlineValue: undefined
+//   })
+// ]
+
+// args-tokens parseArgs tokens
+const tokens = parseArgs(['-a=1'])
+console.log(tokens)
+
+// [
+//   {
+//     kind: 'option',
+//     name: 'a',
+//     rawName: '-a',
+//     index: 0,
+//     value: undefined,
+//     inlineValue: undefined
+//   },
+//   { kind: 'option', index: 0, value: '1', inlineValue: true }
+// ]
+```
+
+## 🚀 Usage
+
+### 💿 Installation
+
+```sh
+# npm
+npm install --save args-tokens
+
+## yarn
+yarn add args-tokens
+
+## pnpm
+pnpm add args-tokens
+```
+
+### 🍭 Codes
+
+```js
+import { parseArgs } from 'args-tokens'
+
+const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
+// do something with using tokens
+// ...
+console.log('tokens:', tokens)
+```
+
+## Node.js `parseArgs` tokens compatible
+
+If you want to use the same short options tokens as returned Node.js `parseArgs`, you can use `allowCompatible` parse option on `parseArgs`:
+
+```js
+import { parseArgs as parseArgsNode } from 'node:util'
+import { parseArgs } from 'args-tokens'
+import { deepStrictEqual } from 'node:assert'
+
+const args = ['-a=1', '2']
+
+// Node.js parseArgs tokens
+const { tokens: tokensNode } = parseArgsNode({
+  allowPositionals: true,
+  strict: false,
+  args,
+  tokens: true
+})
+
+// args-tokens parseArgs tokens
+const tokens = parseArgs(['-a=1'])
+
+// validate
+deepStrictEqual(tokensNode, tokens)
+```
+
+## 🙌 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.
+
+## 💖 Credits
+
+This project is inspired by:
+
+- [`utils.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig), created by Node.js contributors and [OpenJS Foundation](https://openjsf.org/)
+- [`pkgjs/parseargs`](https://github.com/pkgjs/parseargs), created by Node.js CLI package maintainers and Node.js community.
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/args-tokens?style=flat
+[npm-version-href]: https://npmjs.com/package/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/cjs/index.d.ts

@@ -1 +1,27 @@
-export declare function add(a: number, b: number): number;
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+export interface ArgToken {
+    kind: ArgTokenKind;
+    index: number;
+    name?: string;
+    rawName?: string;
+    value?: string;
+    inlineValue?: boolean;
+}
+/**
+ * Parse Options
+ */
+export interface ParseOptions {
+    /**
+     * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode
+     * @default false
+     */
+    allowCompatible?: boolean;
+}
+/**
+ * Parse command line arguments
+ * @param args command line arguments
+ * @param options parse options
+ * @returns argument tokens
+ */
+export declare function parseArgs(args: string[], options?: ParseOptions): ArgToken[];
+export {};

package/lib/cjs/index.js

@@ -1,6 +1,218 @@
 "use strict";
+// SPDX-License-Identifier: MIT
+// Modifier: kazuya kawaguchi (a.k.a. kazupon)
+// Forked from `nodejs/node` (`pkgjs/parseargs`)
+// Repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+// Author: Node.js contributors
+// Code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.add = add;
-function add(a, b) {
-    return a + b;
+exports.parseArgs = parseArgs;
+const HYPHEN_CHAR = '-';
+const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
+const EQUAL_CHAR = '=';
+const EQUAL_CODE = EQUAL_CHAR.codePointAt(0);
+const TERMINATOR = '--';
+const SHORT_OPTION_PREFIX = HYPHEN_CHAR;
+const LONG_OPTION_PREFIX = '--';
+/**
+ * Parse command line arguments
+ * @param args command line arguments
+ * @param options parse options
+ * @returns argument tokens
+ */
+function parseArgs(args, options = {}) {
+    const { allowCompatible = false } = options;
+    const tokens = [];
+    const remainings = [...args];
+    let index = -1;
+    let groupCount = 0;
+    let hasShortValueSeparator = false;
+    while (remainings.length > 0) {
+        const arg = remainings.shift();
+        if (arg == undefined) {
+            break;
+        }
+        const nextArg = remainings[0];
+        if (groupCount > 0) {
+            groupCount--;
+        }
+        else {
+            index++;
+        }
+        // check if `arg` is an options terminator.
+        // guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
+        if (arg === TERMINATOR) {
+            tokens.push({
+                kind: 'option-terminator',
+                index
+            });
+            const mapped = remainings.map(arg => {
+                return { kind: 'positional', index: ++index, value: arg };
+            });
+            tokens.push(...mapped);
+            break;
+        }
+        if (isShortOption(arg)) {
+            const shortOption = arg.charAt(1);
+            let value;
+            let inlineValue;
+            if (groupCount) {
+                // e.g. `-abc`
+                tokens.push({
+                    kind: 'option',
+                    name: shortOption,
+                    rawName: arg,
+                    index,
+                    value,
+                    inlineValue
+                });
+                if (groupCount === 1 && hasOptionValue(nextArg)) {
+                    value = remainings.shift();
+                    if (hasShortValueSeparator) {
+                        inlineValue = true;
+                        hasShortValueSeparator = false;
+                    }
+                    tokens.push({
+                        kind: 'option',
+                        index,
+                        value,
+                        inlineValue
+                    });
+                }
+            }
+            else {
+                // e.g. `-a`
+                tokens.push({
+                    kind: 'option',
+                    name: shortOption,
+                    rawName: arg,
+                    index,
+                    value,
+                    inlineValue
+                });
+            }
+            // eslint-disable-next-line unicorn/no-null
+            if (value != null) {
+                ++index;
+            }
+            continue;
+        }
+        if (isShortOptionGroup(arg)) {
+            // expend short option group (e.g. `-abc` => `-a -b -c`, `-f=bar` => `-f bar`)
+            const expanded = [];
+            let shortValue = '';
+            for (let i = 1; i < arg.length; i++) {
+                const shortableOption = arg.charAt(i);
+                if (hasShortValueSeparator) {
+                    shortValue += shortableOption;
+                }
+                else {
+                    if (!allowCompatible && shortableOption.codePointAt(0) === EQUAL_CODE) {
+                        hasShortValueSeparator = true;
+                    }
+                    else {
+                        expanded.push(`${SHORT_OPTION_PREFIX}${shortableOption}`);
+                    }
+                }
+            }
+            if (shortValue) {
+                expanded.push(shortValue);
+            }
+            remainings.unshift(...expanded);
+            groupCount = expanded.length;
+            continue;
+        }
+        if (isLongOption(arg)) {
+            // e.g. `--foo`
+            const longOption = arg.slice(2);
+            tokens.push({
+                kind: 'option',
+                name: longOption,
+                rawName: arg,
+                index,
+                value: undefined,
+                inlineValue: undefined
+            });
+            continue;
+        }
+        if (isLongOptionAndValue(arg)) {
+            // e.g. `--foo=bar`
+            const equalIndex = arg.indexOf(EQUAL_CHAR);
+            const longOption = arg.slice(2, equalIndex);
+            const value = arg.slice(equalIndex + 1);
+            tokens.push({
+                kind: 'option',
+                name: longOption,
+                rawName: `${LONG_OPTION_PREFIX}${longOption}`,
+                index,
+                value,
+                inlineValue: true
+            });
+            continue;
+        }
+        tokens.push({
+            kind: 'positional',
+            index,
+            value: arg
+        });
+    }
+    return tokens;
+}
+/**
+ * Check if `arg` is a short option (e.g. `-f`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a short option
+ */
+function isShortOption(arg) {
+    return (arg.length === 2 && arg.codePointAt(0) === HYPHEN_CODE && arg.codePointAt(1) !== HYPHEN_CODE);
+}
+/**
+ * Check if `arg` is a short option group (e.g. `-abc`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a short option group
+ */
+function isShortOptionGroup(arg) {
+    if (arg.length <= 2) {
+        return false;
+    }
+    if (arg.codePointAt(0) !== HYPHEN_CODE) {
+        return false;
+    }
+    if (arg.codePointAt(1) === HYPHEN_CODE) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if `arg` is a long option (e.g. `--foo`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a long option
+ */
+function isLongOption(arg) {
+    return hasLongOptionPrefix(arg) && !arg.includes(EQUAL_CHAR, 3);
+}
+/**
+ * Check if `arg` is a long option with value (e.g. `--foo=bar`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a long option
+ */
+function isLongOptionAndValue(arg) {
+    return hasLongOptionPrefix(arg) && arg.includes(EQUAL_CHAR, 3);
+}
+/**
+ * Check if `arg` is a long option prefix (e.g. `--`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a long option prefix
+ */
+function hasLongOptionPrefix(arg) {
+    return arg.length > 2 && ~arg.indexOf(LONG_OPTION_PREFIX);
+}
+/**
+ * Check if a `value` is an option value
+ * @param value a value to check
+ * @returns whether a `value` is an option value
+ */
+function hasOptionValue(value) {
+    // eslint-disable-next-line unicorn/no-null
+    return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
 }

package/lib/esm/index.d.ts

@@ -1 +1,27 @@
-export declare function add(a: number, b: number): number;
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+export interface ArgToken {
+    kind: ArgTokenKind;
+    index: number;
+    name?: string;
+    rawName?: string;
+    value?: string;
+    inlineValue?: boolean;
+}
+/**
+ * Parse Options
+ */
+export interface ParseOptions {
+    /**
+     * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode
+     * @default false
+     */
+    allowCompatible?: boolean;
+}
+/**
+ * Parse command line arguments
+ * @param args command line arguments
+ * @param options parse options
+ * @returns argument tokens
+ */
+export declare function parseArgs(args: string[], options?: ParseOptions): ArgToken[];
+export {};

package/lib/esm/index.js

@@ -1,3 +1,215 @@
-export function add(a, b) {
-    return a + b;
+// SPDX-License-Identifier: MIT
+// Modifier: kazuya kawaguchi (a.k.a. kazupon)
+// Forked from `nodejs/node` (`pkgjs/parseargs`)
+// Repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+// Author: Node.js contributors
+// Code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+const HYPHEN_CHAR = '-';
+const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
+const EQUAL_CHAR = '=';
+const EQUAL_CODE = EQUAL_CHAR.codePointAt(0);
+const TERMINATOR = '--';
+const SHORT_OPTION_PREFIX = HYPHEN_CHAR;
+const LONG_OPTION_PREFIX = '--';
+/**
+ * Parse command line arguments
+ * @param args command line arguments
+ * @param options parse options
+ * @returns argument tokens
+ */
+export function parseArgs(args, options = {}) {
+    const { allowCompatible = false } = options;
+    const tokens = [];
+    const remainings = [...args];
+    let index = -1;
+    let groupCount = 0;
+    let hasShortValueSeparator = false;
+    while (remainings.length > 0) {
+        const arg = remainings.shift();
+        if (arg == undefined) {
+            break;
+        }
+        const nextArg = remainings[0];
+        if (groupCount > 0) {
+            groupCount--;
+        }
+        else {
+            index++;
+        }
+        // check if `arg` is an options terminator.
+        // guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
+        if (arg === TERMINATOR) {
+            tokens.push({
+                kind: 'option-terminator',
+                index
+            });
+            const mapped = remainings.map(arg => {
+                return { kind: 'positional', index: ++index, value: arg };
+            });
+            tokens.push(...mapped);
+            break;
+        }
+        if (isShortOption(arg)) {
+            const shortOption = arg.charAt(1);
+            let value;
+            let inlineValue;
+            if (groupCount) {
+                // e.g. `-abc`
+                tokens.push({
+                    kind: 'option',
+                    name: shortOption,
+                    rawName: arg,
+                    index,
+                    value,
+                    inlineValue
+                });
+                if (groupCount === 1 && hasOptionValue(nextArg)) {
+                    value = remainings.shift();
+                    if (hasShortValueSeparator) {
+                        inlineValue = true;
+                        hasShortValueSeparator = false;
+                    }
+                    tokens.push({
+                        kind: 'option',
+                        index,
+                        value,
+                        inlineValue
+                    });
+                }
+            }
+            else {
+                // e.g. `-a`
+                tokens.push({
+                    kind: 'option',
+                    name: shortOption,
+                    rawName: arg,
+                    index,
+                    value,
+                    inlineValue
+                });
+            }
+            // eslint-disable-next-line unicorn/no-null
+            if (value != null) {
+                ++index;
+            }
+            continue;
+        }
+        if (isShortOptionGroup(arg)) {
+            // expend short option group (e.g. `-abc` => `-a -b -c`, `-f=bar` => `-f bar`)
+            const expanded = [];
+            let shortValue = '';
+            for (let i = 1; i < arg.length; i++) {
+                const shortableOption = arg.charAt(i);
+                if (hasShortValueSeparator) {
+                    shortValue += shortableOption;
+                }
+                else {
+                    if (!allowCompatible && shortableOption.codePointAt(0) === EQUAL_CODE) {
+                        hasShortValueSeparator = true;
+                    }
+                    else {
+                        expanded.push(`${SHORT_OPTION_PREFIX}${shortableOption}`);
+                    }
+                }
+            }
+            if (shortValue) {
+                expanded.push(shortValue);
+            }
+            remainings.unshift(...expanded);
+            groupCount = expanded.length;
+            continue;
+        }
+        if (isLongOption(arg)) {
+            // e.g. `--foo`
+            const longOption = arg.slice(2);
+            tokens.push({
+                kind: 'option',
+                name: longOption,
+                rawName: arg,
+                index,
+                value: undefined,
+                inlineValue: undefined
+            });
+            continue;
+        }
+        if (isLongOptionAndValue(arg)) {
+            // e.g. `--foo=bar`
+            const equalIndex = arg.indexOf(EQUAL_CHAR);
+            const longOption = arg.slice(2, equalIndex);
+            const value = arg.slice(equalIndex + 1);
+            tokens.push({
+                kind: 'option',
+                name: longOption,
+                rawName: `${LONG_OPTION_PREFIX}${longOption}`,
+                index,
+                value,
+                inlineValue: true
+            });
+            continue;
+        }
+        tokens.push({
+            kind: 'positional',
+            index,
+            value: arg
+        });
+    }
+    return tokens;
+}
+/**
+ * Check if `arg` is a short option (e.g. `-f`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a short option
+ */
+function isShortOption(arg) {
+    return (arg.length === 2 && arg.codePointAt(0) === HYPHEN_CODE && arg.codePointAt(1) !== HYPHEN_CODE);
+}
+/**
+ * Check if `arg` is a short option group (e.g. `-abc`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a short option group
+ */
+function isShortOptionGroup(arg) {
+    if (arg.length <= 2) {
+        return false;
+    }
+    if (arg.codePointAt(0) !== HYPHEN_CODE) {
+        return false;
+    }
+    if (arg.codePointAt(1) === HYPHEN_CODE) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if `arg` is a long option (e.g. `--foo`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a long option
+ */
+function isLongOption(arg) {
+    return hasLongOptionPrefix(arg) && !arg.includes(EQUAL_CHAR, 3);
+}
+/**
+ * Check if `arg` is a long option with value (e.g. `--foo=bar`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a long option
+ */
+function isLongOptionAndValue(arg) {
+    return hasLongOptionPrefix(arg) && arg.includes(EQUAL_CHAR, 3);
+}
+/**
+ * Check if `arg` is a long option prefix (e.g. `--`)
+ * @param arg the argument to check
+ * @returns whether `arg` is a long option prefix
+ */
+function hasLongOptionPrefix(arg) {
+    return arg.length > 2 && ~arg.indexOf(LONG_OPTION_PREFIX);
+}
+/**
+ * Check if a `value` is an option value
+ * @param value a value to check
+ * @returns whether a `value` is an option value
+ */
+function hasOptionValue(value) {
+    // eslint-disable-next-line unicorn/no-null
+    return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -28,6 +28,7 @@
   "engines": {
     "node": ">= 18.18"
   },
+  "type": "module",
   "files": [
     "lib"
   ],
@@ -70,6 +71,7 @@
     "gh-changelogen": "^0.2.8",
     "knip": "^5.44.0",
     "lint-staged": "^15.4.3",
+    "mitata": "^1.0.34",
     "pkg-pr-new": "^0.0.39",
     "prettier": "^3.5.0",
     "typescript": "^5.7.3",
@@ -91,6 +93,8 @@
     ]
   },
   "scripts": {
+    "bench:mitata": "node --expose-gc bench/index.mjs",
+    "bench:vitest": "vitest bench --run",
     "build": "pnpm run --parallel --color \"/^build:/\"",
     "build:cjs": "tsc -p ./tsconfig.cjs.json",
     "build:esm": "tsc -p ./tsconfig.esm.json",