refactor(ts)!: move index.js to TypeScript (#292)

BREAKING CHANGE: projects using `@types/yargs-parser` may see variations in type definitions.

Author: bcoe

index.js

@@ -1,6 +1,6 @@
 import * as path from 'path'
 import * as util from 'util'
-import { tokenizeArgString } from './tokenize-arg-string'
+import { tokenizeArgString } from './lib/tokenize-arg-string'
 import type {
   ArgsInput,
   Arguments,
@@ -22,14 +22,23 @@ import type {
   Options,
   OptionsDefault,
   Parser
-} from './yargs-parser-types'
-import type { Dictionary, ValueOf } from './common-types'
+} from './lib/yargs-parser-types'
+import type { Dictionary, ValueOf } from './lib/common-types'
+
+// See https://github.com/yargs/yargs-parser#supported-nodejs-versions for our
+// version support policy. The YARGS_MIN_NODE_VERSION is used for testing only.
+const minNodeVersion = (process && process.env && process.env.YARGS_MIN_NODE_VERSION)
+  ? Number(process.env.YARGS_MIN_NODE_VERSION) : 10
+if (process && process.version) {
+  const major = Number(process.version.match(/v([^.]+)/)![1])
+  if (major < minNodeVersion) {
+    throw Error(`yargs parser supports a minimum Node.js version of ${minNodeVersion}. Read our version support policy: https://github.com/yargs/yargs-parser#supported-nodejs-versions`)
+  }
+}
 import camelCase = require('camelcase')
 import decamelize = require('decamelize')
 
-export type { Arguments, DetailedArguments, Configuration, Options, Parser }
-
-function parse (argsInput: ArgsInput, options?: Partial<Options>): DetailedArguments {
+function parse (argsInput: ArgsInput, options?: Options): DetailedArguments {
   const opts: Partial<Options> = Object.assign({
     alias: undefined,
     array: undefined,
@@ -1100,15 +1109,15 @@ function sanitizeKey (key: string): string {
   return key
 }
 
-const yargsParser: Parser = function Parser (args: ArgsInput, opts?: Partial<Options>): Arguments {
+const yargsParser: Parser = function Parser (args: ArgsInput, opts?: Options): Arguments {
   const result = parse(args.slice(), opts)
   return result.argv
 }
 
 // parse arguments and return detailed
 // meta information, aliases, etc.
-yargsParser.detailed = function (args: ArgsInput, opts?: Partial<Options>): DetailedArguments {
+yargsParser.detailed = function (args: ArgsInput, opts?: Options): DetailedArguments {
   return parse(args.slice(), opts)
 }
 
-export { yargsParser }
+export = yargsParser

lib/index.ts renamed to index.ts

@@ -73,44 +73,44 @@ export type ConfigCallback = (configPath: string) => { [key: string]: any } | Er
 
 export interface Options {
   /** An object representing the set of aliases for a key: `{ alias: { foo: ['f']} }`. */
-  alias: Dictionary<string | string[]>;
+  alias?: Dictionary<string | string[]>;
   /**
    * Indicate that keys should be parsed as an array: `{ array: ['foo', 'bar'] }`.
    * Indicate that keys should be parsed as an array and coerced to booleans / numbers:
    * { array: [ { key: 'foo', boolean: true }, {key: 'bar', number: true} ] }`.
    */
-  array: ArrayOption | ArrayOption[];
+  array?: ArrayOption | ArrayOption[];
   /** Arguments should be parsed as booleans: `{ boolean: ['x', 'y'] }`. */
-  boolean: string | string[];
+  boolean?: string | string[];
   /** Indicate a key that represents a path to a configuration file (this file will be loaded and parsed). */
-  config: string | string[] | Dictionary<boolean | ConfigCallback>;
+  config?: string | string[] | Dictionary<boolean | ConfigCallback>;
   /** configuration objects to parse, their properties will be set as arguments */
-  configObjects: Dictionary<any>[];
+  configObjects?: Dictionary<any>[];
   /** Provide configuration options to the yargs-parser. */
-  configuration: Partial<Configuration>;
+  configuration?: Partial<Configuration>;
   /**
    * Provide a custom synchronous function that returns a coerced value from the argument provided (or throws an error), e.g.
    * `{ coerce: { foo: function (arg) { return modifiedArg } } }`.
    */
-  coerce: Dictionary<CoerceCallback>;
+  coerce?: Dictionary<CoerceCallback>;
   /** Indicate a key that should be used as a counter, e.g., `-vvv = {v: 3}`. */
-  count: string | string[];
+  count?: string | string[];
   /** Provide default values for keys: `{ default: { x: 33, y: 'hello world!' } }`. */
-  default: Dictionary<any>;
+  default?: Dictionary<any>;
   /** Environment variables (`process.env`) with the prefix provided should be parsed. */
-  envPrefix: string;
+  envPrefix?: string;
   /** Specify that a key requires n arguments: `{ narg: {x: 2} }`. */
-  narg: Dictionary<number>;
+  narg?: Dictionary<number>;
   /** `path.normalize()` will be applied to values set to this key. */
-  normalize: string | string[];
+  normalize?: string | string[];
   /** Keys should be treated as strings (even if they resemble a number `-x 33`). */
-  string: string | string[];
+  string?: string | string[];
   /** Keys should be treated as numbers. */
-  number: string | string[];
+  number?: string | string[];
   /** i18n handler, defaults to util.format */
-  __: (format: any, ...param: any[]) => string;
+  __?: (format: any, ...param: any[]) => string;
   /** alias lookup table defaults */
-  key: Dictionary<any>;
+  key?: Dictionary<any>;
 }
 
 export type OptionsDefault = ValueOf<Pick<Required<Options>, 'default'>>;

lib/yargs-parser-types.ts

@@ -2,14 +2,14 @@
   "name": "yargs-parser",
   "version": "18.1.3",
   "description": "the mighty option parser used by yargs",
-  "main": "index.js",
+  "main": "build/index.js",
   "scripts": {
-    "fix": "standardx --fix && standardx --fix **/*.ts",
+    "fix": "standardx --fix ./*.ts && standardx --fix **/*.ts",
     "pretest": "npm run compile -- -p tsconfig.test.json",
     "test": "c8 --reporter=text --reporter=html mocha test/*.js",
     "posttest": "npm run check",
     "coverage": "c8 report --check-coverage",
-    "check": "standardx && standardx **/*.ts",
+    "check": "standardx ./*.ts && standardx **/*.ts",
     "compile": "rimraf build && tsc",
     "prepare": "npm run compile"
   },

package.json

@@ -0,0 +1,13 @@
+/* global describe, it */
+
+import * as yargsParser from '../'
+import * as assert from 'assert'
+
+describe('types', function () {
+  it('allows a partial options object to be provided', () => {
+    const argv = yargsParser('--foo 99', {
+      string: 'foo'
+    })
+    assert.strictEqual(argv.foo, '99')
+  })
+})

test/types.ts

@@ -6,6 +6,7 @@
     "sourceMap": false
   },
   "include": [
+    "./*.ts",
     "lib/**/*.ts"
   ]
 }

tsconfig.json

@@ -4,6 +4,7 @@
     "sourceMap": true
   },
   "include": [
+    "./*.ts",
     "lib/**/*.ts",
     "test/**/*.ts"
   ]