zod-commander 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -4,15 +4,49 @@ 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 Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The action function signature for a Zod-powered command.
+ * @template A - ZodRawShape for arguments
+ * @template O - ZodRawShape for options
+ * @param args - Parsed and validated arguments
+ * @param opts - Parsed and validated options (with key normalization)
+ * @returns A Promise or void
+ */
+export type ZodCommandAction<A extends z.ZodRawShape, O extends z.ZodRawShape> = ZodCommandProps<A, O>['action'];
 type ZodCommandProps<A extends z.ZodRawShape, O extends z.ZodRawShape> = {
     name: string;
     description?: string;
     args?: A;
     opts?: O;
-    action: ZodCommandAction<A, O>;
+    action: (args: Prettify<z.infer<z.ZodObject<A>>>, opts: Prettify<z.infer<z.ZodObject<ReplaceKeyTypes<O>>>>) => Promise<void> | void;
 };
+/**
+ * Creates a Commander.js Argument from a Zod schema.
+ * Handles optionality, default values, and enum choices.
+ * @param key - The argument name
+ * @param zod - The Zod schema for the argument
+ * @returns A Commander Argument instance
+ */
 export declare const zodArgument: (key: string, zod: z.ZodTypeAny) => Argument;
+/**
+ * Creates a Commander.js Option from a Zod schema.
+ * Handles optionality, default values, enum choices, and boolean flags.
+ * Supports short flags via description prefix (e.g., 's;...').
+ * @param key - The option name (can include underscores for grouping)
+ * @param zod - The Zod schema for the option
+ * @returns A Commander Option instance
+ */
 export declare const zodOption: (key: string, zod: z.ZodTypeAny) => Option;
+/**
+ * Defines a Commander.js Command using Zod schemas for arguments and options.
+ * Automatically wires up parsing, validation, and help configuration.
+ * @template A - ZodRawShape for arguments
+ * @template O - ZodRawShape for options
+ * @param props - Command properties (name, description, args, opts, action)
+ * @returns A Commander Command instance
+ */
 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

@@ -5,8 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (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 utils_1 = __importDefault(require("./utils"));
 const zodParser = (zod, opt) => (value) => {
     const result = zod.safeParse(value);
     if (result.success)
@@ -16,38 +15,67 @@ const zodParser = (zod, opt) => (value) => {
         throw new commander_1.InvalidOptionArgumentError(msg);
     throw new commander_1.InvalidArgumentError(msg);
 };
+/**
+ * Creates a Commander.js Argument from a Zod schema.
+ * Handles optionality, default values, and enum choices.
+ * @param key - The argument name
+ * @param zod - The Zod schema for the argument
+ * @returns A Commander Argument instance
+ */
 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);
+    const arg = new commander_1.Argument(flag, zod.description);
+    const def = utils_1.default.zodDefault(zod);
+    if (def !== undefined)
+        arg.default(zod.parse(def));
+    const choices = utils_1.default.zodEnumVals(zod);
     if (choices)
         arg.choices(choices);
-    return arg;
+    // parsing must be done at the end to override default parsers
+    return arg.argParser(zodParser(zod));
 };
 exports.zodArgument = zodArgument;
+/**
+ * Creates a Commander.js Option from a Zod schema.
+ * Handles optionality, default values, enum choices, and boolean flags.
+ * Supports short flags via description prefix (e.g., 's;...').
+ * @param key - The option name (can include underscores for grouping)
+ * @param zod - The Zod schema for the option
+ * @returns A Commander Option instance
+ */
 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 isBoolean = utils_1.default.zodIsBoolean(zod);
+    const flag = `--${key}${isBoolean ? '' : ` <${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)));
+    const opt = new commander_1.Option(flags, description);
+    // required for boolean flags
     if (isBoolean)
         opt.optional = true;
-    const choices = utis_1.default.zodEnumVals(zod);
+    else if (!zod.isOptional())
+        opt.makeOptionMandatory();
+    const def = utils_1.default.zodDefault(zod);
+    if (def !== undefined)
+        opt.default(zod.parse(def));
+    const choices = utils_1.default.zodEnumVals(zod);
     if (choices)
         opt.choices(choices);
-    return opt;
+    // parsing must be done at the end to override default parsers
+    return opt.argParser(zodParser(zod, 'opt'));
 };
 exports.zodOption = zodOption;
+/**
+ * Defines a Commander.js Command using Zod schemas for arguments and options.
+ * Automatically wires up parsing, validation, and help configuration.
+ * @template A - ZodRawShape for arguments
+ * @template O - ZodRawShape for options
+ * @param props - Command properties (name, description, args, opts, action)
+ * @returns A Commander Command instance
+ */
 const zodCommand = ({ name, description, args, opts, action, }) => {
     const command = new commander_1.Command(name);
     if (description)
@@ -61,7 +89,6 @@ const zodCommand = ({ name, description, args, opts, action, }) => {
         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 → utils.d.ts}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-commander",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "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",
@@ -16,16 +16,15 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.0.6",
-    "@types/lodash": "^4.17.20",
+    "@jest/globals": "^30.0.4",
+    "@types/node": "^22.16.3",
     "commander": "^14.0.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.1.2",
+    "jest": "^30.0.4",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.8.3",
     "zod": "^3.25.0"
   },
-  "dependencies": {
-    "lodash": "^4.17.21"
-  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -38,10 +37,8 @@
   "files": [
     "dist/"
   ],
-  "lint-staged": {
-    "*.ts": [
-      "tsc --noEmit && biome ci --threads=4"
-    ]
+  "imports": {
+    "#/*": "./src/*"
   },
   "publishConfig": {
     "access": "public"
@@ -51,10 +48,11 @@
     "zod": ">=3.20.0 <4"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc --project tsconfig.build.json",
     "lint": "biome check .",
     "lint:fix": "biome check --fix --formatter-enabled=false .",
     "format": "biome format --write .",
-    "ci": "biome ci --threads=4"
+    "ci": "biome ci --threads=4",
+    "test": "jest"
   }
 }