args-tokens 0.3.2 → 0.4.1

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 { parse } 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 { ParsedArgs, ParseOptions } from './parse';
+export type { ArgToken, ParserOptions } from './parser';
+export type { ArgOptionSchema } from './resolver';

package/lib/cjs/index.js

@@ -1,20 +1,9 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-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 = exports.parse = void 0;
+var parse_js_1 = require("./parse.js");
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return parse_js_1.parse; } });
 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,40 @@
+import type { ParserOptions } from './parser';
+import type { ArgOptions, ArgValues } from './resolver';
+/**
+ * Parse options for {@link parse} function
+ */
+export interface ParseOptions<O extends ArgOptions> extends ParserOptions {
+    /**
+     * Command line options, about details see {@link ArgOptions}
+     */
+    options?: O;
+}
+/**
+ * Parsed command line arguments
+ */
+export 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>;

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

package/lib/esm/index.d.ts

@@ -1,3 +1,6 @@
+export { parse } 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 { ParsedArgs, ParseOptions } from './parse';
+export type { ArgToken, ParserOptions } from './parser';
+export type { ArgOptionSchema } from './resolver';

package/lib/esm/index.js

@@ -1,2 +1,3 @@
+export { parse } 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,40 @@
+import type { ParserOptions } from './parser';
+import type { ArgOptions, ArgValues } from './resolver';
+/**
+ * Parse options for {@link parse} function
+ */
+export interface ParseOptions<O extends ArgOptions> extends ParserOptions {
+    /**
+     * Command line options, about details see {@link ArgOptions}
+     */
+    options?: O;
+}
+/**
+ * Parsed command line arguments
+ */
+export 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>;

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "args-tokens",
   "description": "parseArgs tokens compatibility and more high-performance parser",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -106,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",