@optique/zod 1.1.0-dev.2146 → 1.1.0-dev.2148

package/README.md

@@ -125,6 +125,45 @@ const startDate = argument(
 ~~~~
 
 
+Async schemas
+-------------
+
+Use `zodAsync()` when a schema depends on async refinements or transforms, and
+run the containing parser with `runAsync()` or `await run()`:
+
+~~~~ typescript
+import { runAsync } from "@optique/run";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
+import { zodAsync } from "@optique/zod";
+import { z } from "zod";
+
+async function checkApiKey(value: string): Promise<boolean> {
+  return await Promise.resolve(value.startsWith("live_"));
+}
+
+const parser = object({
+  apiKey: option("--api-key",
+    zodAsync(z.string().refine(checkApiKey, "Unknown API key."), {
+      placeholder: "",
+    }),
+  ),
+});
+
+const cli = await runAsync(parser);
+~~~~
+
+The `zod()` helper remains synchronous and rejects schemas that require Zod's
+async parse path.  `zodAsync()` preserves metavar inference, choices,
+suggestions, Boolean literal conversion, formatting, and custom errors.
+Fallback values from `bindEnv()` or `bindConfig()` are validated by the same
+schema before they are accepted.
+
+Async validation can run during fallback resolution and other repeated parser
+paths, including shell completion requests.  Keep remote checks bounded and
+cached when possible.
+
+
 Custom error messages
 ---------------------
 
@@ -167,24 +206,28 @@ const port = option("-p", zod(z.coerce.number(), { placeholder: 0 }));
 // const port = option("-p", zod(z.number()));
 ~~~~
 
-### Async refinements are not supported
+### `zod()` is synchronous
 
-Optique's `ValueParser.parse()` is synchronous, so async Zod features like
-async refinements cannot be supported:
+The `zod()` helper returns a sync value parser, so async Zod features like
+async refinements and transforms require `zodAsync()`:
 
 ~~~~ typescript
 import { option } from "@optique/core/primitives";
-import { zod } from "@optique/zod";
+import { zod, zodAsync } from "@optique/zod";
 import { z } from "zod";
 
-// ❌ Not supported
-const email = option("--email",
+// ❌ Not supported by zod()
+const syncEmail = option("--email",
   zod(z.string().refine(async (val) => await checkDB(val)),
     { placeholder: "" }),
 );
-~~~~
 
-If you need async validation, perform it after parsing the CLI arguments.
+// ✅ Use zodAsync() and runAsync()
+const asyncEmail = option("--email",
+  zodAsync(z.string().refine(async (val) => await checkDB(val)),
+    { placeholder: "" }),
+);
+~~~~
 
 
 Zod version compatibility

package/dist/index.cjs

@@ -288,6 +288,23 @@ function inferChoices(schema) {
 	}
 	return void 0;
 }
+function validateOptions(functionName, options) {
+	if (options == null || typeof options !== "object") throw new TypeError(`${functionName}() requires an options object with a placeholder property.`);
+	if (!("placeholder" in options)) throw new TypeError(`${functionName}() options must include a placeholder property.`);
+}
+function formatValue(value, format) {
+	if (format) return 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;
+}
 /**
 * Creates a value parser from a Zod schema.
 *
@@ -370,8 +387,7 @@ function inferChoices(schema) {
 * @since 0.7.0
 */
 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.");
+	validateOptions("zod", options);
 	const choices = inferChoices(schema);
 	const boolInfo = analyzeBooleanSchema(schema);
 	const metavar = options.metavar ?? (boolInfo.isBoolean ? "BOOLEAN" : inferMetavar(schema));
@@ -469,21 +485,123 @@ function zod$1(schema, options) {
 			return doSafeParse(input, input);
 		},
 		format(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 formatValue(value, options.format);
+		}
+	};
+	return parser;
+}
+/**
+* Creates an async value parser from a Zod schema.
+*
+* This parser validates CLI argument strings with Zod's async parse path, so
+* schemas using async refinements or transforms can be reused directly in
+* asynchronous Optique parsers.
+*
+* The metavar, choices, suggestions, Boolean input conversion, formatting,
+* and error customization follow the same rules as {@link zod}.  Because the
+* returned parser runs asynchronously, use it with `parseAsync()`, `run()`, or
+* `runAsync()`.
+*
+* @template T The output type of the Zod schema.
+* @param schema A Zod schema to validate input against.
+* @param options Configuration for the parser, including a required
+*   `placeholder` value used during deferred prompt resolution.
+* @returns An async value parser that validates inputs using the provided
+*   schema.
+*
+* @throws {TypeError} If `options` is missing, not an object, or does not
+*   include `placeholder`.
+* @throws {TypeError} If the resolved `metavar` is an empty string.
+* @since 1.1.0
+*/
+function zodAsync(schema, options) {
+	validateOptions("zodAsync", options);
+	const choices = inferChoices(schema);
+	const boolInfo = analyzeBooleanSchema(schema);
+	const metavar = options.metavar ?? (boolInfo.isBoolean ? "BOOLEAN" : inferMetavar(schema));
+	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
+	async function doSafeParse(input, rawInput) {
+		const result = await schema.safeParseAsync(input);
+		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}`
+			};
+		} catch {}
+		const firstError = result.error.issues[0];
+		return {
+			success: false,
+			error: __optique_core_message.message`${firstError?.message ?? "Validation failed"}`
+		};
+	}
+	async function handleBooleanLiteralError(boolResult, rawInput) {
+		if (!boolInfo.isCoerced) return await doSafeParse(rawInput, rawInput);
+		if (options.errors?.zodError) {
+			if (typeof options.errors.zodError !== "function") return {
+				success: false,
+				error: options.errors.zodError
+			};
+			const zodError = new zod.ZodError([{
+				code: "invalid_type",
+				expected: "boolean",
+				message: `Invalid Boolean value: ${rawInput}`,
+				path: []
+			}]);
+			return {
+				success: false,
+				error: options.errors.zodError(zodError, rawInput)
+			};
+		}
+		return boolResult;
+	}
+	const parser = {
+		mode: "async",
+		metavar,
+		placeholder: options.placeholder,
+		...boolInfo.exposeChoices ? {
+			choices: Object.freeze([true, false]),
+			async *suggest(prefix) {
+				const allLiterals = [...BOOL_TRUE_LITERALS, ...BOOL_FALSE_LITERALS];
+				const normalizedPrefix = prefix.toLowerCase();
+				for (const lit of allLiterals) if (lit.startsWith(normalizedPrefix)) yield {
+					kind: "literal",
+					text: lit
+				};
+			}
+		} : choices != null && choices.length > 0 ? {
+			choices: Object.freeze(choices),
+			async *suggest(prefix) {
+				for (const c of choices) if (c.startsWith(prefix)) yield {
+					kind: "literal",
+					text: c
+				};
+			}
+		} : {},
+		async parse(input) {
+			if (boolInfo.isBoolean) {
+				const boolResult = preConvertBoolean(input);
+				if (!boolResult.success) return await handleBooleanLiteralError(boolResult, input);
+				return await doSafeParse(boolResult.value, input);
+			}
+			return await doSafeParse(input, input);
+		},
+		format(value) {
+			return formatValue(value, options.format);
 		}
 	};
 	return parser;
 }
 
 //#endregion
-exports.zod = zod$1;
+exports.zod = zod$1;
+exports.zodAsync = zodAsync;

package/dist/index.d.cts

@@ -130,5 +130,30 @@ interface ZodParserOptions<T = unknown> {
  * @since 0.7.0
  */
 declare function zod<T>(schema: z.Schema<T>, options: ZodParserOptions<T>): ValueParser<"sync", T>;
+/**
+ * Creates an async value parser from a Zod schema.
+ *
+ * This parser validates CLI argument strings with Zod's async parse path, so
+ * schemas using async refinements or transforms can be reused directly in
+ * asynchronous Optique parsers.
+ *
+ * The metavar, choices, suggestions, Boolean input conversion, formatting,
+ * and error customization follow the same rules as {@link zod}.  Because the
+ * returned parser runs asynchronously, use it with `parseAsync()`, `run()`, or
+ * `runAsync()`.
+ *
+ * @template T The output type of the Zod schema.
+ * @param schema A Zod schema to validate input against.
+ * @param options Configuration for the parser, including a required
+ *   `placeholder` value used during deferred prompt resolution.
+ * @returns An async value parser that validates inputs using the provided
+ *   schema.
+ *
+ * @throws {TypeError} If `options` is missing, not an object, or does not
+ *   include `placeholder`.
+ * @throws {TypeError} If the resolved `metavar` is an empty string.
+ * @since 1.1.0
+ */
+declare function zodAsync<T>(schema: z.Schema<T>, options: ZodParserOptions<T>): ValueParser<"async", T>;
 //#endregion
-export { ZodParserOptions, zod };
+export { ZodParserOptions, zod, zodAsync };

package/dist/index.d.ts

@@ -130,5 +130,30 @@ interface ZodParserOptions<T = unknown> {
  * @since 0.7.0
  */
 declare function zod<T>(schema: z.Schema<T>, options: ZodParserOptions<T>): ValueParser<"sync", T>;
+/**
+ * Creates an async value parser from a Zod schema.
+ *
+ * This parser validates CLI argument strings with Zod's async parse path, so
+ * schemas using async refinements or transforms can be reused directly in
+ * asynchronous Optique parsers.
+ *
+ * The metavar, choices, suggestions, Boolean input conversion, formatting,
+ * and error customization follow the same rules as {@link zod}.  Because the
+ * returned parser runs asynchronously, use it with `parseAsync()`, `run()`, or
+ * `runAsync()`.
+ *
+ * @template T The output type of the Zod schema.
+ * @param schema A Zod schema to validate input against.
+ * @param options Configuration for the parser, including a required
+ *   `placeholder` value used during deferred prompt resolution.
+ * @returns An async value parser that validates inputs using the provided
+ *   schema.
+ *
+ * @throws {TypeError} If `options` is missing, not an object, or does not
+ *   include `placeholder`.
+ * @throws {TypeError} If the resolved `metavar` is an empty string.
+ * @since 1.1.0
+ */
+declare function zodAsync<T>(schema: z.Schema<T>, options: ZodParserOptions<T>): ValueParser<"async", T>;
 //#endregion
-export { ZodParserOptions, zod };
+export { ZodParserOptions, zod, zodAsync };

package/dist/index.js

@@ -265,6 +265,23 @@ function inferChoices(schema) {
 	}
 	return void 0;
 }
+function validateOptions(functionName, options) {
+	if (options == null || typeof options !== "object") throw new TypeError(`${functionName}() requires an options object with a placeholder property.`);
+	if (!("placeholder" in options)) throw new TypeError(`${functionName}() options must include a placeholder property.`);
+}
+function formatValue(value, format) {
+	if (format) return 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;
+}
 /**
 * Creates a value parser from a Zod schema.
 *
@@ -347,8 +364,7 @@ function inferChoices(schema) {
 * @since 0.7.0
 */
 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.");
+	validateOptions("zod", options);
 	const choices = inferChoices(schema);
 	const boolInfo = analyzeBooleanSchema(schema);
 	const metavar = options.metavar ?? (boolInfo.isBoolean ? "BOOLEAN" : inferMetavar(schema));
@@ -446,21 +462,122 @@ function zod(schema, options) {
 			return doSafeParse(input, input);
 		},
 		format(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 formatValue(value, options.format);
+		}
+	};
+	return parser;
+}
+/**
+* Creates an async value parser from a Zod schema.
+*
+* This parser validates CLI argument strings with Zod's async parse path, so
+* schemas using async refinements or transforms can be reused directly in
+* asynchronous Optique parsers.
+*
+* The metavar, choices, suggestions, Boolean input conversion, formatting,
+* and error customization follow the same rules as {@link zod}.  Because the
+* returned parser runs asynchronously, use it with `parseAsync()`, `run()`, or
+* `runAsync()`.
+*
+* @template T The output type of the Zod schema.
+* @param schema A Zod schema to validate input against.
+* @param options Configuration for the parser, including a required
+*   `placeholder` value used during deferred prompt resolution.
+* @returns An async value parser that validates inputs using the provided
+*   schema.
+*
+* @throws {TypeError} If `options` is missing, not an object, or does not
+*   include `placeholder`.
+* @throws {TypeError} If the resolved `metavar` is an empty string.
+* @since 1.1.0
+*/
+function zodAsync(schema, options) {
+	validateOptions("zodAsync", options);
+	const choices = inferChoices(schema);
+	const boolInfo = analyzeBooleanSchema(schema);
+	const metavar = options.metavar ?? (boolInfo.isBoolean ? "BOOLEAN" : inferMetavar(schema));
+	ensureNonEmptyString(metavar);
+	async function doSafeParse(input, rawInput) {
+		const result = await schema.safeParseAsync(input);
+		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}`
+			};
+		} catch {}
+		const firstError = result.error.issues[0];
+		return {
+			success: false,
+			error: message`${firstError?.message ?? "Validation failed"}`
+		};
+	}
+	async function handleBooleanLiteralError(boolResult, rawInput) {
+		if (!boolInfo.isCoerced) return await doSafeParse(rawInput, rawInput);
+		if (options.errors?.zodError) {
+			if (typeof options.errors.zodError !== "function") return {
+				success: false,
+				error: options.errors.zodError
+			};
+			const zodError = new ZodError([{
+				code: "invalid_type",
+				expected: "boolean",
+				message: `Invalid Boolean value: ${rawInput}`,
+				path: []
+			}]);
+			return {
+				success: false,
+				error: options.errors.zodError(zodError, rawInput)
+			};
+		}
+		return boolResult;
+	}
+	const parser = {
+		mode: "async",
+		metavar,
+		placeholder: options.placeholder,
+		...boolInfo.exposeChoices ? {
+			choices: Object.freeze([true, false]),
+			async *suggest(prefix) {
+				const allLiterals = [...BOOL_TRUE_LITERALS, ...BOOL_FALSE_LITERALS];
+				const normalizedPrefix = prefix.toLowerCase();
+				for (const lit of allLiterals) if (lit.startsWith(normalizedPrefix)) yield {
+					kind: "literal",
+					text: lit
+				};
+			}
+		} : choices != null && choices.length > 0 ? {
+			choices: Object.freeze(choices),
+			async *suggest(prefix) {
+				for (const c of choices) if (c.startsWith(prefix)) yield {
+					kind: "literal",
+					text: c
+				};
+			}
+		} : {},
+		async parse(input) {
+			if (boolInfo.isBoolean) {
+				const boolResult = preConvertBoolean(input);
+				if (!boolResult.success) return await handleBooleanLiteralError(boolResult, input);
+				return await doSafeParse(boolResult.value, input);
+			}
+			return await doSafeParse(input, input);
+		},
+		format(value) {
+			return formatValue(value, options.format);
 		}
 	};
 	return parser;
 }
 
 //#endregion
-export { zod };
+export { zod, zodAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/zod",
-  "version": "1.1.0-dev.2146",
+  "version": "1.1.0-dev.2148",
   "description": "Zod value parsers for Optique",
   "keywords": [
     "CLI",
@@ -57,7 +57,7 @@
     "zod": "^3.25.0 || ^4.0.0"
   },
   "dependencies": {
-    "@optique/core": "1.1.0-dev.2146+5fd0a75e"
+    "@optique/core": "1.1.0-dev.2148+ab56ac96"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",