# yargs-command-wrapper

> enables the parsing of commands and subcommands into a unified set of types

Latest version **1.0.7-1** (published 2024-09-24) · ISC license · 0 weekly downloads

## Install

```sh
npm install yargs-command-wrapper
pnpm add yargs-command-wrapper
yarn add yargs-command-wrapper
bun add yargs-command-wrapper
```

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7-1 |
| Published | 2024-09-24 |
| First published | 2023-05-30 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 114.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Nikita Kanashin |
| Maintainers | nktknshn |
| Keywords | yargs, argument, args, option, parser, parsing, cli, command, fp-ts, fp |

## Links

- npm: https://www.npmjs.com/package/yargs-command-wrapper
- Homepage: https://github.com/nktknshn/yargs-command-wrapper
- npm.io page: https://npm.io/package/yargs-command-wrapper

## Dependencies (2)

- [yargs](https://npm.io/package/yargs.md) ^17.7.2
- [@types/yargs](https://npm.io/package/@types/yargs.md) ^17.0.33

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 1.0.7-1 (latest) — 2024-09-24
- 1.0.7 — 2024-09-24
- 1.0.6 — 2024-08-21
- 1.0.5 — 2023-06-06
- 1.0.4 — 2023-06-06
- 1.0.3 — 2023-06-05
- 1.0.2 — 2023-06-05
- 1.0.1 — 2023-06-05
- 1.0.0 — 2023-05-30

## README

# About

<p>
  <a href="https://github.com/nktknshn/yargs-command-wrapper/actions">
    <img src="https://github.com/nktknshn/yargs-command-wrapper/actions/workflows/node.js.yml/badge.svg?branch=master" alt="build status" height="20">
  </a>
  <a href="https://www.npmjs.com/package/yargs-command-wrapper">
    <img src="https://img.shields.io/npm/v/yargs-command-wrapper.svg" alt="npm link" height="20">
  </a>
</p>

This wrapper enables the parsing of commands and subcommands into a unified set
of types that can be handled independently. Additionally, it simplifies the process
of creating a handler for these commands

The inferred union type of the parsed arguments is as follows:

<!-- dprint-ignore -->
```typescript
type ParsedArgs = 
| { command: "server"; subcommand: "start"; argv: { port: number; } }
| { command: "client"; subcommand: "connect"; argv: { host: string; port: number; } }
| { command: "client"; subcommand: "config"; subsubcommand: "get"; argv: { key?: string; file: string; } }
| { command: "client"; subcommand: "config"; subsubcommand: "set"; argv: { key: string; value: string; file: string; } }
```

# Installation

```bash
npm install --save yargs-command-wrapper
```

# Examples

**API might change in the future.**

[https://github.com/nktknshn/yargs-command-wrapper/tree/master/examples](https://github.com/nktknshn/yargs-command-wrapper/tree/master/examples)

[https://github.com/nktknshn/typescript-money-tracker/blob/master/src/cli.ts](https://github.com/nktknshn/typescript-money-tracker/blob/master/src/cli.ts)

```typescript
import {
  buildAndParse,
  command,
  composeCommands,
  createHandlerFor,
  Either,
  failClient,
  subcommands,
} from "yargs-command-wrapper";

const config = composeCommands(
  _ =>
    _.options({
      file: { alias: "f", type: "string", default: "config.json" },
    }),
  command(
    ["get [key]", "g"],
    "get config value",
    _ => _.positional("key", { type: "string" }),
  ),
  command(
    ["set <key> <value>", "s"],
    "set config key",
    _ =>
      _
        .positional("value", { type: "string", demandOption: true })
        .positional("key", { type: "string", demandOption: true }),
  ),
);

const serverStart = command(
  ["start", "sta"],
  "start server",
  _ => _.option("port", { type: "number", default: 8080 }),
);

const serverStop = command(
  ["stop", "sto"],
  "stop server",
  _ => _.option("force", { type: "boolean", default: false }),
);

const cmd = composeCommands(
  _ => _.option("debug", { alias: "d", type: "boolean", default: false }),
  serverStart,
  serverStop,
  subcommands(["config", "c"], "config management", config),
  // allow command without a subcommand
).selfHandle(true);

const { result, yargs } = buildAndParse(cmd, process.argv.slice(2));

if (Either.isLeft(result)) {
  failClient(yargs, result);
}

if (result.right.argv.debug) {
  console.log("debug mode enabled");
}

if (result.right.command === undefined) {
  console.log(`cli was called without any commands`);
  yargs.showHelp();
}
else if (result.right.command === "start") {
  console.log(`starting server on port ${result.right.argv.port}`);
}
else if (result.right.command === "stop") {
  console.log(`stopping server ${result.right.argv.force ? "forcefully" : ""}`);
}
else if (result.right.command === "config") {
  if (result.right.subcommand === "get") {
    console.log(`getting config key ${result.right.argv.key ?? "all"}`);
  }
  else {
    console.log(
      `setting config key ${result.right.argv.key} to ${result.right.argv.value}`,
    );
  }
}

// or by using createHandlerFor:
const handler = createHandlerFor(cmd, {
  "$self": ({ debug }) => {
    console.log(
      `cli was called without any commands. debug: ${debug ? "yes" : "no"}`,
    );
    yargs.showHelp();
  },
  config: {
    get: ({ key, file, debug }) => {
      console.log(`getting config ${file} key ${key ?? "all"}`);
    },
    set: ({ key, value, file, debug }) => {
      console.log(`setting config ${file} key ${key} to ${value}`);
    },
  },
  start: ({ port, debug }) => {
    console.log(`starting server on port ${port}`);
  },
  stop: ({ force, debug }) => {
    console.log(`stopping server ${force ? "forcefully" : ""}`);
  },
});

handler.handle(result.right);
```

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