args-tokens 0.3.1 → 0.4.0

package/README.md

@@ -153,6 +153,10 @@ bun add args-tokens
 
 ## 🚀 Usage
 
+### Parse args to tokens
+
+`parseArgs` will transform arguments into tokens. This function is useful if you want to analyze arguments yourself based on the tokens. It's faster than `node:util` parseArgs because it only focuses on token transformation.
+
 ```js
 import { parseArgs } from 'args-tokens' // for Node.js and Bun
 // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
@@ -163,6 +167,86 @@ const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
 console.log('tokens:', tokens)
 ```
 
+## Resolve args value with tokens and arg option schema
+
+`resolveArgs` is a useful function when you want to resolve values from the tokens obtained by `parseArgs`.
+
+```js
+import { parseArgs, resolveArgs } from 'args-tokens' // for Node.js and Bun
+// import { parseArgs, resolveArgs } from 'jsr:@kazupon/args-tokens' // for Deno
+
+const args = ['dev', '-p=9131', '--host=example.com', '--mode=production']
+const tokens = parseArgs(args)
+const { values, positionals } = resolveArgs(
+  {
+    help: {
+      type: 'boolean',
+      short: 'h'
+    },
+    version: {
+      type: 'boolean',
+      short: 'v'
+    },
+    port: {
+      type: 'number',
+      short: 'p',
+      default: 8080
+    },
+    mode: {
+      type: 'string',
+      short: 'm'
+    },
+    host: {
+      type: 'string',
+      short: 'o',
+      required: true
+    }
+  },
+  tokens
+)
+console.log('values:', values)
+console.log('positionals:', positionals)
+```
+
+## Convenient argument parsing
+
+Using the `parse,` you can transform the arguments into tokens and resolve the argument values once:
+
+```js
+import { parse } from 'args-tokens' // for Node.js and Bun
+// import { parse } from 'jsr:@kazupon/args-tokens' // for Deno
+
+const args = ['dev', '-p=9131', '--host=example.com', '--mode=production']
+const { values, positionals } = parse(args, {
+  options: {
+    help: {
+      type: 'boolean',
+      short: 'h'
+    },
+    version: {
+      type: 'boolean',
+      short: 'v'
+    },
+    port: {
+      type: 'number',
+      short: 'p',
+      default: 8080
+    },
+    mode: {
+      type: 'string',
+      short: 'm'
+    },
+    host: {
+      type: 'string',
+      short: 'o',
+      required: true
+    }
+  }
+})
+console.log('values:', values)
+console.log('positionals:', positionals)
+```
+
 ## 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`:

package/lib/cjs/index.d.ts

@@ -1,3 +1,6 @@
+export * from './parse.js';
 export { parseArgs } from './parser.js';
-export * from './resolver.js';
-export type { ArgToken, ParseOptions } from './parser';
+export { resolveArgs } from './resolver.js';
+export type * from './parse';
+export type { ArgToken, ParserOptions } from './parser';
+export type { ArgOptionSchema } from './resolver';

package/lib/cjs/index.js

@@ -14,7 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseArgs = void 0;
+exports.resolveArgs = exports.parseArgs = void 0;
+__exportStar(require("./parse.js"), exports);
 var parser_js_1 = require("./parser.js");
 Object.defineProperty(exports, "parseArgs", { enumerable: true, get: function () { return parser_js_1.parseArgs; } });
-__exportStar(require("./resolver.js"), exports);
+var resolver_js_1 = require("./resolver.js");
+Object.defineProperty(exports, "resolveArgs", { enumerable: true, get: function () { return resolver_js_1.resolveArgs; } });

package/lib/cjs/parse.d.ts

