zod-commander 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Román Via-Dufresne Saus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# zod-commander
+
+A TypeScript utility for building type-safe CLI commands using [commander](https://www.npmjs.com/package/commander) and [zod](https://www.npmjs.com/package/zod).
+
+## Usage
+
+`zod-commander` lets you define type-safe CLI commands using [zod](https://github.com/colinhacks/zod) schemas for arguments and options, with a simple API.
+
+```ts
+import { Command } from 'commander'
+import { z } from 'zod'
+import { zodCommand } from 'zod-commander'
+
+// Define a command using zodCommand
+const greet = zodCommand({
+  name: 'greet',
+  description: 'Say hello to someone',
+  args: {
+    name: z.string().describe('Name of the person to greet'),
+  },
+  opts: {
+    excited: z.boolean().default(false).describe('e;Add an exclamation mark'), // 'e;' makes -e an alias
+  },
+  async action({ name }, { excited }) {
+    console.log(`Hello, ${name}${excited ? '!' : '.'}`)
+  },
+})
+
+// Create a CLI program and add the command
+const program = new Command()
+program
+  .name('my-cli')
+  .description('A demo CLI using zod-commander')
+  .version('1.0.0')
+  .addCommand(greet)
+  .parseAsync(process.argv)
+```
+
+### Features
+
+- **Type-safe arguments and options**: Use zod schemas to define and validate CLI inputs.
+- **Booleans are treated as flags**: Any boolean option automatically becomes a CLI flag (e.g. `--excited`).
+- **Descriptive help**: `.describe()` on schemas provides help text for each argument/option.
+- **Default values**: Use `.default()` on zod schemas for default option values.
+- **Async actions**: The `action` function can be async and receives parsed args and opts.
+- **No boilerplate**: Just export your command; integrate with your CLI runner as needed.
+- **Aliases for options**: If you start a description with a letter and a semicolon (e.g. `"f;The file to export to"`), that letter will be used as a short alias (e.g. `-f`).
+- **Perfect help output**: The generated help text is clear and complete—try running your command with `--help` to see for yourself!

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { Argument, Command, Option } from 'commander';
+import type { z } from 'zod';
+type BeforeFirstUnderscore<S> = S extends `${infer T}_${infer _}` ? T : S;
+type ReplaceKeyTypes<Type extends z.ZodRawShape> = {
+    [Key in keyof Type as BeforeFirstUnderscore<Key>]: Type[Key];
+};
+export type ZodCommandAction<A extends z.ZodRawShape, O extends z.ZodRawShape> = (args: z.infer<z.ZodObject<A>>, opts: z.infer<z.ZodObject<ReplaceKeyTypes<O>>>) => Promise<void> | void;
+type ZodCommandProps<A extends z.ZodRawShape, O extends z.ZodRawShape> = {
+    name: string;
+    description?: string;
+    args?: A;
+    opts?: O;
+    action: ZodCommandAction<A, O>;
+};
+export declare const zodArgument: (key: string, zod: z.ZodTypeAny) => Argument;
+export declare const zodOption: (key: string, zod: z.ZodTypeAny) => Option;
+export declare const zodCommand: <A extends z.ZodRawShape, O extends z.ZodRawShape>({ name, description, args, opts, action, }: ZodCommandProps<A, O>) => Command;
+export {};

package/dist/index.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodCommand = exports.zodOption = exports.zodArgument = void 0;
+const commander_1 = require("commander");
+const kebabCase_1 = __importDefault(require("lodash/kebabCase"));
+const utis_1 = __importDefault(require("./utis"));
+const zodParser = (zod, opt) => (value) => {
+    const result = zod.safeParse(value);
+    if (result.success)
+        return result.data;
+    const msg = result.error.issues[0].message;
+    if (opt)
+        throw new commander_1.InvalidOptionArgumentError(msg);
+    throw new commander_1.InvalidArgumentError(msg);
+};
+const zodArgument = (key, zod) => {
+    const flag = zod.isOptional() ? `[${key}]` : `<${key}>`;
+    const arg = new commander_1.Argument(flag, zod.description).argParser(zodParser(zod));
+    if (utis_1.default.zodDefault(zod))
+        arg.default(zod.parse(utis_1.default.zodDefault(zod)));
+    const choices = utis_1.default.zodEnumVals(zod);
+    if (choices)
+        arg.choices(choices);
+    return arg;
+};
+exports.zodArgument = zodArgument;
+const zodOption = (key, zod) => {
+    const abbr = zod.description?.match(/^(\w);/)?.[1];
+    const description = abbr ? zod.description.slice(2) : zod.description;
+    const arg = key.includes('_') ? key.split('_').slice(1).join('-') : key;
+    if (key.includes('_'))
+        [key] = key.split('_');
+    key = (0, kebabCase_1.default)(key);
+    const isBoolean = utis_1.default.zodIsBoolean(zod);
+    const flag = `--${key}${isBoolean ? '' : zod.isOptional() ? ` [${arg}]` : ` <${arg}>`}`;
+    const flags = abbr ? `-${abbr}, ${flag}` : flag;
+    const opt = new commander_1.Option(flags, description).argParser(zodParser(zod, 'opt'));
+    if (utis_1.default.zodDefault(zod))
+        opt.default(zod.parse(utis_1.default.zodDefault(zod)));
+    if (isBoolean)
+        opt.optional = true;
+    const choices = utis_1.default.zodEnumVals(zod);
+    if (choices)
+        opt.choices(choices);
+    return opt;
+};
+exports.zodOption = zodOption;
+const zodCommand = ({ name, description, args, opts, action, }) => {
+    const command = new commander_1.Command(name);
+    if (description)
+        command.description(description);
+    for (const key in args)
+        command.addArgument((0, exports.zodArgument)(key, args[key]));
+    for (const key in opts)
+        command.addOption((0, exports.zodOption)(key, opts[key]));
+    command.action(async (...all) => {
+        const resultArgs = Object.fromEntries(Object.keys(args ?? {}).map((key, i) => [key, all[i]]));
+        const resultOpts = all[Object.keys(args ?? {}).length];
+        await action(resultArgs, resultOpts);
+    });
+    command.configureHelp({ showGlobalOptions: true });
+    return command;
+};
+exports.zodCommand = zodCommand;

package/dist/utis.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+declare const utils: {
+    zodCore: <T>(zod: z.ZodTypeAny, fn: (zod: z.ZodTypeAny) => T) => T;
+    zodEnumVals: (zod: z.ZodTypeAny) => any;
+    zodIsBoolean: (zod: z.ZodTypeAny) => boolean;
+    zodDefault: <Output, Def extends z.ZodTypeDef, Input>(zod: z.ZodType<Output, Def, Input>) => Input | undefined;
+};
+export default utils;

package/dist/utis.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const zodCore = (zod, fn) => {
+    const types = [zod_1.z.ZodDefault, zod_1.z.ZodNullable, zod_1.z.ZodOptional];
+    for (const type of types)
+        if (zod instanceof type)
+            return zodCore(zod._def.innerType, fn);
+    if (zod instanceof zod_1.z.ZodEffects)
+        return zodCore(zod._def.schema, fn);
+    return fn(zod);
+};
+const zodEnumVals = (zod) => zodCore(zod, (zod) => (zod instanceof zod_1.z.ZodEnum ? zod._def.values : null));
+const zodIsBoolean = (zod) => zodCore(zod, (zod) => zod instanceof zod_1.z.ZodBoolean);
+const zodDefault = (zod) => zod instanceof zod_1.z.ZodEffects
+    ? zodDefault(zod._def.schema)
+    : zod instanceof zod_1.z.ZodDefault
+        ? zod._def.defaultValue()
+        : undefined;
+const utils = {
+    zodCore,
+    zodEnumVals,
+    zodIsBoolean,
+    zodDefault,
+};
+exports.default = utils;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "zod-commander",
+  "version": "0.0.2",
+  "description": "A TypeScript utility for building type-safe CLI commands using commander and zod.",
+  "author": "Román Via-Dufresne Saus <roman910dev@gmail.com>(https://github.com/roman910dev)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roman910dev/zod-commander.git"
+  },
+  "keywords": [
+    "commander",
+    "zod",
+    "cli",
+    "typescript"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.6",
+    "@types/lodash": "^4.17.20",
+    "commander": "^14.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.2",
+    "typescript": "^5.8.3",
+    "zod": "^3.25.0"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "lint-staged": {
+    "*.ts": [
+      "tsc --noEmit && biome ci --threads=4"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "commander": ">=8 <15",
+    "zod": ">=3.20.0 <4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix --formatter-enabled=false .",
+    "format": "biome format --write .",
+    "ci": "biome ci --threads=4"
+  }
+}