feat: utility types for modular handler declaration (#73)

* configure modular utility types

* expose default options

Author: eegli

.changeset/late-zoos-glow.md

@@ -0,0 +1,5 @@
+---
+"@eegli/tinyparse": patch
+---
+
+Parsers now expose default options

.changeset/wise-onions-obey.md

@@ -0,0 +1,5 @@
+---
+"@eegli/tinyparse": patch
+---
+
+New utility types that allow for modular handler declaration!

docs/reference/handlers.md

@@ -42,20 +42,59 @@ const defaultHandler: CommandHandler<typeof options> = ({
   console.log({ args, globals, options, usage });
 };
 
-const executeHandler = new Parser()
-  .defaultHandler(defaultHandler)
-  .parse(['hello', 'world']).call;
+options.defaultHandler(defaultHandler).parse(['hello', 'world']).call();
+```
+
+Default handlers can be a good place to handle things that Tinyparse is not opinionated about. For example, you can print an error to the console and tell the user that they should select one of the available subcommands. You can also log the usage text to the console so that the user knows what to do next. The usage text is the same as if the app were invoked with a help command or flag (if defined).
+
+## Modular Declaration
+
+In the above example, we use the `CommandHandler` type to declare the default handler. This will annotate the function as taking an object literal with all parameters. Hence, if you want to invoke it somewhere else - like in a test - you will need to pass values for `args`, `globals`, `options`, and `usage`. This is a bit cumbersome. You can declare default and subcommand handlers more modularly by specifiying _exactly_ what they need using the `Handler*` utility types:
+
+```ts
+import { Parser } from '@eegli/tinyparse';
+import type {
+  HandlerParams,
+  HandlerGlobals,
+  HandlerOptions,
+} from '@eegli/tinyparse';
+
+const options = new Parser();
 
-// Time goes by...
+type Globals = HandlerGlobals<typeof options>;
+type Options = HandlerOptions<typeof options>;
 
-await executeHandler();
+// Handler that only needs options and globals
+type DefaultHandler = HandlerParams<Options, never, Globals>;
 
-expect(consoleLog).toHaveBeenCalledWith({
-  args: ['hello', 'world'],
-  globals: {},
-  options: {},
-  usage: expect.any(String),
-});
+const defaultHandler: DefaultHandler = ({ globals, options }) => {
+  console.log({ globals, options });
+};
+
+// Other possible options...
+
+// No parameters
+type NoParamsHandler = HandlerParams;
+const noopHandler: NoParamsHandler = () => {};
+
+// Positional arguments and options only
+type HandlerWithArgs = HandlerParams<Options, [string]>;
+const handlerWithArgs: HandlerWithArgs = ({ options, args }) => {};
+
+// Usage only
+type HandlerWithUsage = HandlerParams<never, never, never, string>;
+const handlerWithUsage: HandlerWithUsage = ({ usage }) => {};
 ```
 
-Default handlers can be a good place to handle things that Tinyparse is not opinionated about. For example, you can print an error to the console and tell the user that they should select one of the available subcommands. You can also log the usage text to the console so that the user knows what to do next. The usage text is the same as if the app were invoked with a help command or flag (if defined).
+In the above example, we specify a handful of handlers, each of which only needs a subset of what Tinyparse feeds it. `HandlerParams` has the following signature:
+
+```ts
+type HandlerParams<
+  Options extends FlagValueRecord = never,
+  Args extends string[] = never,
+  Globals extends AnyGlobal = never,
+  Usage extends string = never,
+> = (...)
+```
+
+In summary, the `CommandHandler` can be a useful shortcut, but if you only need a subset of the parameters, it might make sense to declare the handler more modularly.

docs/reference/options.md

@@ -18,12 +18,18 @@ const parser = new Parser()
   .defaultHandler();
 ```
 
-- `shortFlag` is the short flag _alias_ that will match the option
+- `shortFlag` is the short flag _alias_ that will match the option. It must start with `-`
 - `defaultValue` is used to _infer_ the type of the option. To make this possible, it can only be of **four easily checkable types**: `string`, `number`, `boolean` or `Date`
 - `required` indicates whether the option is required or not
 - `description` is used to generate the help text
 
-If and only if the _expected value_ (i.e., `defaultValue`) for a flag is a number or valid Javascript date string, Tinyparse will try to convert it accordingly.
+If and only if the _expected value_ (i.e., `defaultValue`) for a flag is a _number_ or valid Javascript _date string_, Tinyparse will try to convert it accordingly.
+
+Default option values can be accessed via the `options` getter:
+
+```ts
+parser.options; // { foo: 0 }
+```
 
 ## Validation
 

src/commands.ts

@@ -61,6 +61,9 @@ export class CommandBuilder<
     }
   };
 
