feat(core): allow middleware to return new object instead of mutating original object

Author: AgentEnder

examples/middleware.ts

@@ -39,13 +39,20 @@ const cli = cliForge('basic-cli')
         .middleware((args) => {
           args.name = args.name.toUpperCase();
         })
+        // Middleware can add new properties to the args object
+        .middleware((args) => {
+          return {
+            ...args,
+            env: process.env.NODE_ENV || 'development',
+          };
+        })
         // Multiple middleware can be registered
         .middleware(() => {
           console.log('HELLO MIDDLEWARE');
         }),
     // Handler is used to define the command's behavior
     handler: (args) => {
-      console.log(`Hello, ${args.name}!`);
+      console.log(`Hello, ${args.name}! [${args.env.toUpperCase()}]`);
     },
   });
 

examples/project.json

@@ -2,7 +2,7 @@
   "name": "examples",
   "targets": {
     "run-example": {
-      "command": "tsx {projectRoot}/{args.example}.ts"
+      "command": "tsx --tsconfig {projectRoot}/tsconfig.json {projectRoot}/{args.example}.ts"
     }
   },
   "implicitDependencies": ["cli-forge", "parser"]

examples/zod.ts

@@ -0,0 +1,65 @@
+// ---
+// id: zod-middleware
+// title: Zod Middleware
+// description: |
+//   As another example of middleware, we can look at how to integrate [Zod](https://npmjs.com/zod). CLI Forge
+//   provides a middleware function under `cli-forge/middleware/zod` that can be used to validate, parse, transform,
+//   and otherwise manipulate command arguments using Zod schemas.
+
+// commands:
+//  - '{filename} hello --name sir'
+// ---
+import cliForge from 'cli-forge';
+import { zodMiddleware } from 'cli-forge/middleware/zod';
+import { z } from 'zod';
+
+const cli = cliForge('basic-cli')
+  // Requires a command to be provided
+  .demandCommand()
+
+  // Registers "hello" command
+  .command('hello', {
+    // Builder is used to define the command's options
+    builder: (args) =>
+      args
+        .option('name', {
+          type: 'string',
+          description: 'The name to say hello to',
+          default: 'World',
+        })
+        // Middleware registered on parent commands will be invoked before the child command's middleware
+        .middleware(
+          zodMiddleware(
+            z
+              .object({
+                name: z
+                  .string()
+                  .min(2, 'Name must be at least 2 characters long'),
+              })
+              .transform((data) => ({
+                name: data.name.trim().toUpperCase(),
+                snakeCase: data.name.trim().replace(/\s+/g, '_').toLowerCase(),
+              }))
+          )
+        ),
+
+    // Handler is used to define the command's behavior
+    handler: (args) => {
+      console.log(`Hello, ${args.name}!`);
+      console.log(`sssssnake_case: ${args.snakeCase}`);
+    },
+  });
+
+// We export the CLI for a few reasons:
+// - Testing
+// - Composition (a CLI can be a subcommand of another CLI)
+// - Docs generation
+export default cli;
+
+// Calling `.forge()` executes the CLI. It's single parameter is the CLI args
+// and they default to `process.argv.slice(2)`.
+if (require.main === module) {
+  (async () => {
+    await cli.forge();
+  })();
+}

package-lock.json

@@ -36,7 +36,8 @@
     "verdaccio": "^5.0.4",
     "vite": "^5.0.0",
     "vitest": "^1.3.1",
-    "yaml": "^2.5.0"
+    "yaml": "^2.5.0",
+    "zod": "^4.1.13"
   },
   "nx": {
     "includedScripts": []

package.json

@@ -7,7 +7,8 @@
   },
   "peerDependencies": {
     "markdown-factory": "0.2.0",
-    "tsx": "4.19.0"
+    "tsx": "4.19.0",
+    "zod": "4.1.13"
   },
   "peerDependenciesMeta": {
     "markdown-factory": {
@@ -17,6 +18,9 @@
     "tsx": {
       "optional": true,
       "dev": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "type": "commonjs",
@@ -31,6 +35,21 @@
   "bin": {
     "cli-forge": "./bin/cli.js"
   },
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./middleware": {
+      "require": "./src/middleware.js",
+      "types": "./src/middleware.d.ts"
+    },
+    "./middleware/*": {
+      "require": "./src/middleware/*.js",
+      "types": "./src/middleware/*.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   }

packages/cli-forge/package.json

@@ -289,9 +289,14 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
     console.log(this.formatHelp());
   }
 
-  middleware(callback: (args: TArgs) => void): CLI<TArgs> {
+  middleware<TArgs2>(
+    callback: (args: TArgs) => TArgs2 | Promise<TArgs2>
+  ): CLI<TArgs2 extends void ? TArgs : TArgs & TArgs2> {
     this.registeredMiddleware.push(callback);
-    return this;
+    // If middleware returns void, TArgs doesn't change...
+    // If it returns something, we need to merge it into TArgs...
+    // that's not here though, its where we apply the middleware results.
+    return this as any;
   }
 
   /**
@@ -317,7 +322,13 @@ export class InternalCLI<TArgs extends ParsedArgs = ParsedArgs>
       }
       if (cmd.configuration?.handler) {
         for (const middleware of middlewares) {
-          await middleware(args);
+          const middlewareResult = await middleware(args);
+          if (
+            middlewareResult !== void 0 &&
+            typeof middlewareResult === 'object'
+          ) {
+            args = middlewareResult as T;
+          }
         }
         await cmd.configuration.handler(args, {
           command: cmd,

packages/cli-forge/src/lib/internal-cli.ts

@@ -174,7 +174,9 @@ export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
   }): CLI<TArgs>;
   group(label: string, keys: (keyof TArgs)[]): CLI<TArgs>;
 
-  middleware(callback: (args: TArgs) => void): CLI<TArgs>;
+  middleware<TArgs2>(
+    callback: MiddlewareFunction<TArgs, TArgs2>
+  ): CLI<TArgs2 extends void ? TArgs : TArgs & TArgs2>;
 
   /**
    * Parses argv and executes the CLI
@@ -273,6 +275,10 @@ export type ErrorHandler = (
   }
 ) => void;
 
+export type MiddlewareFunction<TArgs extends ParsedArgs, TArgs2> = (
+  args: TArgs
+) => TArgs2 | Promise<TArgs2>;
+
 /**
  * Constructs a CLI instance. See {@link CLI} for more information.
  * @param name Name for the top level CLI

packages/cli-forge/src/lib/public-api.ts

@@ -0,0 +1 @@
+export * from './middleware/zod';

packages/cli-forge/src/middleware.ts

@@ -0,0 +1,16 @@
+import { ParsedArgs } from '@cli-forge/parser';
+import { MiddlewareFunction } from '../lib/public-api';
+import type { z, ZodObject, ZodPipe } from 'zod';
+
+export function zodMiddleware<
+  TArgs extends ParsedArgs,
+  TSchema extends ZodObject | ZodPipe<ZodObject>
+>(schema: TSchema): MiddlewareFunction<TArgs, TArgs & z.infer<TSchema>> {
+  return async (args: TArgs) => {
+    const parsed = (await schema.parseAsync(args)) as z.infer<TSchema>;
+    if (typeof parsed !== 'object') {
+      throw new Error('Zod schema did not return an object');
+    }
+    return { ...args, ...parsed };
+  };
+}