cmd-ts-too
v0.15.3
Published
This is a fork of: <https://github.com/Schniz/cmd-ts>
Downloads
638
Readme
This is a fork of: https://github.com/Schniz/cmd-ts
cmd-ts-too
💻 A type-driven command line argument parser, with awesome error reporting 🤤
Not all command line arguments are strings, but for some reason, our CLI parsers force us to use strings everywhere. 🤔 cmd-ts-too
is a fully-fledged command line argument parser, influenced by Rust's clap
and structopt
:
🤩 Awesome autocomplete, awesome safeness
🎭 Decode your own custom types from strings with logic and context-aware error handling
🌲 Nested subcommands, composable API
Basic usage
import { command, run, string, number, positional, option } from 'cmd-ts-too';
const cmd = command({
name: 'my-command',
description: 'print something to the screen',
version: '1.0.0',
args: {
number: positional({ type: number, displayName: 'num' }),
message: option({
long: 'greeting',
type: string,
}),
},
handler: (args) => {
args.message; // string
args.number; // number
console.log(args);
},
});
run(cmd, process.argv.slice(2));
command(arguments)
Creates a CLI command.
Decoding custom types from strings
Not all command line arguments are strings. You sometimes want integers, UUIDs, file paths, directories, globs...
Note: this section describes the
ReadStream
type, implemented in./src/example/test-types.ts
Let's say we're about to write a cat
clone. We want to accept a file to read into stdout. A simple example would be something like:
// my-app.ts
import { command, run, positional, string } from 'cmd-ts-too';
const app = command({
/// name: ...,
args: {
file: positional({ type: string, displayName: 'file' }),
},
handler: ({ file }) => {
// read the file to the screen
fs.createReadStream(file).pipe(stdout);
},
});
// parse arguments
run(app, process.argv.slice(2));
That works okay. But we can do better. In which ways?
- Error handling is out of the command line argument parser context, and in userland, making things less consistent and pretty.
- It shows we lack composability and encapsulation — and we miss a way to distribute shared "command line" behavior.
What if we had a way to get a Stream
out of the parser, instead of a plain string? This is where cmd-ts-too
gets its power from, custom type decoding:
// ReadStream.ts
import { Type } from 'cmd-ts-too;
import fs from 'fs';
// Type<string, Stream> reads as "A type from `string` to `Stream`"
const ReadStream: Type<string, Stream> = {
async from(str) {
if (!fs.existsSync(str)) {
// Here is our error handling!
throw new Error('File not found');
}
return fs.createReadStream(str);
},
};
Now we can use (and share) this type and always get a Stream
, instead of carrying the implementation detail around:
// my-app.ts
import { command, run, positional } from 'cmd-ts-too;
const app = command({
// name: ...,
args: {
stream: positional({ type: ReadStream, displayName: 'file' }),
},
handler: ({ stream }) => stream.pipe(process.stdout),
});
// parse arguments
run(app, process.argv.slice(2));
Encapsulating runtime behaviour and safe type conversions can help us with awesome user experience:
- We can throw an error when the file is not found
- We can try to parse the string as a URI and check if the protocol is HTTP, if so - make an HTTP request and return the body stream
- We can see if the string is
-
, and when it happens, returnprocess.stdin
like many Unix applications
And the best thing about it — everything is encapsulated to an easily tested type definition, which can be easily shared and reused. Take a look at io-ts-types, for instance, which has types like DateFromISOString, NumberFromString and more, which is something we can totally do.
Inspiration
This project was previously called clio-ts
, because it was based on io-ts
. This is no longer the case, because I want to reduce the dependency count and mental overhead. I might have a function to migrate types between the two.