feat: make module an optional option instead of an required argument

Author: xDivisionByZerox

README.md

@@ -13,21 +13,31 @@ npm install --save-dev @faker-js/cli
 ## Usage
 
 ```
-npx faker <moduleName> <functionName>
+npx faker [--module <moduleName>] <functionName>
 ```
 
 > **:information_source: Note**: [Read more about `npx`](https://docs.npmjs.com/cli/v7/commands/npx)
 
-Faker-CLI expects a `moduleName` as well as a `functionName` argument.
-This is equivalent to calling `faker[moduleName][functionName]`.
+Faker-CLI expects a `functionName` argument.
+An additional, optional `--module` (or short `-m`) might be provided in case of naming collisions for `functionName`.
+
+This is equivalent to calling `faker[moduleName][functionName]` in any JavaScript environment.
+If no module option was given, the CLI will search through faker to find an appropriate function for your provided `functionName`.
+
 Checkout [Fakers's API](https://fakerjs.dev/api/) for information on which modules and functions are available.
 
 ## Examples
 
 If you want a integer you can run:
 
 ```bash
-npx faker number int
+npx faker int
+```
+
+of
+
+```bash
+npx faker -m number int
 ```
 
 ## What's Next?
@@ -41,7 +51,7 @@ Currently, the CLI always uses the default `en` locale.
 In the future, this feature could be implemented as follows:
 
 ```bash
-npx faker --locale de person firstName
+npx faker --locale de -m person firstName
 ```
 
 This example would print a first name from the German locale.
@@ -53,7 +63,7 @@ If you need an integer within a specific range, you'll have to do it yourself.
 In the future, this feature could be implemented as follows:
 
 ```bash
-npx faker number int --min 10 --max 20
+npx faker -m number int --min 10 --max 20
 ```
 
 This example will generate an integer between 10 and 20.

src/api.ts

@@ -5,7 +5,7 @@
 
 import { faker } from '@faker-js/faker/locale/en';
 
-export const API: Record<string, Record<string, () => unknown>> = {
+export const API = {
   datatype: { boolean: () => faker.datatype.boolean() },
   date: {
     month: () => faker.date.month(),
@@ -291,4 +291,4 @@ export const API: Record<string, Record<string, () => unknown>> = {
     sample: () => faker.word.sample(),
     words: () => faker.word.words(),
   },
-};
+} satisfies Record<string, Record<string, () => unknown>>;

src/build-program.ts

@@ -0,0 +1,51 @@
+import { Argument, Command, Option } from 'commander';
+import packageJson from '../package.json' with { type: 'json' };
+import { API } from './api.js';
+import { FunctionReferenceError } from './errors.js';
+
+const ALL_ENTRYPOINTS: Record<string, () => unknown> = Object.values(
+  API,
+).reduce((result, moduleRef) => ({ ...moduleRef, ...result }), {});
+
+const moduleOption = new Option(
+  '-m, --module <moduleName>',
+  'The name of the module to use for the function invokation. You might want to explicitly set this option if the name of function you want to invoke exists in multiple modules. By default the alphanumerical first module will be choosen otherwise.',
+).choices(Object.keys(API));
+
+const entryArgument = new Argument(
+  '<functionName>',
+  'The name of the function to invoke.',
+).choices(Object.keys(ALL_ENTRYPOINTS));
+
+function actionHandler(this: Command) {
+  // asserting the type here is fine, because Commander already verifies the user input via the required markers on the argument
+  const [functionName] = this.args as [string];
+  // asserting the type here is fine, because Commander already verifies the user input via .choices()
+  const moduleName = this.getOptionValue('module') as
+    | keyof typeof API
+    | undefined;
+
+  let entrypointRef = ALL_ENTRYPOINTS;
+  if (moduleName !== undefined) {
+    entrypointRef = API[moduleName];
+  }
+
+  const entryRef = entrypointRef[functionName];
+  // This can only happen if a module was picked.
+  // Otherwise Commander verifies the user input via .choices()
+  if (entryRef === undefined) {
+    throw new FunctionReferenceError(functionName, moduleName);
+  }
+
+  process.stdout.write(String(entryRef()));
+}
+
+export function buildProgram(): Command {
+  return new Command()
+    .name('faker')
+    .version(packageJson.version)
+    .description(packageJson.description)
+    .addOption(moduleOption)
+    .addArgument(entryArgument)
+    .action(actionHandler);
+}

src/errors.ts

@@ -0,0 +1,8 @@
+export class FunctionReferenceError extends Error {
+  constructor(functionName: string, moduleName: string | undefined) {
+    super(
+      `The function ${functionName} does not exist${moduleName ? ' within the module ' + moduleName : ''}. Try to omit the module option or choose a different module.`,
+    );
+    this.name = FunctionReferenceError.name;
+  }
+}

src/errors/argument.error.ts

@@ -1,38 +1,4 @@
-import { Command } from 'commander';
-import packageJson from '../package.json' with { type: 'json' };
-import { API } from './api.js';
-import { ArgumentError } from './errors/argument.error.js';
-import { ReferenceError } from './errors/reference.error.js';
-
-function buildProgram(): Command {
-  return new Command()
-    .name('faker')
-    .version(packageJson.version)
-    .description(packageJson.description)
-    .argument('<moduleName>', 'The name of the module to invoke.')
-    .argument('<functionName>', 'The name of the function to invoke.')
-    .action((moduleName, functionName) => {
-      if (typeof moduleName !== 'string') {
-        throw new ArgumentError('moduleName', moduleName);
-      }
-
-      const moduleRef = API[moduleName];
-      if (moduleRef === undefined) {
-        throw new ReferenceError('module', moduleName);
-      }
-
-      if (typeof functionName !== 'string') {
-        throw new ArgumentError('functionName', functionName);
-      }
-
-      const entryRef = moduleRef[functionName];
-      if (entryRef === undefined) {
-        throw new ReferenceError('function', moduleName);
-      }
-
-      process.stdout.write(String(entryRef()));
-    });
-}
+import { buildProgram } from './build-program.js';
 
 export function cli(args: string[]) {
   try {

src/errors/reference.error.ts

@@ -110,7 +110,7 @@ async function generateApi() {
 
     import { faker } from '@faker-js/faker/locale/en';
       
-    export const API: Record<string, Record<string, () => unknown>> = ${apiObjectString};
+    export const API = ${apiObjectString} satisfies Record<string, Record<string, () => unknown>>;
     `,
     // @ts-expect-error migrate to prettier js|ts config file to get type definitions correctly
     { ...prettierConfig, parser: 'typescript' },