feat!: adds support for ESM and Deno

.github/workflows/ci.yaml

@@ -16,7 +16,7 @@ jobs:
         with:
           node-version: ${{ matrix.node }}
       - run: node --version
-      - run: npm install
+      - run: npm install --engine-strict
       - run: npm test
   windows:
     runs-on: windows-latest
@@ -27,6 +27,19 @@ jobs:
           node-version: 12
       - run: npm install
       - run: npm test
+  esm:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [14]
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node }}
+      - run: node --version
+      - run: npm install --engine-strict
+      - run: npm run test:esm
   coverage:
     runs-on: ubuntu-latest
     steps:

index.js → index.cjs

@@ -2,15 +2,14 @@
 // classic singleton yargs API, to use yargs
 // without running as a singleton do:
 // require('yargs/yargs')(process.argv.slice(2))
-const yargs = require('./yargs')
-const processArgv = require('./build/lib/process-argv')
+const Yargs = require('./build/index.cjs')
 
-Argv(processArgv.getProcessArgvWithoutBin())
+Argv(Yargs.processArgv.getProcessArgvWithoutBin())
 
 module.exports = Argv
 
 function Argv (processArgs, cwd) {
-  const argv = yargs(processArgs, cwd, require)
+  const argv = Yargs(processArgs, cwd, require)
   singletonify(argv)
   return argv
 }

index.mjs

@@ -0,0 +1,28 @@
+'use strict'
+
+// Bootstraps yargs in ESM mode:
+import escalade from 'escalade/sync'
+import { fileURLToPath } from 'url';
+import Parser from 'yargs-parser'
+import { dirname, resolve } from 'path'
+import { YargsFactory } from './build/lib/yargs-factory.js'
+
+// TODO: stop using createRequire as soon as we've ported: cliui, y18n, etc.
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const Yargs = YargsFactory({
+  findUp: escalade,
+  Parser,
+  require,
+  requireDirectory: require('require-directory'),
+  stringWidth: require('string-width'),
+  y18n: require('y18n')({
+    directory: resolve(__dirname, '../locales'),
+    updateFiles: false
+  })
+})
+
+export default Yargs

lib/argsert.ts

@@ -1,5 +1,5 @@
-import { YError } from './yerror'
-import { parseCommand, ParsedCommand } from './parse-command'
+import { YError } from './yerror.js'
+import { parseCommand, ParsedCommand } from './parse-command.js'
 
 const positionName = ['first', 'second', 'third', 'fourth', 'fifth', 'sixth']
 export function argsert (callerArguments: any[], length?: number): void

lib/cjs.ts

@@ -0,0 +1,50 @@
+'use strict'
+// This file is used to bootstrap yargs for its legacy CommonJS interface:
+
+import { argsert } from './argsert.js'
+import { isPromise } from './utils/is-promise.js'
+import { objFilter } from './utils/obj-filter.js'
+import { globalMiddlewareFactory } from './middleware.js'
+import { parseCommand } from './parse-command.js'
+import * as processArgv from './utils/process-argv.js'
+import { YargsFactory, rebase } from './yargs-factory.js'
+import { YError } from './yerror.js'
+
+// See https://github.com/yargs/yargs#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 supports a minimum Node.js version of ${minNodeVersion}. Read our version support policy: https://github.com/yargs/yargs#supported-nodejs-versions`)
+  }
+}
+
+// Inject CommonJS dependencies:
+const Parser = require('yargs-parser')
+const { resolve } = require('path')
+const y18n = require('y18n')
+const Yargs = YargsFactory({
+  findUp: require('escalade/sync'),
+  Parser,
+  require: (require as any),
+  requireDirectory: require('require-directory'),
+  stringWidth: require('string-width'),
+  y18n: y18n({
+    directory: resolve(__dirname, '../locales'),
+    updateFiles: false
+  })
+})
+
+export default Object.assign(Yargs, {
+  argsert,
+  globalMiddlewareFactory,
+  isPromise,
+  objFilter,
+  parseCommand,
+  Parser,
+  processArgv,
+  rebase,
+  YError
+})

lib/command.ts

@@ -1,16 +1,14 @@
-import { Dictionary, assertNotStrictEqual } from './common-types'
-import { isPromise } from './is-promise'
-import { applyMiddleware, commandMiddlewareFactory, Middleware } from './middleware'
-import { parseCommand, Positional } from './parse-command'
 import * as path from 'path'
-import { RequireDirectoryOptions } from 'require-directory'
-import { UsageInstance } from './usage'
 import { inspect } from 'util'
-import { ValidationInstance } from './validation'
-import { YargsInstance, isYargsInstance, Options, OptionDefinition, Context, Configuration, Arguments, DetailedArguments } from './yargs'
-import requireDirectory = require('require-directory')
-import whichModule = require('which-module')
-import Parser = require('yargs-parser')
+
+import { Dictionary, assertNotStrictEqual, RequireDirectoryOptions, YargsMixin } from './common-types.js'
+import { isPromise } from './utils/is-promise.js'
+import { applyMiddleware, commandMiddlewareFactory, Middleware } from './middleware.js'
+import { parseCommand, Positional } from './parse-command.js'
+import { UsageInstance } from './usage.js'
+import { ValidationInstance } from './validation.js'
+import { YargsInstance, isYargsInstance, Options, OptionDefinition, Context, Configuration, Arguments, DetailedArguments } from './yargs-factory.js'
+import whichModule from './utils/which-module.js'
 
 const DEFAULT_MARKER = /(^\*)|(^\$0)/
 
