@optique/zod 0.7.0-dev.1 → 0.7.0-dev.144

package/dist/index.cjs

@@ -25,12 +25,78 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
 
 //#region src/index.ts
 /**
+* Infers an appropriate metavar string from a Zod schema.
+*
+* This function analyzes the Zod schema's internal structure to determine
+* the most appropriate metavar string for help text generation.
+*
+* @param schema A Zod schema to analyze.
+* @returns The inferred metavar string.
+*
+* @example
+* ```typescript
+* inferMetavar(z.string())              // "STRING"
+* inferMetavar(z.string().email())      // "EMAIL"
+* inferMetavar(z.coerce.number())       // "NUMBER"
+* inferMetavar(z.coerce.number().int()) // "INTEGER"
+* inferMetavar(z.enum(["a", "b"]))      // "CHOICE"
+* ```
+*
+* @since 0.7.0
+*/
+function inferMetavar(schema) {
+	const def = schema._def;
+	if (!def) return "VALUE";
+	const typeName = def.typeName || def.type;
+	if (typeName === "ZodString" || typeName === "string") {
+		if (Array.isArray(def.checks)) for (const check of def.checks) {
+			const kind = check.kind || check.format;
+			if (kind === "email") return "EMAIL";
+			if (kind === "url") return "URL";
+			if (kind === "uuid") return "UUID";
+			if (kind === "datetime") return "DATETIME";
+			if (kind === "date") return "DATE";
+			if (kind === "time") return "TIME";
+			if (kind === "duration") return "DURATION";
+			if (kind === "ip") return check.version === "v4" ? "IPV4" : check.version === "v6" ? "IPV6" : "IP";
+			if (kind === "jwt") return "JWT";
+			if (kind === "emoji") return "EMOJI";
+			if (kind === "cuid") return "CUID";
+			if (kind === "cuid2") return "CUID2";
+			if (kind === "ulid") return "ULID";
+			if (kind === "base64") return "BASE64";
+		}
+		return "STRING";
+	}
+	if (typeName === "ZodNumber" || typeName === "number") {
+		if (Array.isArray(def.checks)) {
+			for (const check of def.checks) if (check.kind === "int" || check.isInt === true || check.format === "safeint") return "INTEGER";
+		}
+		return "NUMBER";
+	}
+	if (typeName === "ZodBoolean" || typeName === "boolean") return "BOOLEAN";
+	if (typeName === "ZodDate" || typeName === "date") return "DATE";
+	if (typeName === "ZodEnum" || typeName === "enum" || typeName === "ZodNativeEnum" || typeName === "nativeEnum") return "CHOICE";
+	if (typeName === "ZodUnion" || typeName === "union" || typeName === "ZodLiteral" || typeName === "literal") return "VALUE";
+	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable") return inferMetavar(def.innerType);
+	if (typeName === "ZodDefault" || typeName === "default") return inferMetavar(def.innerType);
+	return "VALUE";
+}
+/**
 * Creates a value parser from a Zod schema.
 *
 * This parser validates CLI argument strings using Zod schemas, enabling
 * powerful validation and transformation capabilities for command-line
 * interfaces.
 *
+* The metavar is automatically inferred from the schema type unless explicitly
+* provided in options. For example:
+* - `z.string()` → `"STRING"`
+* - `z.string().email()` → `"EMAIL"`
+* - `z.coerce.number()` → `"NUMBER"`
+* - `z.coerce.number().int()` → `"INTEGER"`
+* - `z.enum([...])` → `"CHOICE"`
+*
 * @template T The output type of the Zod schema.
 * @param schema A Zod schema to validate input against.
 * @param options Optional configuration for the parser.
@@ -88,7 +154,7 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
 */
 function zod(schema, options = {}) {
 	return {
-		metavar: options.metavar ?? "VALUE",
+		metavar: options.metavar ?? inferMetavar(schema),
 		parse(input) {
 			const result = schema.safeParse(input);
 			if (result.success) return {

package/dist/index.d.cts

@@ -36,6 +36,14 @@ interface ZodParserOptions {
  * powerful validation and transformation capabilities for command-line
  * interfaces.
  *
+ * The metavar is automatically inferred from the schema type unless explicitly
+ * provided in options. For example:
+ * - `z.string()` → `"STRING"`
+ * - `z.string().email()` → `"EMAIL"`
+ * - `z.coerce.number()` → `"NUMBER"`
+ * - `z.coerce.number().int()` → `"INTEGER"`
+ * - `z.enum([...])` → `"CHOICE"`
+ *
  * @template T The output type of the Zod schema.
  * @param schema A Zod schema to validate input against.
  * @param options Optional configuration for the parser.

package/dist/index.d.ts

@@ -36,6 +36,14 @@ interface ZodParserOptions {
  * powerful validation and transformation capabilities for command-line
  * interfaces.
  *
+ * The metavar is automatically inferred from the schema type unless explicitly
+ * provided in options. For example:
+ * - `z.string()` → `"STRING"`
+ * - `z.string().email()` → `"EMAIL"`
+ * - `z.coerce.number()` → `"NUMBER"`
+ * - `z.coerce.number().int()` → `"INTEGER"`
+ * - `z.enum([...])` → `"CHOICE"`
+ *
  * @template T The output type of the Zod schema.
  * @param schema A Zod schema to validate input against.
  * @param options Optional configuration for the parser.

package/dist/index.js

@@ -2,12 +2,78 @@ import { message } from "@optique/core/message";
 
 //#region src/index.ts
 /**
+* Infers an appropriate metavar string from a Zod schema.
+*
+* This function analyzes the Zod schema's internal structure to determine
+* the most appropriate metavar string for help text generation.
+*
+* @param schema A Zod schema to analyze.
+* @returns The inferred metavar string.
+*
+* @example
+* ```typescript
+* inferMetavar(z.string())              // "STRING"
+* inferMetavar(z.string().email())      // "EMAIL"
+* inferMetavar(z.coerce.number())       // "NUMBER"
+* inferMetavar(z.coerce.number().int()) // "INTEGER"
+* inferMetavar(z.enum(["a", "b"]))      // "CHOICE"
+* ```
+*
+* @since 0.7.0
+*/
+function inferMetavar(schema) {
+	const def = schema._def;
+	if (!def) return "VALUE";
+	const typeName = def.typeName || def.type;
+	if (typeName === "ZodString" || typeName === "string") {
+		if (Array.isArray(def.checks)) for (const check of def.checks) {
+			const kind = check.kind || check.format;
+			if (kind === "email") return "EMAIL";
+			if (kind === "url") return "URL";
+			if (kind === "uuid") return "UUID";
+			if (kind === "datetime") return "DATETIME";
+			if (kind === "date") return "DATE";
+			if (kind === "time") return "TIME";
+			if (kind === "duration") return "DURATION";
+			if (kind === "ip") return check.version === "v4" ? "IPV4" : check.version === "v6" ? "IPV6" : "IP";
+			if (kind === "jwt") return "JWT";
+			if (kind === "emoji") return "EMOJI";
+			if (kind === "cuid") return "CUID";
+			if (kind === "cuid2") return "CUID2";
+			if (kind === "ulid") return "ULID";
+			if (kind === "base64") return "BASE64";
+		}
+		return "STRING";
+	}
+	if (typeName === "ZodNumber" || typeName === "number") {
+		if (Array.isArray(def.checks)) {
+			for (const check of def.checks) if (check.kind === "int" || check.isInt === true || check.format === "safeint") return "INTEGER";
+		}
+		return "NUMBER";
+	}
+	if (typeName === "ZodBoolean" || typeName === "boolean") return "BOOLEAN";
+	if (typeName === "ZodDate" || typeName === "date") return "DATE";
+	if (typeName === "ZodEnum" || typeName === "enum" || typeName === "ZodNativeEnum" || typeName === "nativeEnum") return "CHOICE";
+	if (typeName === "ZodUnion" || typeName === "union" || typeName === "ZodLiteral" || typeName === "literal") return "VALUE";
+	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable") return inferMetavar(def.innerType);
+	if (typeName === "ZodDefault" || typeName === "default") return inferMetavar(def.innerType);
+	return "VALUE";
+}
+/**
 * Creates a value parser from a Zod schema.
 *
 * This parser validates CLI argument strings using Zod schemas, enabling
 * powerful validation and transformation capabilities for command-line
 * interfaces.
 *
+* The metavar is automatically inferred from the schema type unless explicitly
+* provided in options. For example:
+* - `z.string()` → `"STRING"`
+* - `z.string().email()` → `"EMAIL"`
+* - `z.coerce.number()` → `"NUMBER"`
+* - `z.coerce.number().int()` → `"INTEGER"`
+* - `z.enum([...])` → `"CHOICE"`
+*
 * @template T The output type of the Zod schema.
 * @param schema A Zod schema to validate input against.
 * @param options Optional configuration for the parser.
@@ -65,7 +131,7 @@ import { message } from "@optique/core/message";
 */
 function zod(schema, options = {}) {
 	return {
-		metavar: options.metavar ?? "VALUE",
+		metavar: options.metavar ?? inferMetavar(schema),
 		parse(input) {
 			const result = schema.safeParse(input);
 			if (result.success) return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/zod",
-  "version": "0.7.0-dev.1",
+  "version": "0.7.0-dev.144+da70df70",
   "description": "Zod value parsers for Optique",
   "keywords": [
     "CLI",
@@ -63,7 +63,7 @@
     "@types/node": "^20.19.9",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "zod": "^4.0.1"
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "scripts": {
     "build": "tsdown",