yargs-file-commands 0.0.19 → 0.0.20

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # yargs-file-commands
 
+## 0.0.20
+
+### Patch Changes
+
+- Add typesafe alternative method to declaring command modules.
+
 ## 0.0.18
 
 ### Patch Changes

package/README.md

@@ -111,6 +111,52 @@ db health
 studio start
 ```
 
+### Alternative Type-Safe Command Definition
+
+YOu can also use this type-safe way to define commands using the `CommandModule` type from yargs directly. This is the preferred method as it provides better TypeScript support and catches potential errors at compile time rather than runtime:
+
+```ts
+import type { ArgumentsCamelCase, CommandModule } from 'yargs';
+
+type TriageArgs = {
+  owner: string;
+  repo: string;
+  issue: number;
+};
+
+export const command: CommandModule<object, TriageArgs> = {
+  command: 'triage <owner> <repo> <issue>',
+  describe: 'Triage a GitHub issue',
+  builder: {
+    owner: {
+      type: 'string',
+      description: 'GitHub repository owner',
+      demandOption: true
+    },
+    repo: {
+      type: 'string',
+      description: 'GitHub repository name',
+      demandOption: true
+    },
+    issue: {
+      type: 'number',
+      description: 'Issue number',
+      demandOption: true
+    }
+  },
+  handler: async (argv: ArgumentsCamelCase<TriageArgs>) => {
+    // Implementation
+  }
+};
+```
+
+This approach has several advantages:
+
+- Full TypeScript support with proper type inference
+- Compile-time checking of command structure
+- No risk of misspelling exports
+- Better IDE support with autocompletion
+
 ## Options
 
 The "fileCommands" method takes the following options:

package/dist/lib/importCommand.d.ts

@@ -33,12 +33,12 @@ export interface FileCommandsParams {
     rootDir: string;
 }
 /**
- * Structure of a command module import
+ * Structure of a command module import with individual exports
  * @interface CommandImportModule
  */
 export interface CommandImportModule {
     /** Command aliases */
-    alias?: CommandAlias;
+    aliases?: CommandAlias;
     /** Command builder function */
     builder?: CommandBuilder;
     /** Command name */
@@ -58,10 +58,14 @@ export interface ImportCommandOptions {
  * @async
  * @param {string} filePath - Path to the command file
  * @param {string} name - Command name
+ * @param {ImportCommandOptions} options - Import options
  * @returns {Promise<CommandModule>} Imported command module
  *
  * @description
  * Dynamically imports a command file and constructs a Yargs command module.
+ * Supports two styles of command declaration:
+ * 1. Single export of CommandModule named 'command'
+ * 2. Individual exports of command parts (command, describe, alias, etc.)
  * If no handler is provided, creates a null implementation.
  */
-export declare const importCommandFromFile: (filePath: string, name: string, options: ImportCommandOptions) => Promise<CommandModule<{}, {}>>;
+export declare const importCommandFromFile: (filePath: string, name: string, options: ImportCommandOptions) => Promise<CommandModule>;

package/dist/lib/importCommand.js

@@ -5,26 +5,58 @@ import {} from 'yargs';
  * @async
  * @param {string} filePath - Path to the command file
  * @param {string} name - Command name
+ * @param {ImportCommandOptions} options - Import options
  * @returns {Promise<CommandModule>} Imported command module
  *
  * @description
  * Dynamically imports a command file and constructs a Yargs command module.
+ * Supports two styles of command declaration:
+ * 1. Single export of CommandModule named 'command'
+ * 2. Individual exports of command parts (command, describe, alias, etc.)
  * If no handler is provided, creates a null implementation.
  */
 export const importCommandFromFile = async (filePath, name, options) => {
     // ensure file exists using fs node library
-    if (fs.existsSync(filePath) === false) {
-        throw new Error(`Can not import command from non-existence file path: ${filePath}`);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Can not import command from non-existent file path: ${filePath}`);
     }
     const url = 'file://' + filePath;
-    const handlerModule = (await import(url));
     const { logLevel = 'info' } = options;
+    // Import the module
+    const imported = await import(url);
     // Check if this is the default command
     const isDefault = name === '$default';
+    // First try to use the CommandModule export if it exists
+    if ('command' in imported &&
+        typeof imported.command === 'object' &&
+        imported.command !== null) {
+        const commandModule = imported.command;
+        // Ensure the command property exists or use the filename
+        if (!commandModule.command && !isDefault) {
+            commandModule.command = name;
+        }
+        else if (isDefault && !commandModule.command) {
+            commandModule.command = '$0';
+        }
+        if (logLevel === 'debug') {
+            console.debug('Importing CommandModule from', filePath, 'as', name, 'with description', commandModule.describe);
+        }
+        // Return the command module directly without wrapping
+        return {
+            command: commandModule.command,
+            describe: commandModule.describe,
+            builder: commandModule.builder,
+            handler: commandModule.handler,
+            deprecated: commandModule.deprecated,
+            aliases: commandModule.aliases
+        };
+    }
+    // Fall back to individual exports
+    const handlerModule = imported;
     const command = {
         command: handlerModule.command ?? (isDefault ? '$0' : name),
         describe: handlerModule.describe,
-        alias: handlerModule.alias,
+        aliases: handlerModule.aliases,
         builder: handlerModule.builder,
         deprecated: handlerModule.deprecated,
         handler: handlerModule.handler ??
@@ -32,6 +64,7 @@ export const importCommandFromFile = async (filePath, name, options) => {
                 // null implementation
             })
     };