@@ -21,7 +19,8 @@ export function command (
   yargs: YargsInstance,
   usage: UsageInstance,
   validation: ValidationInstance,
-  globalMiddleware: Middleware[] = []
+  globalMiddleware: Middleware[] = [],
+  mixin: YargsMixin
 ) {
   const self: CommandInstance = {} as CommandInstance
   let handlers: Dictionary<CommandHandler> = {}
@@ -127,7 +126,7 @@ export function command (
       }
       return visited
     }
-    requireDirectory({ require: req, filename: callerFile } as NodeModule, dir, opts)
+    mixin.requireDirectory({ require: req, filename: callerFile }, dir, opts)
   }
 
   // lookup module object from require()d command and derive name
@@ -368,7 +367,7 @@ export function command (
     const config: Configuration = Object.assign({}, options.configuration, {
       'populate--': true
     })
-    const parsed = Parser.detailed(unparsed, Object.assign({}, options, {
+    const parsed = mixin.Parser.detailed(unparsed, Object.assign({}, options, {
       configuration: config
     }))
 
@@ -463,7 +462,7 @@ export interface CommandInstance {
     context: Context,
     req: NodeRequireFunction,
     callerFile: string,
-    opts?: RequireDirectoryOptions<any>
+    opts?: RequireDirectoryOptions
   ): void
   addHandler (
     cmd: string | string[] | CommandHandlerDefinition,

lib/common-types.ts

@@ -46,3 +46,41 @@ export function assertSingleKey (actual: string | string[] | Dictionary): assert
 export function objectKeys<T> (object: T) {
   return Object.keys(object) as (keyof T)[]
 }
+
+export interface RequireDirectoryOptions {
+  extensions?: ReadonlyArray<string>;
+  visit?: (commandObject: any, pathToFile: string, filename?: string) => any;
+  recurse?: boolean;
+}
+
+// Dependencies that might vary between CJS, ESM, and Deno are isolated:
+export interface YargsMixin {
+  Parser: ({
+    camelcase: Function;
+    detailed: Function;
+    decamelize: Function;
+  }),
+  y18n: Y18N,
+  findUp: Function,
+  requireDirectory: Function
+  stringWidth: Function;
+  require: RequireType;
+}
+
+export interface RequireType {
+  (path: string): Function;
+  main: MainType;
+}
+
+export interface MainType {
+  filename: string;
+  children: MainType[];
+}
+
+export interface Y18N {
+  __(str: string, ...args: string[]): string;
+  __n(str: string, ...args: (string|number)[]): string;
+  getLocale(): string;
+  setLocale(locale: string): void;
+  updateLocale(obj: {[key: string]: string}): void;
+}

lib/completion.ts

@@ -1,12 +1,13 @@
-import { CommandInstance, isCommandBuilderCallback } from './command'
-import * as templates from './completion-templates'
-import { isPromise } from './is-promise'
-import { parseCommand } from './parse-command'
 import * as path from 'path'
-import { UsageInstance } from './usage'
-import { YargsInstance } from './yargs'
-import { Arguments, DetailedArguments } from 'yargs-parser/build/lib/yargs-parser-types'
-import { assertNotStrictEqual } from './common-types'
+
+import { CommandInstance, isCommandBuilderCallback } from './command.js'
+import * as templates from './completion-templates.js'
+import { isPromise } from './utils/is-promise.js'
+import { parseCommand } from './parse-command.js'
+import { UsageInstance } from './usage.js'
+import { YargsInstance } from './yargs-factory.js'
+import { Arguments, DetailedArguments } from 'yargs-parser/build/lib/yargs-parser-types.js'
+import { assertNotStrictEqual } from './common-types.js'
 
 // add bash completions to your
 //  yargs-powered applications.

lib/middleware.ts

@@ -1,6 +1,6 @@
-import { argsert } from './argsert'
-import { isPromise } from './is-promise'
-import { YargsInstance, Arguments } from './yargs'
+import { argsert } from './argsert.js'
+import { isPromise } from './utils/is-promise.js'
+import { YargsInstance, Arguments } from './yargs-factory.js'
 
 export function globalMiddlewareFactory<T> (globalMiddleware: Middleware[], context: T) {
   return function (callback: MiddlewareCallback | MiddlewareCallback[], applyBeforeValidation = false) {

lib/parse-command.ts

@@ -1,4 +1,4 @@
-import { NotEmptyArray } from './common-types'
+import { NotEmptyArray } from './common-types.js'
 
 export function parseCommand (cmd: string) {
   const extraSpacesStrippedCommand = cmd.replace(/\s{2,}/g, ' ')