docs: typescript

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`
+
+```
+npm i -D @types/yargs
+```
+
+See usage examples in [docs](/docs/typescript.md)
+
 ## Community :
 
 Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).

docs/typescript.md

@@ -0,0 +1,59 @@
+# TypeScript usage examples
+
+Options type inference work pretty well
+
+```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;
+
+```
+`argv` will get type
+```typescript
+{
+  [x: string]: unknown;
+  a: boolean;
+  b: string;
+  c: number | undefined;
+  d: (string | number)[] | undefined;
+  e: number;
+  f: string | undefined;
+  _: string[];
+  $0: string;
+}
+```
+
+You might want to declare an interface for arguments object
+```typescript
+interface Arguments {
+  [x: string]: unknown;
+  a: boolean;
+  b: string;
+  c: number | undefined;
+  d: (string | number)[] | undefined;
+  e: number;
+  f: string | undefined;
+}
+```
+
+To improve `choices` option typing you can specify type for choices
+
+```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'`