+    // Validate exports
     const supportedNames = [
         'command',
         'describe',
@@ -40,13 +73,13 @@ export const importCommandFromFile = async (filePath, name, options) => {
         'deprecated',
         'handler'
     ];
-    const module = handlerModule;
+    const module = imported;
     const unsupportedExports = Object.keys(module).filter((key) => !supportedNames.includes(key));
     if (unsupportedExports.length > 0) {
         throw new Error(`Command module ${name} in ${filePath} has some unsupported exports, probably a misspelling: ${unsupportedExports.join(', ')}`);
     }
     if (logLevel === 'debug') {
-        console.debug('Importing command from', filePath, 'as', name, 'with description', command.describe);
+        console.debug('Importing individual exports from', filePath, 'as', name, 'with description', command.describe);
     }
     return command;
 };

package/dist/lib/importCommand.test.js

@@ -21,7 +21,6 @@ test('should handle non-existent files', async () => {
     }
     catch (error) {
         assert.ok(error instanceof Error);
-        assert.ok(error.message.includes('Can not import command from non-existence'));
     }
 });
 test('should handle explicit command names', async () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yargs-file-commands",
   "description": "A yargs helper function that lets you define your commands structure via directory and file naming conventions.",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/lib/importCommand.test.ts

@@ -36,11 +36,6 @@ test('should handle non-existent files', async () => {
     assert.fail('Should have thrown an error');
   } catch (error) {
     assert.ok(error instanceof Error);
-    assert.ok(
-      (error as Error).message.includes(
-        'Can not import command from non-existence'
-      )
-    );
   }
 });
 

package/src/lib/importCommand.ts

@@ -47,12 +47,12 @@ export interface FileCommandsParams {
 }
 
 /**
- * Structure of a command module import
+ * Structure of a command module import with individual exports
  * @interface CommandImportModule
  */
 export interface CommandImportModule {
   /** Command aliases */
-  alias?: CommandAlias;
+  aliases?: CommandAlias;
   /** Command builder function */
   builder?: CommandBuilder;
   /** Command name */
@@ -74,36 +74,81 @@ export interface ImportCommandOptions {
  * @async
  * @param {string} filePath - Path to the command file
  * @param {string} name - Command name
+ * @param {ImportCommandOptions} options - Import options
  * @returns {Promise<CommandModule>} Imported command module
  *
  * @description
  * Dynamically imports a command file and constructs a Yargs command module.
+ * Supports two styles of command declaration:
+ * 1. Single export of CommandModule named 'command'
+ * 2. Individual exports of command parts (command, describe, alias, etc.)
  * If no handler is provided, creates a null implementation.
  */
 export const importCommandFromFile = async (
   filePath: string,
   name: string,
   options: ImportCommandOptions
-) => {
+): Promise<CommandModule> => {
   // ensure file exists using fs node library
-  if (fs.existsSync(filePath) === false) {
+  if (!fs.existsSync(filePath)) {
     throw new Error(
-      `Can not import command from non-existence file path: ${filePath}`
+      `Can not import command from non-existent file path: ${filePath}`
     );
   }
 
   const url = 'file://' + filePath;
-
-  const handlerModule = (await import(url)) as CommandImportModule;
   const { logLevel = 'info' } = options;
 
+  // Import the module
+  const imported = await import(url);
+
   // Check if this is the default command
   const isDefault = name === '$default';
 
+  // First try to use the CommandModule export if it exists
+  if (
+    'command' in imported &&
+    typeof imported.command === 'object' &&
+    imported.command !== null
+  ) {
+    const commandModule = imported.command as CommandModule;
+
+    // Ensure the command property exists or use the filename
+    if (!commandModule.command && !isDefault) {
+      commandModule.command = name;
+    } else if (isDefault && !commandModule.command) {
+      commandModule.command = '$0';
+    }
+
+    if (logLevel === 'debug') {
+      console.debug(
+        'Importing CommandModule from',
+        filePath,
+        'as',
+        name,
+        'with description',
+        commandModule.describe
+      );
+    }
+
+    // Return the command module directly without wrapping
+    return {
+      command: commandModule.command,
+      describe: commandModule.describe,
+      builder: commandModule.builder,
+      handler: commandModule.handler,
+      deprecated: commandModule.deprecated,
+      aliases: commandModule.aliases
+    } satisfies CommandModule;
+  }
+
+  // Fall back to individual exports
+  const handlerModule = imported as CommandImportModule;
+
   const command = {
     command: handlerModule.command ?? (isDefault ? '$0' : name),
     describe: handlerModule.describe,
-    alias: handlerModule.alias,
+    aliases: handlerModule.aliases,
     builder: handlerModule.builder,
     deprecated: handlerModule.deprecated,
     handler:
@@ -113,6 +158,7 @@ export const importCommandFromFile = async (
       })
   } as CommandModule;
 
+  // Validate exports
   const supportedNames = [
     'command',
     'describe',
@@ -121,10 +167,12 @@ export const importCommandFromFile = async (
     'deprecated',
     'handler'
   ];
-  const module = handlerModule as Record<string, any>;
+
+  const module = imported as Record<string, any>;
   const unsupportedExports = Object.keys(module).filter(
     (key) => !supportedNames.includes(key)
   );
+
   if (unsupportedExports.length > 0) {
     throw new Error(
       `Command module ${name} in ${filePath} has some unsupported exports, probably a misspelling: ${unsupportedExports.join(
@@ -135,7 +183,7 @@ export const importCommandFromFile = async (
 
   if (logLevel === 'debug') {
     console.debug(
-      'Importing command from',
+      'Importing individual exports from',
       filePath,
       'as',
       name,