v1.0.0

.eslintignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+.coverage

.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["./node_modules/@adhamu/zero/eslint/typescript"]
+}

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on: push
+
+jobs:
+  pipeline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Set Environment Variables
+        run: |
+          echo ::set-output name=NODE_VERSION::$(cat .nvmrc)
+          echo ::set-output name=PACKAGE_VERSION::$(cat package.json | jq -r '.version')
+          echo ::set-output name=BRANCH::${GITHUB_REF##*/}
+        id: env_vars
+
+      - name: Install Node.js ${{ steps.env_vars.outputs.NODE_VERSION }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ steps.nvm.outputs.NODE_VERSION }}
+          registry-url: "https://registry.npmjs.org"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Cache node_modules
+        uses: actions/cache@v2
+        with:
+          path: "**/node_modules"
+          key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}
+
+      - name: Install dependencies
+        run: yarn --frozen-lockfile
+
+      - name: Security Audit
+        run: yarn audit || true
+
+      - name: Outdated Packages
+        run: yarn outdated || true
+
+      - name: Coding Standards
+        run: yarn lint
+
+      - name: Test
+        run: yarn test:coverage
+
+      - name: Type
+        run: yarn type
+
+      - name: Build
+        run: yarn build
+
+      - name: Publish to Registry
+        run: |
+          pkg_version=${{ steps.env_vars.outputs.PACKAGE_VERSION }}
+          branch=${{ steps.env_vars.outputs.BRANCH }}
+
+          if [[ $branch != "main" ]]; then
+            yarn version --new-version "$pkg_version-beta$GITHUB_RUN_NUMBER" --no-git-tag-version
+            yarn publish --tag beta --access public
+          else
+            yarn publish --access public
+          fi

.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+.coverage

.nvmrc

@@ -0,0 +1 @@
+16.14

.prettierrc.yaml

@@ -0,0 +1 @@
+"@adhamu/zero/prettier"

LICENSE

@@ -0,0 +1,19 @@
+Copyright 2022 Amit Dhamu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,76 @@
+# Arge
+
+A tiny package to parse CLI flags and arguments into an object.
+
+## Requirements
+
+- Node 16+
+
+## Installation
+
+```shell
+yarn add arge
+```
+
+## Usage
+
+```typescript
+import { arge } from 'arge'
+
+const args = arge(process.argv)
+```
+
+This will return arguments parsed from `process.argv` like this:
+
+```shell
+node app.js --dry-run --mode=development --test=false --retries=100
+```
+
+...into an object similar to below:
+
+```json
+{
+  "dry-run": true,
+  "mode": "development",
+  "test": false,
+  "retries": 100
+}
+```
+
+By default, the `arge` function assumes that you have passed `process.argv`. It does this because:
+
+> The first element will be process.execPath.
+
+> The second element will be the path to the JavaScript file being executed
+
+https://nodejs.org/docs/latest/api/process.html#processargv
+
+This package will omit those two items from the output.
+
+If you wanted to pass an arbitrary array of flags that don't come from `process.argv`, you can set the second argument of `arge` to `false`.
+
+For example
+
+```typescript
+import { arge } from 'arge'
+
+const flags = [
+  '--dry-run',
+  '--mode=development',
+  '--test=false',
+  '--retries=100',
+]
+
+const args = arge(flags, false)
+```
+
+This would then output:
+
+```json
+{
+  "dry-run": true,
+  "mode": "development",
+  "test": false,
+  "retries": 100
+}
+```

esbuild.config.js

@@ -0,0 +1,23 @@
+const { build } = require('esbuild')
+
+const options = {
+  bundle: true,
+  sourcemap: false,
+  entryPoints: ['./src/index.ts'],
+  external: Object.keys(require('./package.json').dependencies || {}),
+  logLevel: 'info',
+  minify: true,
+  target: ['esnext'],
+}
+
+build({
+  ...options,
+  format: 'esm',
+  outfile: './dist/index.esm.js',
+})
+
+build({
+  ...options,
+  format: 'cjs',
+  outfile: './dist/index.js',
+})

jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  ...require('@adhamu/zero/jest'),
+  transform: { '^.+\\.ts(x)?$': '@swc/jest' },
+}

package.json

@@ -0,0 +1,46 @@
+{
+  "name": "arge",
+  "version": "1.0.0",
+  "description": "A simple utility to parse command line arguments and flags",
+  "keywords": [
+    "argv",
+    "argparse",
+    "cli",
+    "command line",
+    "flags",
+    "parse",
+    "process.argv",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adhamu/arge"
+  },
+  "license": "MIT",
+  "author": "Amit Dhamu <[email protected]>",
+  "main": "./dist/index.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "npx rimraf dist",
+    "build": "node esbuild.config.js build",
+    "postbuild": "tsc --project tsconfig.build.json",
+    "lint": "eslint 'src/**/*.ts*' --ignore-path=.eslintignore --config=.eslintrc.json",
+    "test": "jest --colors",
+    "test:coverage": "yarn test --coverage",
+    "type": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@adhamu/zero": "^4.3.1",
+    "@swc/core": "^1.2.175",
+    "@swc/jest": "^0.2.20",
+    "@types/jest": "^27.5.0",
+    "@types/node": "^17.0.31",
+    "esbuild": "^0.14.38",
+    "jest": "^28.0.3",
+    "typescript": "^4.6.4"
+  }
+}

src/__tests__/index.test.ts

@@ -0,0 +1,48 @@
+import { arge } from '..'
+
+describe('arge', () => {
+  const baseArgs = ['node', 'app.js']
+
+  it('parses simple arguments', () => {
+    const argv = [
+      ...baseArgs,
+      '-f',
+      '--dry-run',
+      '--mode=development',
+      '--test=false',
+      '--retries=100',
+    ]
+
+    expect(arge(argv)).toEqual({
+      f: true,
+      'dry-run': true,
+      mode: 'development',
+      retries: 100,
+      test: false,
+    })
+  })
+
+  it('converts comma separated values to an array', () => {
+    const argv = [...baseArgs, '--colors=red, blue,green']
+
+    expect(arge(argv)).toEqual({
+      colors: ['red', 'blue', 'green'],
+    })
+  })
+
+  it('converts space separated values to an array', () => {
+    const argv = [...baseArgs, '--colors=red  blue green']
+
+    expect(arge(argv)).toEqual({
+      colors: ['red', 'blue', 'green'],
+    })
+  })
+
+  it('can handle non-argv input', () => {
+    const argv = ['--colors=red  blue green']
+
+    expect(arge(argv, false)).toEqual({
+      colors: ['red', 'blue', 'green'],
+    })
+  })
+})

src/index.ts

@@ -0,0 +1,36 @@
+const parse = (value: string | boolean | number) => {
+  if (['true', 'false', true, false].includes(value as string)) {
+    return JSON.parse(value as string)
+  }
+
+  if (!Number.isNaN(Number(value))) {
+    return parseFloat(value as string)
+  }
+
+  if ((value as string).includes(',')) {
+    return (value as string).split(',').map(v => v.trim())
+  }
+
+  if ((value as string).includes(' ')) {
+    return (value as string)
+      .split(' ')
+      .map(v => v.trim())
+      .filter(v => !!v)
+  }
+
+  return value
+}
+
+export const arge = (args: string[], isArgv = true) => {
+  const flags = isArgv ? args.filter((_, index) => index > 1) : args
+
+  return flags.reduce((acc, curr) => {
+    const [k, v] = curr.split('=')
+    const key = k.replace(/^-+/, '')
+
+    return {
+      ...acc,
+      [key]: parse(v || true),
+    }
+  }, {})
+}

tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "**/*.test.*"],
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "outDir": "dist"
+  }
+}

tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./node_modules/@adhamu/zero/tsconfig/base.json",
+  "include": ["**/*.ts*"],
+  "compilerOptions": {
+    "lib": ["ES2021"],
+    "module": "commonjs",
+    "target": "ES2021",
+    "outDir": "./dist"
+  }
+}