Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dpup/node-flags
Flag handling library for node.js.
https://github.com/dpup/node-flags
Last synced: 1 day ago
JSON representation
Flag handling library for node.js.
- Host: GitHub
- URL: https://github.com/dpup/node-flags
- Owner: dpup
- License: mit
- Created: 2011-03-25T01:38:01.000Z (almost 14 years ago)
- Default Branch: main
- Last Pushed: 2025-01-28T15:00:36.000Z (24 days ago)
- Last Synced: 2025-02-12T22:13:24.065Z (9 days ago)
- Language: TypeScript
- Homepage:
- Size: 105 KB
- Stars: 27
- Watchers: 4
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Node-Flags
A flexible and easy-to-use command-line flag parsing library for Node.js applications.
[](https://badge.fury.io/js/flg)
[](https://opensource.org/licenses/MIT)
## Features
- Define flags across multiple files
- Support for various data types (string, boolean, integer, number, string list, multi-string)
- Easy-to-use API for defining and accessing flags
- Customizable flag validation
- Built-in help text generation
## Installation
Install using your favorite package manager:
```bash
npm install flg
# or
yarn add flg
# or
pnpm add flg
```
> ⚠️ _**Important Notice**_: This npm package was formerly known as `flags` and has been renamed to `flg`. Starting from version `3.0.0`, all updates will be published under this new package name.
>
> Migrate from `flags` to `flg` at your convenience to ensure you receive upcoming releases and avoid the deprecation notice of the previous name.
>
> _See [below](#package-name-update) for details and migration steps._
## Usage
Here's a quick example of how to use Node-Flags:
```javascript
import * as flags from "flg";
// Define flags
flags.defineString("name", "Anonymous", "Your name");
flags.defineInteger("age", 21, "Your age in years");
flags.defineNumber("height", 1.8, "Your height in meters");
flags.defineStringList("pets", [], "List of your pets");
flags.defineMultiString("hobby", [], "Your hobbies");
// Parse command-line arguments
flags.parse();
// Access flag values
const info = [
`Name: ${flags.get("name")}`,
`Age: ${flags.get("age")}`,
`Height: ${flags.get("height")}m`,
`Pets: ${flags.get("pets").join(", ")}`,
`Hobbies:\n ${flags.get("hobby").join("\n ")}`,
];
console.log(info.join("\n"));
```
Run your script with flags:
```bash
node example.js --name="John Doe" --age=30 --height=1.75 --pets=dog,cat --hobby=reading --hobby=gaming
```
## Defining Flags
Node-Flags provides several methods to define flags:
- `defineString(name, defaultValue, description)`
- `defineBoolean(name, defaultValue, description)`
- `defineInteger(name, defaultValue, description)`
- `defineNumber(name, defaultValue, description)`
- `defineStringList(name, defaultValue, description)`
- `defineMultiString(name, defaultValue, description)`
Each method returns a `Flag` object that allows further configuration:
```javascript
flags
.defineString("api-key")
.setDefault("your-default-key")
.setDescription("API key for authentication")
.setValidator((value) => {
if (value.length < 10) {
throw new Error("API key must be at least 10 characters long");
}
})
.setSecret(true);
```
## Passing Flags
- Use double dashes for flag names: `--flagname`
- Separate values with an equal sign or space: `--flagname=value` or `--flagname value`
- Quote complex string values: `--message="Hello, World!"`
- Use `--` to separate flags from additional arguments: `--flag1 value1 -- arg1 arg2`
## Querying Flag Values
Access flag values using `flags.get(flagName)` or `flags.FLAGS.flagName.get()`.
Flag objects also provide properties like `name`, `defaultValue`, `currentValue`, and `isSet`.
## Help Text
Node-Flags automatically generates help text. Access it by running your script with the `--help` flag.
## Testing
For testing, you can pass predefined arguments to `flags.parse()`:
```javascript
flags.parse(["--flag1", "--noflag2", "--flag3=value"]);
```
Reset flags between test cases:
```javascript
flags.reset();
```
## Package name update
The original release of `flags` version `0.2.2` has been republished as `flg` version `3.0.0`. This change was made to ensure consistency and avoid potential naming conflicts.
All existing releases under the original `flags` name are still intact, so existing applications will not break.
Migrate to `flg` to ensure you receive future releases.
#### Migration Guide
To upgrade your project to use the new `flg` package:
1. Uninstall the old `flags` package:
```bash
npm uninstall flags
```
2. Install the new `flg` package:
```bash
npm install flg
```
3. Update all references in your code from `flags` to `flg`:
```js
// before
import * as flags from "flags";
// after
import * as flags from "flg";
```
#### Versioning
The new versioning starts from `3.0.0` to reflect the continuity of the `flags` package while aligning with semantic versioning best practices.
#### Release history
| Version | Date |
| ---------------------------------------------------------- | ------------------------ |
| [[email protected]](https://www.npmjs.com/package/flg/v/3.0.0) | _New name going forward_ |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.2.2) | 2024-09-16T17:32:20.498Z |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.2.1) | 2024-09-14T00:38:28.225Z |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.2.0) | 2024-09-13T23:04:51.567Z |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.1.3) | 2015-02-27T02:29:55.285Z |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.1.2) | 2014-04-18T01:55:57.093Z |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.1.1) | 2011-11-02T19:53:15.783Z |
| [[email protected]](https://www.npmjs.com/package/flags/v/0.1.0) | 2011-04-04T14:58:55.383Z |
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.