args-tokens 0.2.5 → 0.3.0

package/lib/esm/parser.js

@@ -0,0 +1,225 @@
+// 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
+ * @example
+ * ```js
+ * import { parseArgs } from 'args-tokens' // for Node.js and Bun
+ * // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
+ *
+ * const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
+ * // do something with using tokens
+ * // ...
+ * console.log('tokens:', tokens)
+ * ```
+ * @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
+ */
+export 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
+ */
+export 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/resolver.d.ts

@@ -0,0 +1,50 @@
+import type { ArgToken } from './parser';
+/**
+ * An option schema for an argument.
+ */
+export interface ArgOptionSchema {
+    /**
+     * Type of argument.
+     */
+    type: 'string' | 'boolean' | 'number';
+    /**
+     * A single character alias for the option.
+     */
+    short?: string;
+    /**
+     * Whether the argument is required or not.
+     */
+    required?: true;
+    /**
+     * The default value of the argument.
+     */
+    default?: string | boolean | number;
+}
+/**
+ * An object that contains {@link ArgOptionSchema | options schema}.
+ */
+export interface ArgOptions {
+    [option: string]: ArgOptionSchema;
+}
+/**
+ * An object that contains the values of the arguments.
+ */
+export type ArgValues<T> = T extends ArgOptions ? ResolveArgValues<T, {
+    [Option in keyof T]: ExtractOptionValue<T[Option]>;
+}> : {
+    [option: string]: string | boolean | number | undefined;
+};
+type ExtractOptionValue<O extends ArgOptionSchema> = O['type'] extends 'string' ? string : O['type'] extends 'boolean' ? boolean : O['type'] extends 'number' ? number : string | boolean | number;
+type ResolveArgValues<O extends ArgOptions, V extends Record<keyof O, unknown>> = {
+    -readonly [Option in keyof O]?: V[Option];
+} & FilterArgs<O, V, 'default'> & FilterArgs<O, V, 'required'> extends infer P ? {
+    [K in keyof P]: P[K];
+} : never;
+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];
+};
+export declare function resolveArgs<T extends ArgOptions>(options: T, tokens: ArgToken[]): {
+    values: ArgValues<T>;
+    positionals: string[];
+};
+export {};