@@ -0,0 +1,41 @@
+import type { ParserOptions } from './parser';
+import type { ArgOptions, ArgValues } from './resolver';
+/**
+ * Parse options for {@link parse} function
+ */
+interface ParseOptions<O extends ArgOptions> extends ParserOptions {
+    /**
+     * Command line options, about details see {@link ArgOptions}
+     */
+    options?: O;
+}
+/**
+ * Parsed command line arguments
+ */
+type ParsedArgs<T extends ArgOptions> = {
+    /**
+     * Parsed values, same as `values` in {@link resolveArgs}
+     */
+    values: ArgValues<T>;
+    /**
+     * Positional arguments, same as `positionals` in {@link resolveArgs}
+     */
+    positionals: string[];
+};
+/**
+ * Parse command line arguments
+ * @description This function is a convenient API, that is used {@link parseArgs} and {@link resolveArgs} in internal.
+ * @example
+ * ```js
+ * import { parse } from 'args-tokens'
+ *
+ * const { values, positionals } = parse(process.argv.slice(2))
+ * 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
+ */
+export declare function parse<O extends ArgOptions>(args: string[], options?: ParseOptions<O>): ParsedArgs<O>;
+export {};

package/lib/cjs/parse.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+const parser_js_1 = require("./parser.js");
+const resolver_js_1 = require("./resolver.js");
+const DEFAULT_OPTIONS = {
+    help: {
+        type: 'boolean',
+        short: 'h'
+    },
+    version: {
+        type: 'boolean',
+        short: 'v'
+    }
+};
+/**
+ * Parse command line arguments
+ * @description This function is a convenient API, that is used {@link parseArgs} and {@link resolveArgs} in internal.
+ * @example
+ * ```js
+ * import { parse } from 'args-tokens'
+ *
+ * const { values, positionals } = parse(process.argv.slice(2))
+ * 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
+ */
+function parse(args, options = {}) {
+    const { options: argOptions, allowCompatible = false } = options;
+    const tokens = (0, parser_js_1.parseArgs)(args, { allowCompatible });
+    return (0, resolver_js_1.resolveArgs)(argOptions || DEFAULT_OPTIONS, tokens);
+}

package/lib/cjs/parser.d.ts

@@ -36,9 +36,9 @@ export interface ArgToken {
     inlineValue?: boolean;
 }
 /**
- * Parse Options
+ * Parser Options
  */
