https://github.com/sidwebworks/zors
A next-gen framework for type-safe command-line applications
https://github.com/sidwebworks/zors
cli deno node typscript zors
Last synced: 3 months ago
JSON representation
A next-gen framework for type-safe command-line applications
- Host: GitHub
- URL: https://github.com/sidwebworks/zors
- Owner: sidwebworks
- License: mit
- Created: 2022-06-15T09:38:47.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-08-16T11:55:33.000Z (over 3 years ago)
- Last Synced: 2023-03-11T05:56:55.229Z (almost 3 years ago)
- Topics: cli, deno, node, typscript, zors
- Language: TypeScript
- Homepage:
- Size: 362 KB
- Stars: 14
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://packagephobia.com/result?p=zors)
# Zors 🥇
> Next-gen framework for building modern, type-safe command-line applications.
- 📦 Tiny (zero dependencies)
- 💡 Runtime agonistic (supports both Deno and Node JS)
- 🛠️ Rich Features
- 🔩 Simple and extensible plugin api
- 🔑 Excellent Typescript support with fully Typed APIs
# Notice
We're actively working on bug fixes, improvements and documentation to get this stable and released ASAP.
# Table of Contents
- [Installation](#installation)
- [Quick Start Guide](#quick-start-guide)
- [Usage](#usage)
- [Display Help Message and Version](#display-help-message-and-version)
- [API Reference](#api-reference)
- [Packages](#packages)
## Installation
```shell
# with npm
npm install zors
# with yarn
yarn add zors
# with pnpm
pnpm add zors
```
## Quick Start Guide
To create a new program you can import the `zors` function, which takes in your a `name` and `version`
which will be later used for automatic help generation.
> Its recommended to keep your program name same as the `bin` name in your `package.json`
```ts
// in main.[js | ts] ...
import { zors } from 'zors';
const name = 'my-git';
const version = '1.0.0';
const program = zors(name, version);
// let's build a simple git cli
program
.command('init', 'Initialize an empty git repository')
.option(
'-q, --quiet',
'Only print error and warning messages; all other output will be suppressed.'
)
.action((args, options, tools) => {
if (!options.quiet) {
console.log('Initialized an empty git repository');
}
process.exit(0);
});
// run it
await program.run(process.argv.slice(2));
```
### So what do some of these terms mean?
You can use the `.command()` method to create a new [`Command`]() which takes in a some `raw` input and `description` parameters along with an optional [`config`](###command-config) object.
```ts
.command('init', 'Initialize an empty git repository')
```
Every command can define some options, you can add one using `.option()` method on any command object. Which also takes in a `raw` input and `description`.
If neither of these are used, an option is treated as a `boolean` by default.
```ts
.option('-q, --quiet', 'Only print error and warning messages; all other output will be suppressed.')
```
Every command needs to have an `action` defined, action is just a function which is executed with some arguments when the command is called.
You can define an action using the `.action()` method on any command, whose parameters are `args`, `options` and `tools` respectively.
```ts
.action((args, options, tools) => {
// define the actions needed to be done on command execution
});
```
**That's all you need to create a basic CLI app**,
Let's try **running** it. In Node to get the standard input `argv` we can use `process.argv` and use `.slice(2)` ignore the first 2 items in the array as they're of no use to us.
```ts
await program.run(process.argv.slice(2));
```
🔝 [scroll to top](#table-of-contents)
## Usage
### Display Help Message and Version
```ts
import { zors } from 'zors';
import { commitCommand, statusCommand } from './commands.js';
const program = zors('git', '1.0.0');
program
.help() // Displays help message when '-h' or '--help' is specified
.version("1.0.0") // Displays version number when '-v' or '--version' is specified
.command(...)
...
program.run(process.argv.slice(2));
```
🔝 [scroll to top](#table-of-contents)
## API Reference
We rely on Typescript types to auto-generate API documentation [find it here](https://paka.dev/npm/zors)
## Packages
| Package | Version (click for changelogs) |
|---|----|
| [zors](packages/core) | [](packages/core/CHANGELOG.md) |
🔝 [scroll to top](#table-of-contents)