+  /**
+   * Add an option (flag)
+   */
   option<K extends string, V extends FlagValue>(key: K, opts: FlagOptions<V>) {
     const { longFlag, shortFlag } = opts;
     this.#validateOption(key);
@@ -76,6 +79,9 @@ export class CommandBuilder<
     >;
   }
 
+  /**
+   * Add a subcommand
+   */
   subcommand<A extends CommandArgPattern>(
     command: string,
     opts: Subcommand<Options, Globals, A>,
@@ -85,25 +91,28 @@ export class CommandBuilder<
     return this;
   }
 
-  subparser<O extends FlagValueRecord, G extends AnyGlobal>(
-    command: string,
-    opts: Subparser<O, G>,
-  ) {
+  /**
+   * Add a subparser
+   */
+  subparser(command: string, opts: Subparser<FlagValueRecord, AnyGlobal>) {
     this.#tryRegisterCommandToken(command);
-    this.#config.parsers.set(
-      command,
-      opts as Subparser<FlagValueRecord, AnyGlobal>,
-    );
+    this.#config.parsers.set(command, opts);
     return this;
   }
 
+  /**
+   * Set the globals
+   */
   setGlobals<G extends Globals>(
     setGlobals: (options: Options) => G | Promise<G>,
   ) {
     this.#config.globalSetter = setGlobals;
     return this as unknown as CommandBuilder<Options, G>;
   }
 
+  /**
+   * Set metadata
+   */
   setMeta(meta: MetaOptions) {
     this.#tryRegisterCommandToken(meta.help?.command);
     this.#tryRegisterCommandToken(meta.version?.command);
@@ -117,11 +126,17 @@ export class CommandBuilder<
     return this;
   }
 
+  /**
+   * Set the error handler
+   */
   onError(handler: ErrorHandler) {
     this.#config.errorHandler = handler;
     return this;
   }
 