-export interface ParseOptions {
+export interface ParserOptions {
     /**
      * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode
      * @default false
@@ -61,7 +61,7 @@ export interface ParseOptions {
  * @param options parse options
  * @returns argument tokens
  */
-export declare function parseArgs(args: string[], options?: ParseOptions): ArgToken[];
+export declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
 /**
  * Check if `arg` is a short option (e.g. `-f`)
  * @param arg the argument to check
@@ -73,5 +73,5 @@ export declare function isShortOption(arg: string): boolean;
  * @param arg the argument to check
  * @returns whether `arg` is a long option prefix
  */
-export declare function hasLongOptionPrefix(arg: string): number | false;
+export declare function hasLongOptionPrefix(arg: string): boolean;
 export {};

package/lib/cjs/parser.js

@@ -217,6 +217,7 @@ function isLongOptionAndValue(arg) {
  * @returns whether `arg` is a long option prefix
  */
 function hasLongOptionPrefix(arg) {
+    // @ts-ignore -- NOTE: `~` is a bitwise NOT operator
     return arg.length > 2 && ~arg.indexOf(LONG_OPTION_PREFIX);
 }
 /**

package/lib/esm/index.d.ts

@@ -1,3 +1,6 @@
+export * from './parse.js';
 export { parseArgs } from './parser.js';
-export * from './resolver.js';
-export type { ArgToken, ParseOptions } from './parser';
+export { resolveArgs } from './resolver.js';
+export type * from './parse';
+export type { ArgToken, ParserOptions } from './parser';
+export type { ArgOptionSchema } from './resolver';

package/lib/esm/index.js

@@ -1,2 +1,3 @@
+export * from './parse.js';
 export { parseArgs } from './parser.js';
-export * from './resolver.js';
+export { resolveArgs } from './resolver.js';

package/lib/esm/parse.d.ts

@@ -0,0 +1,41 @@
+import type { ParserOptions } from './parser';
+import type { ArgOptions, ArgValues } from './resolver';
+/**
+ * Parse options for {@link parse} function
+ */
+interface ParseOptions<O extends ArgOptions> extends ParserOptions {
+    /**
+     * Command line options, about details see {@link ArgOptions}
+     */
+    options?: O;
+}
+/**
+ * Parsed command line arguments
+ */
+type ParsedArgs<T extends ArgOptions> = {
+    /**
+     * Parsed values, same as `values` in {@link resolveArgs}
+     */
+    values: ArgValues<T>;
+    /**
+     * Positional arguments, same as `positionals` in {@link resolveArgs}
+     */
+    positionals: string[];
+};
+/**
+ * Parse command line arguments
+ * @description This function is a convenient API, that is used {@link parseArgs} and {@link resolveArgs} in internal.
+ * @example
+ * ```js
+ * import { parse } from 'args-tokens'
+ *
+ * const { values, positionals } = parse(process.argv.slice(2))
+ * 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
+ */
+export declare function parse<O extends ArgOptions>(args: string[], options?: ParseOptions<O>): ParsedArgs<O>;
+export {};

package/lib/esm/parse.js

@@ -0,0 +1,32 @@
+import { parseArgs } from './parser.js';
+import { resolveArgs } from './resolver.js';
+const DEFAULT_OPTIONS = {
+    help: {
+        type: 'boolean',
+        short: 'h'
+    },
+    version: {
+        type: 'boolean',
+        short: 'v'
+    }
+};
+/**
+ * Parse command line arguments
+ * @description This function is a convenient API, that is used {@link parseArgs} and {@link resolveArgs} in internal.
+ * @example
+ * ```js
+ * import { parse } from 'args-tokens'
+ *
+ * const { values, positionals } = parse(process.argv.slice(2))
+ * 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
+ */
+export function parse(args, options = {}) {
+    const { options: argOptions, allowCompatible = false } = options;
+    const tokens = parseArgs(args, { allowCompatible });
+    return resolveArgs(argOptions || DEFAULT_OPTIONS, tokens);
+}

package/lib/esm/parser.d.ts

@@ -36,9 +36,9 @@ export interface ArgToken {
     inlineValue?: boolean;
 }
 /**
- * Parse Options
+ * Parser Options
  */
-export interface ParseOptions {
+export interface ParserOptions {
     /**
      * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode
      * @default false
@@ -61,7 +61,7 @@ export interface ParseOptions {
  * @param options parse options
  * @returns argument tokens
  */
-export declare function parseArgs(args: string[], options?: ParseOptions): ArgToken[];
+export declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
 /**
  * Check if `arg` is a short option (e.g. `-f`)
  * @param arg the argument to check
@@ -73,5 +73,5 @@ export declare function isShortOption(arg: string): boolean;
  * @param arg the argument to check
  * @returns whether `arg` is a long option prefix
  */
-export declare function hasLongOptionPrefix(arg: string): number | false;
+export declare function hasLongOptionPrefix(arg: string): boolean;
 export {};

package/lib/esm/parser.js

@@ -212,6 +212,7 @@ function isLongOptionAndValue(arg) {
  * @returns whether `arg` is a long option prefix
  */
 export function hasLongOptionPrefix(arg) {
+    // @ts-ignore -- NOTE: `~` is a bitwise NOT operator
     return arg.length > 2 && ~arg.indexOf(LONG_OPTION_PREFIX);
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -81,6 +81,7 @@
     "eslint-plugin-unicorn": "^56.0.1",
     "eslint-plugin-yml": "^1.16.0",
     "gh-changelogen": "^0.2.8",
+    "jsr": "^0.13.3",
     "knip": "^5.44.0",
     "lint-staged": "^15.4.3",
     "mitata": "^1.0.34",
@@ -105,7 +106,7 @@
     ]
   },
   "scripts": {
-    "bench:mitata": "node --expose-gc bench/index.js",
+    "bench:mitata": "node --expose-gc bench/mitata.js",
     "bench:vitest": "vitest bench --run",
     "build": "pnpm run --parallel --color \"/^build:/\"",
     "build:cjs": "tsc -p ./tsconfig.cjs.json",
@@ -119,6 +120,7 @@
     "fix:prettier": "prettier . --write",
     "lint": "pnpm run --parallel --color \"/^lint:/\"",
     "lint:eslint": "eslint .",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
     "lint:knip": "knip",
     "lint:prettier": "prettier . --check",
     "release": "bumpp --commit \"release: v%s\" --all --push --tag",