# @joro/optimist

> Optimize options list

Latest version **0.1.7** (published 2020-04-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @joro/optimist
pnpm add @joro/optimist
yarn add @joro/optimist
bun add @joro/optimist
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.7 |
| Published | 2020-04-24 |
| First published | 2020-04-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 9.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jōro |
| Maintainers | amatsuyukun |
| Keywords | arguments, command-line, commands, console, parameters, parser, options |

## Links

- npm: https://www.npmjs.com/package/@joro/optimist
- Repository: https://github.com/AmatsuyuKun/Optimist
- Homepage: https://github.com/AmatsuyuKun/Optimist#readme
- Issues: https://github.com/AmatsuyuKun/Optimist/issues
- npm.io page: https://npm.io/package/@joro/optimist

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 0.1.7 (latest) — 2020-04-24
- 0.1.6 — 2020-04-24
- 0.1.5 — 2020-04-24
- 0.1.4 — 2020-04-24
- 0.1.3 — 2020-04-24
- 0.1.2 — 2020-04-24
- 0.1.1 — 2020-04-24

## README

<p>
    <a href="https://www.npmjs.com/package/@joro/optimist">
        <img src="https://badgen.net/npm/v/@joro/optimist?color=green" alt="NPM version">
    </a>
    <a href="https://circleci.com/gh/AmatsuyuKun/Optimist">
        <img src="https://circleci.com/gh/AmatsuyuKun/Optimist.svg?style=shield" alt="CircleCI Status"/>
    </a>
    <a href="https://david-dm.org/AmatsuyuKun/Optimist?type=dev">
        <img src="https://david-dm.org/AmatsuyuKun/Optimist/dev-status.svg" alt="DevDependencies Status"/>
    </a>
</p>

<!-- Spacing -->
<br/>

<p align="center">
    <img src="media/optimist.png" alt="Optimist" width="200px"/>
</p>

<h2 align="center">♻️ Optimize options list</h2>

Simply maps common command-line options to an `object`, turning their values to literal types.

## Table of Contents

- [Usage](#usage)
  - [Options and Values](#options-and-values)
  - [Defaults and Aliases](#defaults-and-aliases)
  - [Returned Value](#returned-value)
- [References](#references)
- [Contributing](#contributing)
- [License](#license)

## Usage

Install Optimist using `npm`:

```bash
npm install --save-dev @joro/optimist
```

Or `yarn`:

```bash
yarn add --dev @joro/optimist
```

Get started by simply requiring optimist module and define an optional default values:

```javascript
const optimist = require('@joro/optimist');

const defaults = {
  option1: 'string',
  option2: [true, false],
  option3: {
    defaults: -1.1,
    aliases: 'opt3'
  },
  option4: {
    defaults: [null, undefined],
    aliases: ['opt4']
  }
};

console.log(optimist(process.argv.slice(2), defaults));
```

Now, if we execute our script with the following arguments:

```bash
node <script.js> --option1 string --option2 -opt3 -1.1 -opt4=undefined
```

It will output an optimized representation of the given options:

```javascript
{
  _: [],
  option1: 'string',
  option2: true,
  option3: -1.1,
  option4: undefined
}
```

### Options and Values

Valid options syntax are marked with a `--` or `-`, and values are separated with a space or `=`. Single options are parsed with an implicit `true` value.

Number values like `-1.1` are treated as both an option or a value depending on the position of arguments, e.g in `-123=value` and `--option=-123`, the former is an option name while the latter is a value. Values such as `boolean`, `number`, `null`, or `undefined` types are parsed as literals. Others will remain as raw string.

### Defaults and Aliases

Referring to the above example, the given defaults are used to determine if the actual command-line arguments contains valid or invalid options as well as provide default values to those options not explicitly specified. Such defaults are defined as the following:

- `option1`: Represents an option with a single default value.
  - Matches: `--option1 'string'` or `--option1=string`
- `option2`: Represents an option with multiple required values.
  - Matches: `--option2` or `--option2=false`
- `option3`: Represents an option with a single default value including an alias.
  - Matches: `--option3 -1.1` or `-opt3=-1.1`
- `option4`: Represents an option with multiple required values including an alias.
  - Matches: `--option4 null` or `-opt4=undefined`

> **Note:** For multiple values, the actual default value is the first element (index `[0]`), e.g in `[true, false]`, `true` is the default value.

> **Note:** Use the `aliases` property to define a name alias. Doing so, will let you use the `defaults` property for default values. Aliases will always return their exact `option` name, e.g, `--opt3=value` will return `option3`:`value`.

### Returned Value

The returned `object` contains an `option`:`value` pairs including a `['_']` property containing a list of all invalid options. An invalid option is captured if its name or value is not defined in the defaults. If there are no provided defaults, then only the syntax will be parsed.

## References

Optimist is designed to be just simple. If you didn't find what you're looking for, try [minimist](https://www.npmjs.com/package/minimist) instead.

## Contributing

Fork or star this repository to give a positive feedback :heavy_heart_exclamation:. Send bug reports, and other issues [here](https://github.com/AmatsuyuKun/Optimist/issues).

## License

Copyright 2020 Jōro. Use of this source code is governed by the MIT license that can be found in the [LICENSE](LICENSE) file or at https://opensource.org/licenses/MIT.

---
_Source: https://npm.io/package/@joro/optimist · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._