feat: add new options (#2)

Author: ivodolenc

README.md

@@ -5,7 +5,7 @@ A fast and ultra lightweight CLI argument parser.
 <sub><a href="https://github.com/hypernym-studio/args">Repository</a> | <a href="https://www.npmjs.com/package/@hypernym/args">Package</a> | <a href="https://github.com/hypernym-studio/args/releases">Releases</a> | <a href="https://github.com/hypernym-studio/args/discussions">Discussions</a></sub>
 
 ```sh
-npm i @hypernym/args
+pnpm add @hypernym/args
 ```
 
 ## Features
@@ -50,6 +50,12 @@ $ --flag value
 # => { _: [], flag: 'value', }
 ```
 
+```sh
+$ --flag=value
+
+# => { _: [], flag: 'value', }
+```
+
 ### Aliases
 
 Inputs with `-` prefix are parsed as _aliases_.
@@ -68,13 +74,19 @@ $ -alias value
 # => { _: [], alias: 'value', }
 ```
 
+```sh
+$ -alias=value
+
+# => { _: [], alias: 'value', }
+```
+
 ### Ignores
 
 - Ignores standalone inputs `--` and `-`
-- Ignores all inputs that include `=`
+- Ignores argument inputs that include `=`
 
 ```sh
-$ --flag=value -- arg=value - -alias=value
+$ arg=value -- arg-b=value -
 
 # => { _: [] }
 ```
@@ -99,7 +111,7 @@ const args = createArgs<Args>()
 
 console.log(args)
 
-/* Output:
+/*
 {
   _: ['hello', 'world'],
   foo: 'bar',
@@ -114,37 +126,78 @@ console.log(args)
 
 ### argv
 
-- Type: `string[]`
+Specifies an array of values to parse as arguments.
+
+- Type: `string[] | undefined`
 - Default: `process.argv.slice(2)`
 
 ```ts
-const args = createArgs({
+import { createArgs } from '@hypernym/args'
+
+createArgs({
   argv: process.argv.slice(2),
 })
 ```
 
 ### alias
 
-- Type: `object`
+Specifies an object of `alias` that will be added to the parsed output with matching values.
+
+- Type: `Record<string, string | string[]> | undefined`
 - Default: `undefined`
 
 ```ts
-const args = createArgs({
+import { createArgs } from '@hypernym/args'
+
+createArgs({
   alias: {
     config: ['conf', 'c'],
     help: 'h',
   },
 })
 ```
 
+### defaults
+
+Specifies an object of `defaults` that will be added to the parsed output regardless of `CLI` inputs.
+
+- Type: `(Record<string, unknown> & { _?: string[] }) | undefined`
+- Default: `undefined`
+
+```ts
+import { createArgs } from '@hypernym/args'
+
+createArgs({
+  defaults: {
+    _: ['value'],
+    a: true,
+  },
+})
+```
+
+### exclude
+
+Specifies an array of values that will be skipped when parsing arguments.
+
+- Type: `string[] | undefined`
+- Default: `undefined`
+
+```ts
+import { createArgs } from '@hypernym/args'
+
+createArgs({
+  exclude: ['arg', '--flag', '-alias'],
+})
+```
+
 ## Community
 
-Feel free to use the official [discussions](https://github.com/hypernym-studio/args/discussions) for any additional questions.
+Feel free to ask questions or share new ideas.
+
+Use the official [discussions](https://github.com/hypernym-studio/args/discussions) to get involved.
 
 ## License
 
-Developed in 🇭🇷 Croatia
+Developed in 🇭🇷 Croatia, © Hypernym Studio.
 
 Released under the [MIT](LICENSE.txt) license.
-
-© Hypernym Studio

src/index.ts

@@ -1,11 +1,11 @@
-// Inspired by mri, https://github.com/lukeed/mri 1.2.0 MIT
-// Rewritten in TypeScript by Ivo Dolenc, Hypernym Studio
+// Inspired by mri, 1.2.0, MIT License, https://github.com/lukeed/mri
+// Rewritten and adapted to @hypernym/args, 0.3.0, MIT License, https://github.com/hypernym-studio/args
 
-import { isString, isArray, isFlag, isAlias } from './utils.js'
-import type { Defaults, Args, Options } from './types/index.js'
+import { isString, isArray, isFlag, isAlias } from './utils'
+import type { Defaults, Args, Options } from './types'
 
 /**
- * Creates a command-line argument parser for the Node process.
+ * Creates a command-line argument parser.
  *
  * @example
  *
@@ -24,53 +24,70 @@ import type { Defaults, Args, Options } from './types/index.js'
 export function createArgs<T = Defaults>({
   argv = process.argv.slice(2),
   alias,
+  defaults,
+  exclude,
 }: Options = {}): Args<T> {
   const args: Args = {
     _: [],
   }
 
-  function _setArg(arg: string, index: number) {
+  const excludes = ['--', '-', ...(exclude || [])]
+  argv = argv.filter((arg) => !excludes.includes(arg))
+
+  function setArg(arg: string, index: number) {
     let value: boolean | string = true
-    const argKey = isFlag(arg) ? arg.slice(2) : arg.slice(1)
-    const argValue = argv[index + 1]
+    let argKey: string = isFlag(arg) ? arg.slice(2) : arg.slice(1)
+    let argValue: string
+
+    if (arg.includes('=')) {
+      const split = argKey.split('=')
+      argKey = split[0]
+      argValue = split[1]
+    } else {
+      argValue = argv[index + 1]
+    }
 
     if (argValue && !argValue.startsWith('-')) value = argValue
 
-    if (argKey && !argKey.includes('=')) {
-      if (alias) {
-        for (const [aliasKey, aliasValue] of Object.entries(alias)) {
-          if (aliasKey.includes(argKey) || aliasValue.includes(argKey)) {
-            args[aliasKey] = value
-            if (isString(aliasValue)) args[aliasValue] = value
-            if (isArray(aliasValue)) for (const v of aliasValue) args[v] = value
-          }
+    if (alias) {
+      for (const [aliasKey, aliasValue] of Object.entries(alias)) {
+        if (aliasKey.includes(argKey) || aliasValue.includes(argKey)) {
+          args[aliasKey] = value
+          if (isString(aliasValue)) args[aliasValue] = value
+          if (isArray(aliasValue)) for (const v of aliasValue) args[v] = value
+          return
         }
       }
-
-      args[argKey] = value
     }
+
+    args[argKey] = value
   }
 
-  for (const [index, arg] of argv.entries()) {
-    // flags '--'
-    if (isFlag(arg)) _setArg(arg, index)
-    // aliases '-'
-    else if (isAlias(arg)) _setArg(arg, index)
-    // unprefixed values
+  for (let i = 0, l = argv.length; i < l; i++) {
+    const arg = argv[i]
+
+    // '--flags' and '-alias'
+    if (isFlag(arg) || isAlias(arg)) setArg(arg, i)
+    // 'arguments' (unprefixed)
     else {
-      const _arg = argv[index - 1]
+      const prevArg: string | undefined = argv[i - 1]
 
-      if (!_arg) {
-        if (!arg.startsWith('-') && !arg.includes('=')) {
-          args._.push(arg)
+      if (!prevArg) {
+        if (!arg.includes('=')) args._.push(arg)
+      } else if (prevArg) {
+        if (!prevArg.startsWith('-') || prevArg.includes('=')) {
+          if (!arg.includes('=')) args._.push(arg)
         }
-      } else if (!_arg.startsWith('-') && !arg.includes('=')) {
-        args._.push(arg)
-      } else if ((_arg === '-' || _arg === '--') && !arg.includes('=')) {
-        args._.push(arg)
       }
     }
   }
 
+  if (defaults) {
+    if (defaults._) args._ = [...defaults._, ...args._]
+    for (const [dKey, dValue] of Object.entries(defaults)) {
+      if (dKey !== '_') args[dKey] = dValue
+    }
+  }
+
   return args as Args<T>
 }

src/types/index.ts

@@ -5,9 +5,78 @@ export type Args<T = Defaults> = T & {
 }
 
 export interface Options {
+  /**
+   * Specifies an array of values to parse as arguments.
+   *
+   * @default process.argv.slice(2)
+   *
+   * @example
+   *
+   * ```ts
+   * import { createArgs } from '@hypernym/args'
+   *
+   * createArgs({
+   *   argv: process.argv.slice(2),
+   * })
+   * ```
+   */
   argv?: string[]
+  /**
+   * Specifies an `alias` object that will be added to the parsed output with matching values.
+   *
+   * @default undefined
+   *
+   * @example
+   *
+   * ```ts
+   * import { createArgs } from '@hypernym/args'
+   *
+   * createArgs({
+   *   alias: {
+   *     config: ['conf', 'c'],
+   *     help: 'h',
+   *   },
+   * })
+   * ```
+   */
   alias?: Record<string, string | string[]>
+  /**
+   * Specifies an `defaults` object that will be added to the parsed output regardless of `CLI` inputs.
+   *
+   * @default undefined
+   *
+   * @example
+   *
+   * ```ts
+   * import { createArgs } from '@hypernym/args'
+   *
+   * createArgs({
+   *   defaults: {
+   *     _: ['value'],
+   *     a: true,
+   *   }
+   * })
+   * ```
+   */
+  defaults?: Defaults & {
+    _?: string[]
+  }
+  /**
+   * Specifies an array of values that will be skipped when parsing arguments.
+   *
+   * @default undefined
+   *
+   * @example
+   *
+   * ```ts
+   * import { createArgs } from '@hypernym/args'
+   *
+   * createArgs({
+   *   exclude: ['arg', '--flag', '-alias'],
+   * })
+   * ```
+   */
+  exclude?: string[]
 }
 
-// Auto-generated
-export * from '../index.js'
+export * from '@'

test/alias.test.ts

@@ -0,0 +1,23 @@
+import { test, expect } from 'vitest'
+import { createArgs } from '@'
+
+test('args-alias', () => {
+  interface ArgsAlias {
+    a?: string
+    b?: string
+    c?: boolean
+    d?: boolean
+  }
+
+  const argsAlias = createArgs<ArgsAlias>({
+    argv: ['-a=value', '-b', 'value', '-c', '-d'],
+  })
+
+  expect(argsAlias).toStrictEqual({
+    _: [],
+    a: 'value',
+    b: 'value',
+    c: true,
+    d: true,
+  })
+})