package/lib/esm/resolver.js

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: MIT
+// Modifier: kazuya kawaguchi (a.k.a. kazupon)
+import { hasLongOptionPrefix, isShortOption } from './parser.js';
+export function resolveArgs(options, tokens) {
+    const values = {};
+    const positionals = [];
+    const longOptionTokens = [];
+    const shortOptionTokens = [];
+    let currentShortOption;
+    const expandableShortOptions = [];
+    function toValue() {
+        if (expandableShortOptions.length === 0) {
+            return undefined;
+        }
+        else {
+            const value = expandableShortOptions.map(token => token.name).join('');
+            expandableShortOptions.length = 0;
+            return value;
+        }
+    }
+    function applyShortOptionValue() {
+        if (currentShortOption) {
+            currentShortOption.value = toValue();
+            shortOptionTokens.push({ ...currentShortOption });
+            currentShortOption = undefined;
+        }
+    }
+    /**
+     * separate tokens into positionals, long options, and short options, after that resolve values
+     */
+    // eslint-disable-next-line unicorn/no-for-loop
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.kind === 'positional') {
+            positionals.push(token.value);
+            applyShortOptionValue(); // check if previous short option is not resolved
+        }
+        else if (token.kind === 'option') {
+            if (token.rawName) {
+                if (hasLongOptionPrefix(token.rawName)) {
+                    longOptionTokens.push({ ...token });
+                    applyShortOptionValue(); // check if previous short option is not resolved
+                }
+                else if (isShortOption(token.rawName)) {
+                    if (currentShortOption) {
+                        if (currentShortOption.index === token.index) {
+                            expandableShortOptions.push({ ...token });
+                        }
+                        else {
+                            currentShortOption.value = toValue();
+                            shortOptionTokens.push({ ...currentShortOption });
+                            currentShortOption = { ...token };
+                        }
+                    }
+                    else {
+                        currentShortOption = { ...token };
+                    }
+                }
+            }
+            else {
+                // short option value
+                if (currentShortOption && currentShortOption.index == token.index) {
+                    currentShortOption.value = token.value;
+                    shortOptionTokens.push({ ...currentShortOption });
+                    currentShortOption = undefined;
+                }
+            }
+        }
+        else {
+            applyShortOptionValue(); // check if previous short option is not resolved
+        }
+    }
+    /**
+     * check if the last short option is not resolved
+     */
+    applyShortOptionValue();
+    /**
+     * resolve values
+     */
+    for (const [option, schema] of Object.entries(options)) {
+        if (longOptionTokens.length === 0 && shortOptionTokens.length === 0 && schema.required) {
+            throw createRequireError(option, schema);
+        }
+        // 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);
+                if (schema.type !== 'boolean') {
+                    validateValue(token, option, schema);
+                }
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                ;
+                values[option] = resolveOptionValue(token, schema);
+                continue;
+            }
+        }
+        // eslint-disable-next-line unicorn/no-for-loop
+        for (let i = 0; i < shortOptionTokens.length; i++) {
+            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);
+                if (schema.type !== 'boolean') {
+                    validateValue(token, option, schema);
+                }
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                ;
+                values[option] = resolveOptionValue(token, schema);
+                continue;
+            }
+        }
+        // eslint-disable-next-line unicorn/no-null
+        if (values[option] == null && schema.default != null) {
+            // check if the default value is in values
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+            ;
+            values[option] = schema.default;
+        }
+    }
+    return { values, positionals };
+}
+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);
+    }
+}
+function validateValue(token, option, schema) {
+    switch (schema.type) {
+        case 'number': {
+            if (!isNumeric(token.value)) {
+                throw createTypeError(option, schema);
+            }
+            break;
+        }
+        case 'string': {
+            if (typeof token.value !== 'string') {
+                throw createTypeError(option, schema);
+            }
+            break;
+        }
+    }
+}
+function isNumeric(str) {
+    // @ts-ignore
+    // eslint-disable-next-line unicorn/prefer-number-properties
+    return str.trim() !== '' && !isNaN(str);
+}
+function createTypeError(option, schema) {
+    return new TypeError(`Option '--${option}' ${schema.short ? `or '-${schema.short}'` : ''} should be '${schema.type}'`);
+}
+function resolveOptionValue(token, schema) {
+    if (token.value) {
+        return schema.type === 'number' ? +token.value : token.value;
+    }
+    if (schema.type === 'boolean') {
+        return true;
+    }
+    return schema.type === 'number' ? +(schema.default || '') : schema.default;
+}

package/lib/esm/resolver.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/esm/resolver.test-d.js

@@ -0,0 +1,4 @@
+import { expectTypeOf, test } from 'vitest';
+test('ArgValues', () => {
+    expectTypeOf().toEqualTypeOf();
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -41,6 +41,18 @@
       "require": "./lib/cjs/index.js",
       "default": "./lib/cjs/index.js"
     },
+    "./parser": {
+      "types": "./lib/cjs/parser.d.ts",
+      "import": "./lib/esm/parser.js",
+      "require": "./lib/cjs/parser.js",
+      "default": "./lib/cjs/parser.js"
+    },
+    "./resolver": {
+      "types": "./lib/cjs/resolver.d.ts",
+      "import": "./lib/esm/resolver.js",
+      "require": "./lib/cjs/resolver.js",
+      "default": "./lib/cjs/resolver.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -93,7 +105,7 @@
     ]
   },
   "scripts": {
-    "bench:mitata": "node --expose-gc bench/index.mjs",
+    "bench:mitata": "node --expose-gc bench/index.js",
     "bench:vitest": "vitest bench --run",
     "build": "pnpm run --parallel --color \"/^build:/\"",
     "build:cjs": "tsc -p ./tsconfig.cjs.json",