@optique/zod 1.0.0-dev.921 → 1.0.0

package/README.md

@@ -37,7 +37,9 @@ import { z } from "zod";
 
 const cli = run(
   object({
-    email: option("--email", zod(z.string().email())),
+    email: option("--email",
+      zod(z.string().email(), { placeholder: "" }),
+    ),
   }),
 );
 
@@ -65,7 +67,9 @@ import { option } from "@optique/core/primitives";
 import { zod } from "@optique/zod";
 import { z } from "zod";
 
-const email = option("--email", zod(z.string().email()));
+const email = option("--email",
+  zod(z.string().email(), { placeholder: "" }),
+);
 ~~~~
 
 ### URL validation
@@ -75,7 +79,9 @@ import { option } from "@optique/core/primitives";
 import { zod } from "@optique/zod";
 import { z } from "zod";
 
-const url = option("--url", zod(z.string().url()));
+const url = option("--url",
+  zod(z.string().url(), { placeholder: "" }),
+);
 ~~~~
 
 ### Port numbers with range validation
@@ -90,7 +96,7 @@ import { zod } from "@optique/zod";
 import { z } from "zod";
 
 const port = option("-p", "--port",
-  zod(z.coerce.number().int().min(1024).max(65535))
+  zod(z.coerce.number().int().min(1024).max(65535), { placeholder: 1024 }),
 );
 ~~~~
 
@@ -102,7 +108,7 @@ import { zod } from "@optique/zod";
 import { z } from "zod";
 
 const logLevel = option("--log-level",
-  zod(z.enum(["debug", "info", "warn", "error"]))
+  zod(z.enum(["debug", "info", "warn", "error"]), { placeholder: "debug" }),
 );
 ~~~~
 
@@ -114,7 +120,7 @@ import { zod } from "@optique/zod";
 import { z } from "zod";
 
 const startDate = argument(
-  zod(z.string().transform((s) => new Date(s)))
+  zod(z.string().transform((s) => new Date(s)), { placeholder: new Date(0) }),
 );
 ~~~~
 
