docs: add TypeScript documentation (#1381)

README.md

@@ -16,7 +16,7 @@
 [![Slack][slack-image]][slack-url]
 
 ## Description :
-Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface. 
+Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.
 
 It gives you:
 
@@ -87,6 +87,16 @@ require('yargs') // eslint-disable-line
 
 Run the example above with `--help` to see the help for the application.
 
+## TypeScript
+
+yargs has type definitions at [@types/yargs][type-definitions].
+
+```
+npm i @types/yargs --save-dev
+```
+
+See usage examples in [docs](/docs/typescript.md)
+
 ## Community :
 
 Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).
@@ -122,3 +132,4 @@ Having problems? want to contribute? join our [community slack](http://devtoolsc
 [conventional-commits-url]: https://conventionalcommits.org/
 [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
 [slack-url]: http://devtoolscommunity.herokuapp.com
+[type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs

docs/typescript.md

@@ -0,0 +1,66 @@
+# TypeScript usage examples
+
+The TypeScript definitions take into account yargs' `type` key and the prescense of
+`demandOption`/`default`.
+
+The following `.options()` definition:
+
+```typescript
+#!/usr/bin/env node
+import yargs from 'yargs';
+
+const argv = yargs.options({
+  a: { type: 'boolean', default: false },
+  b: { type: 'string', demandOption: true },
+  c: { type: 'number', alias: 'chill' },
+  d: { type: 'array' },
+  e: { type: 'count' },
+  f: { choices: ['1', '2', '3'] }
+}).argv;
+```
+
+Will result in an `argv` that's typed like so:
+
+```typescript
+{
+  [x: string]: unknown;
+  a: boolean;
+  b: string;
+  c: number | undefined;
+  d: (string | number)[] | undefined;
+  e: number;
+  f: string | undefined;
+  _: string[];
+  $0: string;
+}
+```
+
+
+You will likely want to define an interface for your application, describing the form that
+the parsed `argv` will take:
+
+```typescript
+interface Arguments {
+  [x: string]: unknown;
+  a: boolean;
+  b: string;
+  c: number | undefined;
+  d: (string | number)[] | undefined;
+  e: number;
+  f: string | undefined;
+}
+```
+
+To improve the `choices` option typing you can also specify its types:
+
+```typescript
+type Difficulty = 'normal' | 'nightmare' | 'hell';
+const difficulties: ReadonlyArray<Difficulty> = ['normal', 'nightmare', 'hell'];
+
+const argv = yargs.option('difficulty', {
+  choices: difficulties,
+  demandOption: true
+}).argv;
+```
+
+`argv` will get  type `'normal' | 'nightmare' | 'hell'`.