@optique/zod 1.0.0-dev.1499 → 1.0.0-dev.1500

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

@@ -302,7 +302,8 @@ function inferChoices(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
@@ -311,7 +312,9 @@ function inferChoices(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
@@ -322,7 +325,7 @@ function inferChoices(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 }),
 * );
 * ```
 *
@@ -333,7 +336,7 @@ function inferChoices(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" }),
 * );
 * ```
 *
@@ -344,21 +347,28 @@ function inferChoices(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$1(schema, options = {}) {
+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));
@@ -427,6 +437,7 @@ function zod$1(schema, options = {}) {
 	const parser = {
 		$mode: "sync",
 		metavar,
+		placeholder: options.placeholder,
 		...boolInfo.exposeChoices ? {
 			choices: Object.freeze([true, false]),
 			suggest(prefix) {

package/dist/index.d.cts

@@ -16,6 +16,13 @@ interface ZodParserOptions<T = unknown> {
    * @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
@@ -58,7 +65,8 @@ interface ZodParserOptions<T = unknown> {
  *
  * @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
@@ -67,7 +75,9 @@ interface ZodParserOptions<T = unknown> {
  * 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
@@ -78,7 +88,7 @@ interface ZodParserOptions<T = unknown> {
  *
  * // 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 }),
  * );
  * ```
  *
@@ -89,7 +99,7 @@ interface ZodParserOptions<T = unknown> {
  * 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" }),
  * );
  * ```
  *
@@ -100,20 +110,25 @@ interface ZodParserOptions<T = unknown> {
  * 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<T>): 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

@@ -16,6 +16,13 @@ interface ZodParserOptions<T = unknown> {
    * @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
@@ -58,7 +65,8 @@ interface ZodParserOptions<T = unknown> {
  *
  * @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
@@ -67,7 +75,9 @@ interface ZodParserOptions<T = unknown> {
  * 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
@@ -78,7 +88,7 @@ interface ZodParserOptions<T = unknown> {
  *
  * // 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 }),
  * );
  * ```
  *
@@ -89,7 +99,7 @@ interface ZodParserOptions<T = unknown> {
  * 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" }),
  * );
  * ```
  *
@@ -100,20 +110,25 @@ interface ZodParserOptions<T = unknown> {
  * 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<T>): 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

@@ -279,7 +279,8 @@ function inferChoices(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
@@ -288,7 +289,9 @@ function inferChoices(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
@@ -299,7 +302,7 @@ function inferChoices(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 }),
 * );
 * ```
 *
@@ -310,7 +313,7 @@ function inferChoices(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" }),
 * );
 * ```
 *
@@ -321,21 +324,28 @@ function inferChoices(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 = {}) {
+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));
@@ -404,6 +414,7 @@ function zod(schema, options = {}) {
 	const parser = {
 		$mode: "sync",
 		metavar,
+		placeholder: options.placeholder,
 		...boolInfo.exposeChoices ? {
 			choices: Object.freeze([true, false]),
 			suggest(prefix) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/zod",
-  "version": "1.0.0-dev.1499+1fd447f6",
+  "version": "1.0.0-dev.1500+dc0650e5",
   "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.1499+1fd447f6"
+    "@optique/core": "1.0.0-dev.1500+dc0650e5"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",