+  /**
+   * Set the default handler
+   */
   defaultHandler(handler?: DefaultHandler<Options, Globals>) {
     return new Parser<Options, Globals>({
       ...this.#config,

src/config.ts

@@ -13,7 +13,7 @@ interface CoreConfig<O extends FlagValueRecord, G extends AnyGlobal> {
   meta: MetaOptions;
   options: FlagOptionsMap;
   commands: CommandOptionsMap<O, G>;
-  parsers: SubparserOptionsMap<FlagValueRecord, AnyGlobal>;
+  parsers: SubparserOptionsMap;
 }
 
 export interface CommonConfig<O extends FlagValueRecord, G extends AnyGlobal>

src/help.ts

@@ -137,7 +137,7 @@ export class HelpPrinter<O extends FlagValueRecord, G extends AnyGlobal> {
     const command = this.#meta?.command;
 
     let str = summary ? `${summary}\n\nUsage:` : 'Usage:';
-    if (command) str += ` ${command} [command] <...flags>`;
+    if (command) str += ` ${command} [command?] <...flags>`;
     return str;
   }
 

src/index.ts

@@ -1,4 +1,11 @@
 export { CommandBuilder as Parser } from './commands';
 export { ValidationError } from './error';
 
-export type { CommandHandler, ErrorHandler, GlobalSetter } from './types';
+export type {
+  CommandHandler,
+  ErrorHandler,
+  GlobalSetter,
+  HandlerGlobals,
+  HandlerOptions,
+  HandlerParams,
+} from './types';

src/parser.ts

@@ -9,19 +9,33 @@ import {
   FlagValueRecord,
   Subcommand,
 } from './types';
-export class Parser<O extends FlagValueRecord, G extends AnyGlobal> {
-  #config: CommonConfig<O, G>;
-  #helpPrinter: HelpPrinter<O, G>;
+export class Parser<
+  Options extends FlagValueRecord,
+  Globals extends AnyGlobal,
+> {
+  #config: CommonConfig<Options, Globals>;
+  #helpPrinter: HelpPrinter<Options, Globals>;
 
-  constructor(config: CommonConfig<O, G>) {
+  constructor(config: CommonConfig<Options, Globals>) {
     this.#config = config;
     this.#helpPrinter = new HelpPrinter(config);
   }
 
+  /**
+   * Get the default options with their default values
+   */
+  get options(): Options {
+    const entries = [...this.#config.options.entries()].map(([k, v]) => [
+      k,
+      v.defaultValue,
+    ]);
+    return Object.fromEntries(entries);
+  }
+
   #validateSubcommandArgs(
     command: string,
     args: string[],
-    commandOpts: Subcommand<O, G, CommandArgPattern>,
+    commandOpts: Subcommand<Options, Globals, CommandArgPattern>,
   ) {
     if (Array.isArray(commandOpts.args)) {
       const expectedNumArgs = commandOpts.args.length;
@@ -71,6 +85,9 @@ export class Parser<O extends FlagValueRecord, G extends AnyGlobal> {
     throw error;
   }
 
+  /**
+   * Parse the given argv and return a function to call the appropriate handler
+   */
   parse(argv: string[]): {
     call: () => Promise<void>;
   } {
@@ -89,8 +106,8 @@ export class Parser<O extends FlagValueRecord, G extends AnyGlobal> {
         return;
       }
       try {
-        const options = collectFlags(flagMap, this.#config.options) as O;
-        const setGlobals = this.#config.globalSetter || (() => ({}) as G);
+        const options = collectFlags(flagMap, this.#config.options) as Options;
+        const setGlobals = this.#config.globalSetter || (() => ({}) as Globals);
         const globals = await setGlobals(options);
         const subcommandOpts = this.#config.commands.get(subcommand);
         if (subcommandOpts) {

src/types.ts

@@ -78,10 +78,10 @@ export type Subparser<O extends FlagValueRecord, G extends AnyGlobal> = {
 /**
  * A map of subparsers and their settings.
  */
-export type SubparserOptionsMap<
-  O extends FlagValueRecord = FlagValueRecord,
-  G extends AnyGlobal = AnyGlobal,
-> = Map<string, Subparser<O, G>>;
+export type SubparserOptionsMap = Map<
+  string,
+  Subparser<FlagValueRecord, AnyGlobal>
+>;
 
 export type HelpOptions = {
   command?: string;
@@ -121,6 +121,34 @@ export type GlobalSetter<T> = T extends CommandBuilder<infer O, AnyGlobal>
 
 export type ErrorHandler = (error: ValidationError, usage: string) => void;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HandlerOptions<T> = T extends CommandBuilder<infer O, any>
+  ? O
+  : never;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HandlerGlobals<T> = T extends CommandBuilder<any, infer G>
+  ? G
+  : never;
+
+export type HandlerParams<
+  Options extends FlagValueRecord = never,
+  Args extends string[] = never,
+  Globals extends AnyGlobal = never,
+  Usage extends string = never,
+> = (
+  params: RemoveNever<{
+    options: Options;
+    args: Args;
+    globals: Globals;
+    usage: Usage;
+  }>,
+) => void | Promise<void>;
+
+type RemoveNever<T> = {
+  [K in keyof T as T[K] extends never ? never : K]: T[K];
+};
+
 export type Downcast<T> = T extends unknown[]
   ? {
       [P in keyof T]: T[P] extends number