@@ -131,6 +137,7 @@ import { message } from "@optique/core/message";
 import { z } from "zod";
 
 const email = option("--email", zod(z.string().email(), {
+  placeholder: "",
   metavar: "EMAIL",
   errors: {
     zodError: (error, input) =>
@@ -154,7 +161,7 @@ import { zod } from "@optique/zod";
 import { z } from "zod";
 
 // ✅ Correct
-const port = option("-p", zod(z.coerce.number()));
+const port = option("-p", zod(z.coerce.number(), { placeholder: 0 }));
 
 // ❌ Won't work (CLI arguments are always strings)
 // const port = option("-p", zod(z.number()));
@@ -172,7 +179,8 @@ import { z } from "zod";
 
 // ❌ Not supported
 const email = option("--email",
-  zod(z.string().refine(async (val) => await checkDB(val)))
+  zod(z.string().refine(async (val) => await checkDB(val)),
+    { placeholder: "" }),
 );
 ~~~~
 

package/dist/index.cjs

@@ -22,9 +22,136 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __optique_core_message = __toESM(require("@optique/core/message"));
+const __optique_core_nonempty = __toESM(require("@optique/core/nonempty"));
+const zod = __toESM(require("zod"));
 
 //#region src/index.ts
 /**
+* Checks whether the given error is a Zod async-parse error.
+*
+* - **Zod v4** throws a dedicated `$ZodAsyncError` class.
+* - **Zod v3** (3.25+) throws a plain `Error` whose message starts with
+*   `"Async refinement encountered during synchronous parse operation"` for
+*   async refinements, or `"Asynchronous transform encountered during
+*   synchronous parse operation"` for async transforms.
+*/
+function isZodAsyncError(error) {
+	if (error.constructor.name === "$ZodAsyncError") return true;
+	if (error.message === "Async refinement encountered during synchronous parse operation. Use .parseAsync instead." || error.message === "Asynchronous transform encountered during synchronous parse operation. Use .parseAsync instead." || error.message === "Synchronous parse encountered promise.") return true;
+	return false;
+}
+const BOOL_TRUE_LITERALS = [
+	"true",
+	"1",
+	"yes",
+	"on"
+];
+const BOOL_FALSE_LITERALS = [
+	"false",
+	"0",
+	"no",
+	"off"
+];
+/**
+* Analyzes whether the given Zod schema represents a boolean type,
+* unwrapping all known Zod wrappers.  Also determines whether it is
+* safe to expose `choices` and `suggest()` — wrappers that can narrow
+* the accepted domain (effects, catch) suppress choice exposure.
+*/
+function analyzeBooleanSchema(schema) {
+	const result = analyzeBooleanInner(schema, true, /* @__PURE__ */ new WeakSet());
+	if (!result.isBoolean) return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+	return result;
+}
+function analyzeBooleanInner(schema, canExposeChoices, visited) {
+	if (visited.has(schema)) return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+	visited.add(schema);
+	const def = schema._def;
+	if (!def) return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+	const typeName = def.typeName ?? def.type;
+	if (typeName === "ZodBoolean" || typeName === "boolean") {
+		const hasCustomChecks = Array.isArray(def.checks) && def.checks.some((c) => c.kind === "custom" || c.type === "custom" || c._zod?.def?.check === "custom");
+		return {
+			isBoolean: true,
+			exposeChoices: canExposeChoices && !hasCustomChecks,
+			isCoerced: def.coerce === true
+		};
+	}
+	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable" || typeName === "ZodDefault" || typeName === "default" || typeName === "ZodReadonly" || typeName === "readonly" || typeName === "prefault" || typeName === "nonoptional") {
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, canExposeChoices, visited);
+	}
+	if (typeName === "ZodLazy" || typeName === "lazy") {
+		if (typeof def.getter === "function") return analyzeBooleanInner(def.getter(), canExposeChoices, visited);
+	}
+	if (typeName === "ZodEffects" || typeName === "effects") {
+		if (def.effect?.type === "preprocess") return {
+			isBoolean: false,
+			exposeChoices: false,
+			isCoerced: false
+		};
+		const innerSchema = def.schema;
+		if (innerSchema != null) return analyzeBooleanInner(innerSchema, false, visited);
+	}
+	if (typeName === "ZodCatch" || typeName === "catch") {
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	if (typeName === "ZodBranded" || typeName === "branded") {
+		const innerType = def.innerType ?? (typeof def.type === "object" && def.type != null ? def.type : void 0);
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	if (typeName === "pipe" || typeName === "ZodPipeline") {
+		const inSchema = def.in;
+		if (inSchema != null) return analyzeBooleanInner(inSchema, false, visited);
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	if (typeName === "pipeline") {
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+}
+/**
+* Pre-converts a CLI string input to an actual boolean value using
+* CLI-friendly literals (true/false, 1/0, yes/no, on/off).
+*/
+function preConvertBoolean(input) {
+	const normalized = input.trim().toLowerCase();
+	if (BOOL_TRUE_LITERALS.includes(normalized)) return {
+		success: true,
+		value: true
+	};
+	if (BOOL_FALSE_LITERALS.includes(normalized)) return {
+		success: true,
+		value: false
+	};
+	return {
+		success: false,
+		error: __optique_core_message.message`Invalid Boolean value: ${input}. Expected one of ${(0, __optique_core_message.valueSet)([...BOOL_TRUE_LITERALS, ...BOOL_FALSE_LITERALS], {
+			fallback: "",
+			locale: "en-US"
+		})}.`
+	};
+}
+/**
 * Infers an appropriate metavar string from a Zod schema.
 *
 * This function analyzes the Zod schema's internal structure to determine
@@ -47,7 +174,7 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
 function inferMetavar(schema) {
 	const def = schema._def;
 	if (!def) return "VALUE";
-	const typeName = def.typeName || def.type;
+	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;
@@ -76,8 +203,15 @@ function inferMetavar(schema) {
 	}
 	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 === "ZodEnum" || typeName === "enum" || typeName === "ZodNativeEnum" || typeName === "nativeEnum") return inferChoices(schema) != null ? "CHOICE" : "VALUE";
+	if (typeName === "ZodLiteral" || typeName === "literal") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
+	if (typeName === "ZodUnion" || typeName === "union") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
 	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable") {
 		const innerType = def.innerType;
 		if (innerType != null) return inferMetavar(innerType);
@@ -91,6 +225,70 @@ function inferMetavar(schema) {
 	return "VALUE";
 }
 /**
+* Extracts valid choices from a Zod schema that represents a fixed set of
+* values (enum, literal, or union of literals).
+*
+* @param schema A Zod schema to analyze.
+* @returns An array of string representations of valid choices, or `undefined`
+*          if the schema does not represent a fixed set of values.
+*/
+function inferChoices(schema) {
+	const def = schema._def;
+	if (!def) return void 0;
+	const typeName = def.typeName ?? def.type;
+	if (typeName === "ZodEnum" || typeName === "enum") {
+		const values = def.values;
+		if (Array.isArray(values)) return values.map(String);
+		const entries = def.entries;
+		if (entries != null && typeof entries === "object") {
+			const result = /* @__PURE__ */ new Set();
+			for (const val of Object.values(entries)) if (typeof val === "string") result.add(val);
+			else return void 0;
+			return result.size > 0 ? [...result] : void 0;
+		}
+		return void 0;
+	}
+	if (typeName === "ZodNativeEnum" || typeName === "nativeEnum") {
+		const values = def.values;
+		if (values != null && typeof values === "object" && !Array.isArray(values)) {
+			const result = /* @__PURE__ */ new Set();
+			for (const val of Object.values(values)) if (typeof val === "string") result.add(val);
+			else return void 0;
+			return result.size > 0 ? [...result] : void 0;
+		}
+		return void 0;
+	}
+	if (typeName === "ZodLiteral" || typeName === "literal") {
+		const value = def.value;
+		if (typeof value === "string") return [value];
+		const values = def.values;
+		if (Array.isArray(values)) {
+			const result = [];
+			for (const v of values) if (typeof v === "string") result.push(v);
+			else return void 0;
+			return result.length > 0 ? result : void 0;
+		}
+		return void 0;
+	}
+	if (typeName === "ZodUnion" || typeName === "union") {
+		const options = def.options;
+		if (!Array.isArray(options)) return void 0;
+		const allChoices = /* @__PURE__ */ new Set();
+		for (const opt of options) {
+			const sub = inferChoices(opt);
+			if (sub == null) return void 0;
+			for (const choice of sub) allChoices.add(choice);
+		}
+		return allChoices.size > 0 ? [...allChoices] : void 0;
+	}
+	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable" || typeName === "ZodDefault" || typeName === "default") {
+		const innerType = def.innerType;
+		if (innerType != null) return inferChoices(innerType);
+		return void 0;
+	}
+	return void 0;
+}
+/**
 * Creates a value parser from a Zod schema.
 *
 * This parser validates CLI argument strings using Zod schemas, enabling
@@ -107,7 +305,8 @@ function inferMetavar(schema) {
 *
 * @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.
+* @param options Configuration for the parser, including a required
+*   `placeholder` value used during deferred prompt resolution.
 * @returns A value parser that validates inputs using the provided schema.
 *
 * @example Basic string validation
@@ -116,7 +315,9 @@ function inferMetavar(schema) {
 * import { zod } from "@optique/zod";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", zod(z.string().email()));
+* const email = option("--email",
+*   zod(z.string().email(), { placeholder: "" }),
+* );
 * ```
 *
 * @example Number validation with coercion
@@ -127,7 +328,7 @@ function inferMetavar(schema) {
 *
 * // Use z.coerce for non-string types since CLI args are always strings
 * const port = option("-p", "--port",
-*   zod(z.coerce.number().int().min(1024).max(65535))
+*   zod(z.coerce.number().int().min(1024).max(65535), { placeholder: 1024 }),
 * );
 * ```
 *
@@ -138,7 +339,7 @@ function inferMetavar(schema) {
 * import { option } from "@optique/core/primitives";
 *
 * const logLevel = option("--log-level",
-*   zod(z.enum(["debug", "info", "warn", "error"]))
+*   zod(z.enum(["debug", "info", "warn", "error"]), { placeholder: "debug" }),
 * );
 * ```
 *
@@ -149,50 +350,140 @@ function inferMetavar(schema) {
 * import { message } from "@optique/core/message";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", zod(z.string().email(), {
-*   metavar: "EMAIL",
-*   errors: {
-*     zodError: (error, input) =>
-*       message`Please provide a valid email address, got ${input}.`
-*   }
-* }));
+* const email = option("--email",
+*   zod(z.string().email(), {
+*     placeholder: "",
+*     metavar: "EMAIL",
+*     errors: {
+*       zodError: (error, input) =>
+*         message`Please provide a valid email address, got ${input}.`
+*     },
+*   }),
+* );
 * ```
 *
+* @throws {TypeError} If `options` is missing, not an object, or does not
+*   include `placeholder`.
+* @throws {TypeError} If the resolved `metavar` is an empty string.
+* @throws {TypeError} If the schema contains async refinements or other async
+*   operations that cannot be executed synchronously.
 * @since 0.7.0
 */
-function zod(schema, options = {}) {
-	return {
-		$mode: "sync",
-		metavar: options.metavar ?? inferMetavar(schema),
-		parse(input) {
-			const result = schema.safeParse(input);
-			if (result.success) return {
-				success: true,
-				value: result.data
+function zod$1(schema, options) {
+	if (options == null || typeof options !== "object") throw new TypeError("zod() requires an options object with a placeholder property.");
+	if (!("placeholder" in options)) throw new TypeError("zod() options must include a placeholder property.");
+	const choices = inferChoices(schema);
+	const boolInfo = analyzeBooleanSchema(schema);
+	const metavar = options.metavar ?? (boolInfo.isBoolean ? "BOOLEAN" : inferMetavar(schema));
+	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
+	function doSafeParse(input, rawInput) {
+		let result;
+		try {
+			result = schema.safeParse(input);
+		} catch (error) {
+			if (error instanceof Error && isZodAsyncError(error)) throw new TypeError("Async Zod schemas (e.g., async refinements) are not supported by zod(). Use synchronous schemas instead.");
+			throw error;
+		}
+		if (result.success) return {
+			success: true,
+			value: result.data
+		};
+		if (options.errors?.zodError) return {
+			success: false,
+			error: typeof options.errors.zodError === "function" ? options.errors.zodError(result.error, rawInput) : options.errors.zodError
+		};
+		const zodModule = schema;
+		if (typeof zodModule.constructor?.prettifyError === "function") try {
+			const pretty = zodModule.constructor.prettifyError(result.error);
+			return {
+				success: false,
+				error: __optique_core_message.message`${pretty}`
 			};
-			if (options.errors?.zodError) return {
+		} catch {}
+		const firstError = result.error.issues[0];
+		return {
+			success: false,
+			error: __optique_core_message.message`${firstError?.message ?? "Validation failed"}`
+		};
+	}
+	/**
+	* Handles a failed boolean literal pre-conversion.
+	*
+	*  -  *Non-coerced* (`z.boolean()`): falls through to `doSafeParse`
+	*     so that catch/default, custom errors, and async detection all
+	*     work.  This is safe because `safeParse(string)` fails at the
+	*     type level before any refinements execute.
+	*  -  *Coerced* (`z.coerce.boolean()`): runs the lazy async probe
+	*     (if not yet completed), then returns the pre-conversion error
+	*     or delegates to the custom `zodError` callback.
+	*/
+	function handleBooleanLiteralError(boolResult, rawInput) {
+		if (!boolInfo.isCoerced) return doSafeParse(rawInput, rawInput);
+		if (options.errors?.zodError) {
+			if (typeof options.errors.zodError !== "function") return {
 				success: false,
-				error: typeof options.errors.zodError === "function" ? options.errors.zodError(result.error, input) : options.errors.zodError
+				error: options.errors.zodError
 			};
-			const zodModule = schema;
-			if (typeof zodModule.constructor?.prettifyError === "function") try {
-				const pretty = zodModule.constructor.prettifyError(result.error);
-				return {
-					success: false,
-					error: __optique_core_message.message`${pretty}`
-				};
-			} catch {}
-			const firstError = result.error.issues[0];
+			const zodError = new zod.ZodError([{
+				code: "invalid_type",
+				expected: "boolean",
+				message: `Invalid Boolean value: ${rawInput}`,
+				path: []
+			}]);
 			return {
 				success: false,
-				error: __optique_core_message.message`${firstError?.message ?? "Validation failed"}`
+				error: options.errors.zodError(zodError, rawInput)
 			};
+		}
+		return boolResult;
+	}
+	const parser = {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder,
+		...boolInfo.exposeChoices ? {
+			choices: Object.freeze([true, false]),
+			suggest(prefix) {
+				const allLiterals = [...BOOL_TRUE_LITERALS, ...BOOL_FALSE_LITERALS];
+				const normalizedPrefix = prefix.toLowerCase();
+				return allLiterals.filter((lit) => lit.startsWith(normalizedPrefix)).map((lit) => ({
+					kind: "literal",
+					text: lit
+				}));
+			}
+		} : choices != null && choices.length > 0 ? {
+			choices: Object.freeze(choices),
+			*suggest(prefix) {
+				for (const c of choices) if (c.startsWith(prefix)) yield {
+					kind: "literal",
+					text: c
+				};
+			}
+		} : {},
+		parse(input) {
+			if (boolInfo.isBoolean) {
+				const boolResult = preConvertBoolean(input);
+				if (!boolResult.success) return handleBooleanLiteralError(boolResult, input);
+				return doSafeParse(boolResult.value, input);
+			}
+			return doSafeParse(input, input);
 		},
 		format(value) {
-			return String(value);
+			if (options.format) return options.format(value);
+			if (value instanceof Date) return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
+			if (typeof value !== "object" || value === null) return String(value);
+			if (Array.isArray(value)) return String(value);
+			const str = String(value);
+			if (str !== "[object Object]") return str;
+			const proto = Object.getPrototypeOf(value);
+			if (proto === Object.prototype || proto === null) try {
+				return JSON.stringify(value) ?? str;
+			} catch {}
+			return str;
 		}
 	};
+	return parser;
 }
 
 //#endregion
-exports.zod = zod;
+exports.zod = zod$1;

package/dist/index.d.cts

@@ -8,7 +8,7 @@ import { z } from "zod";
  * Options for creating a Zod value parser.
  * @since 0.7.0
  */
-interface ZodParserOptions {
+interface ZodParserOptions<T = unknown> {
   /**
    * The metavariable name for this parser. This is used in help messages to
    * indicate what kind of value this parser expects. Usually a single
@@ -16,6 +16,25 @@ interface ZodParserOptions {
    * @default `"VALUE"`
    */
   readonly metavar?: NonEmptyString;
+  /**
+   * A phase-one stand-in value of type `T` used during deferred prompt
+   * resolution.  Because the output type of a Zod schema cannot be
+   * inferred to a concrete default, callers must provide this explicitly.
+   * @since 1.0.0
+   */
+  readonly placeholder: T;
+  /**
+   * Custom formatter for displaying parsed values in help messages.
+   * When not provided, the default formatter is used: primitives use
+   * `String()`, valid `Date` values use `.toISOString()`, and plain
+   * objects use `JSON.stringify()`.  All other objects (arrays, class
+   * instances, etc.) use `String()`.
+   *
+   * @param value The parsed value to format.
+   * @returns A string representation of the value.
+   * @since 1.0.0
+   */
+  readonly format?: (value: T) => string;
   /**
    * Custom error messages for Zod validation failures.
    */
@@ -46,7 +65,8 @@ interface ZodParserOptions {
  *
  * @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.
+ * @param options Configuration for the parser, including a required
+ *   `placeholder` value used during deferred prompt resolution.
  * @returns A value parser that validates inputs using the provided schema.
  *
  * @example Basic string validation
@@ -55,7 +75,9 @@ interface ZodParserOptions {
  * import { zod } from "@optique/zod";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", zod(z.string().email()));
+ * const email = option("--email",
+ *   zod(z.string().email(), { placeholder: "" }),
+ * );
  * ```
  *
  * @example Number validation with coercion
@@ -66,7 +88,7 @@ interface ZodParserOptions {
  *
  * // Use z.coerce for non-string types since CLI args are always strings
  * const port = option("-p", "--port",
- *   zod(z.coerce.number().int().min(1024).max(65535))
+ *   zod(z.coerce.number().int().min(1024).max(65535), { placeholder: 1024 }),
  * );
  * ```
  *
@@ -77,7 +99,7 @@ interface ZodParserOptions {
  * import { option } from "@optique/core/primitives";
  *
  * const logLevel = option("--log-level",
- *   zod(z.enum(["debug", "info", "warn", "error"]))
+ *   zod(z.enum(["debug", "info", "warn", "error"]), { placeholder: "debug" }),
  * );
  * ```
  *
@@ -88,17 +110,25 @@ interface ZodParserOptions {
  * import { message } from "@optique/core/message";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", zod(z.string().email(), {
- *   metavar: "EMAIL",
- *   errors: {
- *     zodError: (error, input) =>
- *       message`Please provide a valid email address, got ${input}.`
- *   }
- * }));
+ * const email = option("--email",
+ *   zod(z.string().email(), {
+ *     placeholder: "",
+ *     metavar: "EMAIL",
+ *     errors: {
+ *       zodError: (error, input) =>
+ *         message`Please provide a valid email address, got ${input}.`
+ *     },
+ *   }),
+ * );
  * ```
  *
+ * @throws {TypeError} If `options` is missing, not an object, or does not
+ *   include `placeholder`.
+ * @throws {TypeError} If the resolved `metavar` is an empty string.
+ * @throws {TypeError} If the schema contains async refinements or other async
+ *   operations that cannot be executed synchronously.
  * @since 0.7.0
  */
-declare function zod<T>(schema: z.Schema<T>, options?: ZodParserOptions): ValueParser<"sync", T>;
+declare function zod<T>(schema: z.Schema<T>, options: ZodParserOptions<T>): ValueParser<"sync", T>;
 //#endregion
 export { ZodParserOptions, zod };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Message } from "@optique/core/message";
-import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
 import { z } from "zod";
+import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
 
 //#region src/index.d.ts
 
@@ -8,7 +8,7 @@ import { z } from "zod";
  * Options for creating a Zod value parser.
  * @since 0.7.0
  */
-interface ZodParserOptions {
+interface ZodParserOptions<T = unknown> {
   /**
    * The metavariable name for this parser. This is used in help messages to
    * indicate what kind of value this parser expects. Usually a single
@@ -16,6 +16,25 @@ interface ZodParserOptions {
    * @default `"VALUE"`
    */
   readonly metavar?: NonEmptyString;
+  /**
+   * A phase-one stand-in value of type `T` used during deferred prompt
+   * resolution.  Because the output type of a Zod schema cannot be
+   * inferred to a concrete default, callers must provide this explicitly.
+   * @since 1.0.0
+   */
+  readonly placeholder: T;
+  /**
+   * Custom formatter for displaying parsed values in help messages.
+   * When not provided, the default formatter is used: primitives use
+   * `String()`, valid `Date` values use `.toISOString()`, and plain
+   * objects use `JSON.stringify()`.  All other objects (arrays, class
+   * instances, etc.) use `String()`.
+   *
+   * @param value The parsed value to format.
+   * @returns A string representation of the value.
+   * @since 1.0.0
+   */
+  readonly format?: (value: T) => string;
   /**
    * Custom error messages for Zod validation failures.
    */
@@ -46,7 +65,8 @@ interface ZodParserOptions {
  *
  * @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.
+ * @param options Configuration for the parser, including a required
+ *   `placeholder` value used during deferred prompt resolution.
  * @returns A value parser that validates inputs using the provided schema.
  *
  * @example Basic string validation
@@ -55,7 +75,9 @@ interface ZodParserOptions {
  * import { zod } from "@optique/zod";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", zod(z.string().email()));
+ * const email = option("--email",
+ *   zod(z.string().email(), { placeholder: "" }),
+ * );
  * ```
  *
  * @example Number validation with coercion
@@ -66,7 +88,7 @@ interface ZodParserOptions {
  *
  * // Use z.coerce for non-string types since CLI args are always strings
  * const port = option("-p", "--port",
- *   zod(z.coerce.number().int().min(1024).max(65535))
+ *   zod(z.coerce.number().int().min(1024).max(65535), { placeholder: 1024 }),
  * );
  * ```
  *
@@ -77,7 +99,7 @@ interface ZodParserOptions {
  * import { option } from "@optique/core/primitives";
  *
  * const logLevel = option("--log-level",
- *   zod(z.enum(["debug", "info", "warn", "error"]))
+ *   zod(z.enum(["debug", "info", "warn", "error"]), { placeholder: "debug" }),
  * );
  * ```
  *
@@ -88,17 +110,25 @@ interface ZodParserOptions {
  * import { message } from "@optique/core/message";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", zod(z.string().email(), {
- *   metavar: "EMAIL",
- *   errors: {
- *     zodError: (error, input) =>
- *       message`Please provide a valid email address, got ${input}.`
- *   }
- * }));
+ * const email = option("--email",
+ *   zod(z.string().email(), {
+ *     placeholder: "",
+ *     metavar: "EMAIL",
+ *     errors: {
+ *       zodError: (error, input) =>
+ *         message`Please provide a valid email address, got ${input}.`
+ *     },
+ *   }),
+ * );
  * ```
  *
+ * @throws {TypeError} If `options` is missing, not an object, or does not
+ *   include `placeholder`.
+ * @throws {TypeError} If the resolved `metavar` is an empty string.
+ * @throws {TypeError} If the schema contains async refinements or other async
+ *   operations that cannot be executed synchronously.
  * @since 0.7.0
  */
-declare function zod<T>(schema: z.Schema<T>, options?: ZodParserOptions): ValueParser<"sync", T>;
+declare function zod<T>(schema: z.Schema<T>, options: ZodParserOptions<T>): ValueParser<"sync", T>;
 //#endregion
 export { ZodParserOptions, zod };

package/dist/index.js

@@ -1,7 +1,134 @@
-import { message } from "@optique/core/message";
+import { message, valueSet } from "@optique/core/message";
+import { ensureNonEmptyString } from "@optique/core/nonempty";
+import { ZodError } from "zod";
 
 //#region src/index.ts
 /**
+* Checks whether the given error is a Zod async-parse error.
+*
+* - **Zod v4** throws a dedicated `$ZodAsyncError` class.
+* - **Zod v3** (3.25+) throws a plain `Error` whose message starts with
+*   `"Async refinement encountered during synchronous parse operation"` for
+*   async refinements, or `"Asynchronous transform encountered during
+*   synchronous parse operation"` for async transforms.
+*/
+function isZodAsyncError(error) {
+	if (error.constructor.name === "$ZodAsyncError") return true;
+	if (error.message === "Async refinement encountered during synchronous parse operation. Use .parseAsync instead." || error.message === "Asynchronous transform encountered during synchronous parse operation. Use .parseAsync instead." || error.message === "Synchronous parse encountered promise.") return true;
+	return false;
+}
+const BOOL_TRUE_LITERALS = [
+	"true",
+	"1",
+	"yes",
+	"on"
+];
+const BOOL_FALSE_LITERALS = [
+	"false",
+	"0",
+	"no",
+	"off"
+];
+/**
+* Analyzes whether the given Zod schema represents a boolean type,
+* unwrapping all known Zod wrappers.  Also determines whether it is
+* safe to expose `choices` and `suggest()` — wrappers that can narrow
+* the accepted domain (effects, catch) suppress choice exposure.
+*/
+function analyzeBooleanSchema(schema) {
+	const result = analyzeBooleanInner(schema, true, /* @__PURE__ */ new WeakSet());
+	if (!result.isBoolean) return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+	return result;
+}
+function analyzeBooleanInner(schema, canExposeChoices, visited) {
+	if (visited.has(schema)) return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+	visited.add(schema);
+	const def = schema._def;
+	if (!def) return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+	const typeName = def.typeName ?? def.type;
+	if (typeName === "ZodBoolean" || typeName === "boolean") {
+		const hasCustomChecks = Array.isArray(def.checks) && def.checks.some((c) => c.kind === "custom" || c.type === "custom" || c._zod?.def?.check === "custom");
+		return {
+			isBoolean: true,
+			exposeChoices: canExposeChoices && !hasCustomChecks,
+			isCoerced: def.coerce === true
+		};
+	}
+	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable" || typeName === "ZodDefault" || typeName === "default" || typeName === "ZodReadonly" || typeName === "readonly" || typeName === "prefault" || typeName === "nonoptional") {
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, canExposeChoices, visited);
+	}
+	if (typeName === "ZodLazy" || typeName === "lazy") {
+		if (typeof def.getter === "function") return analyzeBooleanInner(def.getter(), canExposeChoices, visited);
+	}
+	if (typeName === "ZodEffects" || typeName === "effects") {
+		if (def.effect?.type === "preprocess") return {
+			isBoolean: false,
+			exposeChoices: false,
+			isCoerced: false
+		};
+		const innerSchema = def.schema;
+		if (innerSchema != null) return analyzeBooleanInner(innerSchema, false, visited);
+	}
+	if (typeName === "ZodCatch" || typeName === "catch") {
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	if (typeName === "ZodBranded" || typeName === "branded") {
+		const innerType = def.innerType ?? (typeof def.type === "object" && def.type != null ? def.type : void 0);
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	if (typeName === "pipe" || typeName === "ZodPipeline") {
+		const inSchema = def.in;
+		if (inSchema != null) return analyzeBooleanInner(inSchema, false, visited);
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	if (typeName === "pipeline") {
+		const innerType = def.innerType;
+		if (innerType != null) return analyzeBooleanInner(innerType, false, visited);
+	}
+	return {
+		isBoolean: false,
+		exposeChoices: false,
+		isCoerced: false
+	};
+}
+/**
+* Pre-converts a CLI string input to an actual boolean value using
+* CLI-friendly literals (true/false, 1/0, yes/no, on/off).
+*/
+function preConvertBoolean(input) {
+	const normalized = input.trim().toLowerCase();
+	if (BOOL_TRUE_LITERALS.includes(normalized)) return {
+		success: true,
+		value: true
+	};
+	if (BOOL_FALSE_LITERALS.includes(normalized)) return {
+		success: true,
+		value: false
+	};
+	return {
+		success: false,
+		error: message`Invalid Boolean value: ${input}. Expected one of ${valueSet([...BOOL_TRUE_LITERALS, ...BOOL_FALSE_LITERALS], {
+			fallback: "",
+			locale: "en-US"
+		})}.`
+	};
+}
+/**
 * Infers an appropriate metavar string from a Zod schema.
 *
 * This function analyzes the Zod schema's internal structure to determine
@@ -24,7 +151,7 @@ import { message } from "@optique/core/message";
 function inferMetavar(schema) {
 	const def = schema._def;
 	if (!def) return "VALUE";
-	const typeName = def.typeName || def.type;
+	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;
@@ -53,8 +180,15 @@ function inferMetavar(schema) {
 	}
 	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 === "ZodEnum" || typeName === "enum" || typeName === "ZodNativeEnum" || typeName === "nativeEnum") return inferChoices(schema) != null ? "CHOICE" : "VALUE";
+	if (typeName === "ZodLiteral" || typeName === "literal") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
+	if (typeName === "ZodUnion" || typeName === "union") {
+		if (inferChoices(schema) != null) return "CHOICE";
+		return "VALUE";
+	}
 	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable") {
 		const innerType = def.innerType;
 		if (innerType != null) return inferMetavar(innerType);
@@ -68,6 +202,70 @@ function inferMetavar(schema) {
 	return "VALUE";
 }
 /**
+* Extracts valid choices from a Zod schema that represents a fixed set of
+* values (enum, literal, or union of literals).
+*
+* @param schema A Zod schema to analyze.
+* @returns An array of string representations of valid choices, or `undefined`
+*          if the schema does not represent a fixed set of values.
+*/
+function inferChoices(schema) {
+	const def = schema._def;
+	if (!def) return void 0;
+	const typeName = def.typeName ?? def.type;
+	if (typeName === "ZodEnum" || typeName === "enum") {
+		const values = def.values;
+		if (Array.isArray(values)) return values.map(String);
+		const entries = def.entries;
+		if (entries != null && typeof entries === "object") {
+			const result = /* @__PURE__ */ new Set();
+			for (const val of Object.values(entries)) if (typeof val === "string") result.add(val);
+			else return void 0;
+			return result.size > 0 ? [...result] : void 0;
+		}
+		return void 0;
+	}
+	if (typeName === "ZodNativeEnum" || typeName === "nativeEnum") {
+		const values = def.values;
+		if (values != null && typeof values === "object" && !Array.isArray(values)) {
+			const result = /* @__PURE__ */ new Set();
+			for (const val of Object.values(values)) if (typeof val === "string") result.add(val);
+			else return void 0;
+			return result.size > 0 ? [...result] : void 0;
+		}
+		return void 0;
+	}
+	if (typeName === "ZodLiteral" || typeName === "literal") {
+		const value = def.value;
+		if (typeof value === "string") return [value];
+		const values = def.values;
+		if (Array.isArray(values)) {
+			const result = [];
+			for (const v of values) if (typeof v === "string") result.push(v);
+			else return void 0;
+			return result.length > 0 ? result : void 0;
+		}
+		return void 0;
+	}
+	if (typeName === "ZodUnion" || typeName === "union") {
+		const options = def.options;
+		if (!Array.isArray(options)) return void 0;
+		const allChoices = /* @__PURE__ */ new Set();
+		for (const opt of options) {
+			const sub = inferChoices(opt);
+			if (sub == null) return void 0;
+			for (const choice of sub) allChoices.add(choice);
+		}
+		return allChoices.size > 0 ? [...allChoices] : void 0;
+	}
+	if (typeName === "ZodOptional" || typeName === "optional" || typeName === "ZodNullable" || typeName === "nullable" || typeName === "ZodDefault" || typeName === "default") {
+		const innerType = def.innerType;
+		if (innerType != null) return inferChoices(innerType);
+		return void 0;
+	}
+	return void 0;
+}
+/**
 * Creates a value parser from a Zod schema.
 *
 * This parser validates CLI argument strings using Zod schemas, enabling
@@ -84,7 +282,8 @@ function inferMetavar(schema) {
 *
 * @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.
+* @param options Configuration for the parser, including a required
+*   `placeholder` value used during deferred prompt resolution.
 * @returns A value parser that validates inputs using the provided schema.
 *
 * @example Basic string validation
@@ -93,7 +292,9 @@ function inferMetavar(schema) {
 * import { zod } from "@optique/zod";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", zod(z.string().email()));
+* const email = option("--email",
+*   zod(z.string().email(), { placeholder: "" }),
+* );
 * ```
 *
 * @example Number validation with coercion
@@ -104,7 +305,7 @@ function inferMetavar(schema) {
 *
 * // Use z.coerce for non-string types since CLI args are always strings
 * const port = option("-p", "--port",
-*   zod(z.coerce.number().int().min(1024).max(65535))
+*   zod(z.coerce.number().int().min(1024).max(65535), { placeholder: 1024 }),
 * );
 * ```
 *
@@ -115,7 +316,7 @@ function inferMetavar(schema) {
 * import { option } from "@optique/core/primitives";
 *
 * const logLevel = option("--log-level",
-*   zod(z.enum(["debug", "info", "warn", "error"]))
+*   zod(z.enum(["debug", "info", "warn", "error"]), { placeholder: "debug" }),
 * );
 * ```
 *
@@ -126,49 +327,139 @@ function inferMetavar(schema) {
 * import { message } from "@optique/core/message";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", zod(z.string().email(), {
-*   metavar: "EMAIL",
-*   errors: {
-*     zodError: (error, input) =>
-*       message`Please provide a valid email address, got ${input}.`
-*   }
-* }));
+* const email = option("--email",
+*   zod(z.string().email(), {
+*     placeholder: "",
+*     metavar: "EMAIL",
+*     errors: {
+*       zodError: (error, input) =>
+*         message`Please provide a valid email address, got ${input}.`
+*     },
+*   }),
+* );
 * ```
 *
+* @throws {TypeError} If `options` is missing, not an object, or does not
+*   include `placeholder`.
+* @throws {TypeError} If the resolved `metavar` is an empty string.
+* @throws {TypeError} If the schema contains async refinements or other async
+*   operations that cannot be executed synchronously.
 * @since 0.7.0
 */
-function zod(schema, options = {}) {
-	return {
-		$mode: "sync",
-		metavar: options.metavar ?? inferMetavar(schema),
-		parse(input) {
-			const result = schema.safeParse(input);
-			if (result.success) return {
-				success: true,
-				value: result.data
+function zod(schema, options) {
+	if (options == null || typeof options !== "object") throw new TypeError("zod() requires an options object with a placeholder property.");
+	if (!("placeholder" in options)) throw new TypeError("zod() options must include a placeholder property.");
+	const choices = inferChoices(schema);
+	const boolInfo = analyzeBooleanSchema(schema);
+	const metavar = options.metavar ?? (boolInfo.isBoolean ? "BOOLEAN" : inferMetavar(schema));
+	ensureNonEmptyString(metavar);
+	function doSafeParse(input, rawInput) {
+		let result;
+		try {
+			result = schema.safeParse(input);
+		} catch (error) {
+			if (error instanceof Error && isZodAsyncError(error)) throw new TypeError("Async Zod schemas (e.g., async refinements) are not supported by zod(). Use synchronous schemas instead.");
+			throw error;
+		}
+		if (result.success) return {
+			success: true,
+			value: result.data
+		};
+		if (options.errors?.zodError) return {
+			success: false,
+			error: typeof options.errors.zodError === "function" ? options.errors.zodError(result.error, rawInput) : options.errors.zodError
+		};
+		const zodModule = schema;
+		if (typeof zodModule.constructor?.prettifyError === "function") try {
+			const pretty = zodModule.constructor.prettifyError(result.error);
+			return {
+				success: false,
+				error: message`${pretty}`
 			};
-			if (options.errors?.zodError) return {
+		} catch {}
+		const firstError = result.error.issues[0];
+		return {
+			success: false,
+			error: message`${firstError?.message ?? "Validation failed"}`
+		};
+	}
+	/**
+	* Handles a failed boolean literal pre-conversion.
+	*
+	*  -  *Non-coerced* (`z.boolean()`): falls through to `doSafeParse`
+	*     so that catch/default, custom errors, and async detection all
+	*     work.  This is safe because `safeParse(string)` fails at the
+	*     type level before any refinements execute.
+	*  -  *Coerced* (`z.coerce.boolean()`): runs the lazy async probe
+	*     (if not yet completed), then returns the pre-conversion error
+	*     or delegates to the custom `zodError` callback.
+	*/
+	function handleBooleanLiteralError(boolResult, rawInput) {
+		if (!boolInfo.isCoerced) return doSafeParse(rawInput, rawInput);
+		if (options.errors?.zodError) {
+			if (typeof options.errors.zodError !== "function") return {
 				success: false,
-				error: typeof options.errors.zodError === "function" ? options.errors.zodError(result.error, input) : options.errors.zodError
+				error: options.errors.zodError
 			};
-			const zodModule = schema;
-			if (typeof zodModule.constructor?.prettifyError === "function") try {
-				const pretty = zodModule.constructor.prettifyError(result.error);
-				return {
-					success: false,
-					error: message`${pretty}`
-				};
-			} catch {}
-			const firstError = result.error.issues[0];
+			const zodError = new ZodError([{
+				code: "invalid_type",
+				expected: "boolean",
+				message: `Invalid Boolean value: ${rawInput}`,
+				path: []
+			}]);
 			return {
 				success: false,
-				error: message`${firstError?.message ?? "Validation failed"}`
+				error: options.errors.zodError(zodError, rawInput)
 			};
+		}
+		return boolResult;
+	}
+	const parser = {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder,
+		...boolInfo.exposeChoices ? {
+			choices: Object.freeze([true, false]),
+			suggest(prefix) {
+				const allLiterals = [...BOOL_TRUE_LITERALS, ...BOOL_FALSE_LITERALS];
+				const normalizedPrefix = prefix.toLowerCase();
+				return allLiterals.filter((lit) => lit.startsWith(normalizedPrefix)).map((lit) => ({
+					kind: "literal",
+					text: lit
+				}));
+			}
+		} : choices != null && choices.length > 0 ? {
+			choices: Object.freeze(choices),
+			*suggest(prefix) {
+				for (const c of choices) if (c.startsWith(prefix)) yield {
+					kind: "literal",
+					text: c
+				};
+			}
+		} : {},
+		parse(input) {
+			if (boolInfo.isBoolean) {
+				const boolResult = preConvertBoolean(input);
+				if (!boolResult.success) return handleBooleanLiteralError(boolResult, input);
+				return doSafeParse(boolResult.value, input);
+			}
+			return doSafeParse(input, input);
 		},
 		format(value) {
-			return String(value);
+			if (options.format) return options.format(value);
+			if (value instanceof Date) return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
+			if (typeof value !== "object" || value === null) return String(value);
+			if (Array.isArray(value)) return String(value);
+			const str = String(value);
+			if (str !== "[object Object]") return str;
+			const proto = Object.getPrototypeOf(value);
+			if (proto === Object.prototype || proto === null) try {
+				return JSON.stringify(value) ?? str;
+			} catch {}
+			return str;
 		}
 	};
+	return parser;
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/zod",
-  "version": "1.0.0-dev.921+754748bd",
+  "version": "1.0.0",
   "description": "Zod value parsers for Optique",
   "keywords": [
     "CLI",
@@ -57,7 +57,7 @@
     "zod": "^3.25.0 || ^4.0.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.921+754748bd"
+    "@optique/core": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",