feat: async resolution; better logging support in commands

examples/01-basic-flags/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/02-error-handling/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/03-simple-commands/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/04-package-manager/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/05-application-config/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/05-application-config/src/index.ts

@@ -20,11 +20,11 @@ class UserConfigResolver extends Resolver {
     return this
   }
 
-  keyExists (key: string): boolean {
+  async keyExists (key: string): Promise<boolean> {
     return this.data[key] !== undefined
   }
 
-  resolveKey (key: string): string {
+  async resolveKey (key: string): Promise<string> {
     const value = this.data[key]
 
     if (value === undefined) {

examples/06-builtin-commands/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/07-prompting/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "start": "npm run build && node lib/index.js",
+    "start": "node --enable-source-maps lib/index.js",
     "build": "tsc"
   },
   "keywords": [],

examples/07-prompting/src/index.ts

@@ -9,12 +9,6 @@ export const parserOpts: ParserOpts = {
   programVersion: 'v1'
 }
 
-// Provide a custom resolver for the username key.
-// This does have the downside that it will *always* try and resolve the key
-// whether the user provides the flag or not.
-//
-// If this distinction matters, use an Argument and override the `resolveDefault` method
-// to control the behaviour dependant on specificity
 class UsernamePromptResolver extends Resolver {
   private readonly rl: readline.Interface
   constructor (id: string) {
@@ -25,9 +19,9 @@ class UsernamePromptResolver extends Resolver {
     })
   }
 
-  async keyExists (key: string): Promise<boolean> {
+  async keyExists (key: string, userDidPassArg: boolean): Promise<boolean> {
     // We only care about resolving our username argument
-    return key === 'username'
+    return key === 'username' && userDidPassArg
   }
 
   async resolveKey (): Promise<string> {

src/args.ts

@@ -116,9 +116,9 @@ export class Args<TArgTypes extends DefaultArgTypes = DefaultArgTypes> {
    * @param inherit - Whether to inherit arguments from this configuration into the parser
    * @returns this
    */
-  public command<TName extends string, TCommand extends Command> (
-    [name, ...aliases]: [`${TName}`, ...string[]],
-    command: TCommand,
+  public command (
+    [name, ...aliases]: [string, ...string[]],
+    command: Command,
     inherit = false
   ): Args<TArgTypes> {
     if (this._state.commands.has(name)) {
@@ -409,7 +409,7 @@ export class Args<TArgTypes extends DefaultArgTypes = DefaultArgTypes> {
    * @returns The result of the parse
    */
   public async parseToResult (argString: string | string[], executeCommands = false): Promise<Result<ParseSuccess<TArgTypes>, ParseError | CoercionError[] | CommandError>> {
-    this.opts.logger.debug(`Beginning parse of input '${argString}'`)
+    this.opts.logger.internal(`Beginning parse of input '${argString}'`)
 
     const tokenResult = tokenise(Array.isArray(argString) ? argString.join(' ') : argString)
 

src/builder/builtin.ts

@@ -58,8 +58,21 @@ export abstract class Builtin {
    * @returns The generated help string
    */
   public helpInfo (): string {
-    return `${this.commandTriggers.map(cmd => `${cmd} <...args>`).join(', ')} | ${this.argumentTriggers.map(arg => `--${arg}`).join(', ')}`
+    const commands = this.commandTriggers.map(cmd => `${cmd} <...args>`).join(', ')
+    const args = this.argumentTriggers.map(arg => `--${arg}`).join(', ')
+
+    if (commands && args) {
+      return `${commands} | ${args}`
+    }
+
+    if (commands) {
+      return commands
+    }
+
+    if (args) {
+      return args
+    }
+
+    return `${this.constructor.name} | no triggers`
   }
 }
-
-export type BuiltinType = 'help' | 'completion' | 'version' | 'fallback'

src/builder/command.ts

@@ -2,13 +2,14 @@ import { Args, DefaultArgTypes } from '../args'
 import { CommandError } from '../error'
 import { InternalCommand } from '../internal/parse/types'
 import { CommandOpts, StoredCommandOpts, defaultCommandOpts, defaultParserOpts } from '../opts'
-import { ArgType } from '../util'
+import { ArgType, Logger } from '../util'
 
 /**
  * Base class for all commands, including subcommands. Any user implemented command must extend from this class.
  */
 export abstract class Command {
   public readonly opts: StoredCommandOpts
+  protected readonly log: Logger
 
   constructor (
     opts: CommandOpts
@@ -21,6 +22,8 @@ export abstract class Command {
         ...opts.parserOpts
       }
     }
+
+    this.log = this.opts.parserOpts.logger
   }
 
   /**

src/builder/default-resolvers.ts

@@ -3,7 +3,7 @@ import { StoredParserOpts } from '../opts'
 import { Resolver } from './resolver'
 
 export class EnvironmentResolver extends Resolver {
-  async keyExists (key: string, opts: StoredParserOpts): Promise<boolean> {
+  async keyExists (key: string, _: boolean, opts: StoredParserOpts): Promise<boolean> {
     const envKey = `${opts.environmentPrefix}_${key.toUpperCase()}`
     const platform = currentPlatform()
     return platform.getEnv(envKey) !== undefined

src/builder/resolver.ts

@@ -13,9 +13,10 @@ export abstract class Resolver {
   /**
    * Determine whether this resolver can resolve the provided key.
    * @param key - The key to check
+   * @param userDidPassArg - Whether the user provided an argument or not
    * @param opts - The parser opts
    */
-  abstract keyExists (key: string, opts: StoredParserOpts): Promise<boolean>
+  abstract keyExists (key: string, userDidPassArg: boolean, opts: StoredParserOpts): Promise<boolean>
   /**
    * Resolve the provided key to its string value.
    *

src/internal/parse/coerce.ts

@@ -90,7 +90,7 @@ async function resolveArgumentDefault (
     const key = argument.type === 'flag' ? argument.longFlag : argument.key
 
     for (const resolver of resolvers) {
-      if (await resolver.keyExists(key, opts)) {
+      if (await resolver.keyExists(key, false, opts)) {
         const value = await resolver.resolveKey(key, opts)
 
         if (!value) {

src/internal/parse/schematic-validation.ts

@@ -37,14 +37,16 @@ export async function validateFlagSchematically (
     }
   }
 
+  const userDidProvideArgs = (foundFlags ?? []).length > 0
+
   let { resolveDefault, optional, dependencies, conflicts, exclusive, requiredUnlessPresent } = argument.inner._state
   const [specifiedDefault, unspecifiedDefault] = await Promise.all([resolveDefault('specified'), resolveDefault('unspecified')])
 
   // Test our resolvers to see if any of them have a value, so we know whether to reject below
   let resolversHaveValue = false
 
   for (const resolver of resolvers) {
-    if (await resolver.keyExists(argument.longFlag, opts)) {
+    if (await resolver.keyExists(argument.longFlag, userDidProvideArgs, opts)) {
       resolversHaveValue = true
     }
   }
@@ -110,7 +112,7 @@ export async function validatePositionalSchematically (
   let resolversHaveValue = false
 
   for (const middleware of resolvers) {
-    if (await middleware.keyExists(argument.key, opts)) {
+    if (await middleware.keyExists(argument.key, foundFlag !== undefined, opts)) {
       resolversHaveValue = true
     }
   }

src/internal/util.ts

@@ -17,11 +17,11 @@ export function getAliasDenotion (alias: FlagAlias): string {
   }
 }
 
-const flagValidationRegex = /-+(?:[a-z]+)/
+const flagValidationRegex = /-+(?:[a-zA-Z]+)/
 
 export function internaliseFlagString (flag: string): ['long' | 'short', string] {
   if (!flagValidationRegex.test(flag)) {
-    throw new SchemaError(`flags must match '--abcdef...' or '-abcdef' got '${flag}'`)
+    throw new SchemaError(`flags must match '--abcdefABCDEF' or '-abcdefABCDEF' got '${flag}'`)
   }
 
   // Long flag

src/util/help.ts

@@ -21,9 +21,9 @@ export function generateHelp (parser: Args<{}>): string {
 
       if (value.aliases.length) {
         if (isMultiType) {
-          return `[--${value.longFlag}${value.aliases.map(getAliasDenotion).join(' | ')}<${value.inner.type}...>]`
+          return `[--${value.longFlag} | ${value.aliases.map(getAliasDenotion).join(' | ')} <${value.inner.type}...>]`
         }
-        return `[--${value.longFlag}${value.aliases.map(getAliasDenotion).join(' | ')}<${value.inner.type}>]`
+        return `[--${value.longFlag} | ${value.aliases.map(getAliasDenotion).join(' | ')} <${value.inner.type}>]`
       }
       return `[--${value.longFlag} <${value.inner.type}>]`
     } else {
@@ -36,9 +36,9 @@ export function generateHelp (parser: Args<{}>): string {
 
       if (value.aliases.length) {
         if (isMultiType) {
-          return `(--${value.longFlag}${value.aliases.map(getAliasDenotion).join(' | ')}<${value.inner.type}...>)`
+          return `(--${value.longFlag} | ${value.aliases.map(getAliasDenotion).join(' | ')} <${value.inner.type}...>)`
         }
-        return `(--${value.longFlag}${value.aliases.map(getAliasDenotion).join(' | ')}<${value.inner.type}>)`
+        return `(--${value.longFlag} | ${value.aliases.map(getAliasDenotion).join(' | ')} <${value.inner.type}>)`
       }
 
       return `(--${value.longFlag} <${value.inner.type}>)`

src/util/logging.ts

@@ -2,6 +2,7 @@ interface Stringifiable { toString: () => string }
 type LoggingFunction<T> = (...args: Stringifiable[]) => T
 
 const LEVEL_TO_CONSOLE: Record<LogLevel, () => (...args: unknown[]) => void> = {
+  internal: () => console.trace,
   trace: () => console.trace,
   debug: () => console.debug,
   info: () => console.log,
@@ -11,7 +12,8 @@ const LEVEL_TO_CONSOLE: Record<LogLevel, () => (...args: unknown[]) => void> = {
 }
 
 const LEVEL_TO_NUMBER: Record<LogLevel, number> = {
-  trace: 0,
+  internal: 0,
+  trace: 1,
   debug: 10,
   info: 20,
   warn: 30,
@@ -22,13 +24,14 @@ const LEVEL_TO_NUMBER: Record<LogLevel, number> = {
 /**
  * The levels which a {@link Logger} can operate at.
  */
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+export type LogLevel = 'internal' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
 
 /**
  * The logging class used internally to (configurably) inform users about library behaviour.
  * This is a thin wrapper around the {@link console}, and should generally be set to something above 'info' in production.
  */
 export class Logger {
+  internal = this.makeLevelFunc('internal', false)
   trace = this.makeLevelFunc('trace', false)
   debug = this.makeLevelFunc('debug', false)
   info = this.makeLevelFunc('info', false)
@@ -51,12 +54,12 @@ export class Logger {
       const ourLevel = LEVEL_TO_NUMBER[this.level]
       const targetLevel = LEVEL_TO_NUMBER[level]
 
-      if (ourLevel >= targetLevel) {
+      if (ourLevel > targetLevel) {
         return
       }
 
-      const fn = LEVEL_TO_CONSOLE[this.level]()
-      fn(`[${this.name}]`, new Date().toISOString(), ':', ...args)
+      const fn = LEVEL_TO_CONSOLE[level]()
+      fn(`[${level.toUpperCase()}]`.padEnd(7), `[${this.name}]`, new Date().toISOString(), ':', ...args)
 
       if (exit) {
         process.exit()

test/integrations/resolver.test.ts

@@ -5,8 +5,8 @@ import { runArgsExecution } from './utils'
 
 class MockResolver extends Resolver {
   constructor (
-    public readonly keyExists: (key: string) => boolean,
-    public readonly resolveKey: (key: string) => string,
+    public readonly keyExists: (key: string) => Promise<boolean>,
+    public readonly resolveKey: (key: string) => Promise<string>,
     id = 'mock'
   ) {
     super(id)
@@ -15,8 +15,8 @@ class MockResolver extends Resolver {
 
 describe('Resolver tests', () => {
   it('calls for resolver when resolving arguments', async () => {
-    const existsFn = jest.fn((key: string) => key === 'ware')
-    const valueFn = jest.fn(() => 'value')
+    const existsFn = jest.fn(async (key: string) => key === 'ware')
+    const valueFn = jest.fn(async () => 'value')
 
     const parser = new Args(parserOpts)
       .arg(['--ware'], a.string())
@@ -29,8 +29,8 @@ describe('Resolver tests', () => {
   })
 
   it('rejects invalid resolver values', async () => {
-    const existsFn = jest.fn((key: string) => key === 'ware')
-    const valueFn = jest.fn(() => 'value')
+    const existsFn = jest.fn(async (key: string) => key === 'ware')
+    const valueFn = jest.fn(async () => 'value')
 
     const parser = new Args(parserOpts)
       .arg(['--ware'], a.decimal())

test/parsing/utils.ts

@@ -1,6 +1,6 @@
 
 import assert from 'assert'
-import { ArgsState, MinimalArgument, StoredParserOpts, defaultCommandOpts } from '../../src'
+import { ArgsState, Command, MinimalArgument, StoredParserOpts, defaultCommandOpts, defaultParserOpts } from '../../src'
 import { CoercedArguments, coerce } from '../../src/internal/parse/coerce'
 import { tokenise } from '../../src/internal/parse/lexer'
 import { ParsedArguments, parse } from '../../src/internal/parse/parser'
@@ -20,17 +20,18 @@ export function makeInternalCommand (
     aliases: aliases ?? [],
     isBase: true,
     inner: {
+      log: defaultParserOpts.logger,
       _subcommands: subcommands ?? {},
-      args: p => p,
+      args: (p: any) => p,
       opts: {
         description: description ?? `${name} command description`,
         parserOpts: opts,
         ...defaultCommandOpts
       },
-      run: p => p,
-      runner: p => p,
-      subcommand: p => ({} as any)
-    },
+      run: (p: any) => p,
+      runner: (p: any) => p,
+      subcommand: (p: any) => ({} as any)
+    } as unknown as Command,
     parser: ({} as any)
   }
 }