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

package/README.md

@@ -45,7 +45,9 @@ import * as v from "valibot";
 
 const cli = run(
   object({
-    email: option("--email", valibot(v.pipe(v.string(), v.email()))),
+    email: option("--email",
+      valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+    ),
   }),
 );
 
@@ -73,7 +75,9 @@ import { option } from "@optique/core/primitives";
 import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
-const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+const email = option("--email",
+  valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+);
 ~~~~
 
 ### URL validation
@@ -83,7 +87,9 @@ import { option } from "@optique/core/primitives";
 import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
-const url = option("--url", valibot(v.pipe(v.string(), v.url())));
+const url = option("--url",
+  valibot(v.pipe(v.string(), v.url()), { placeholder: "" }),
+);
 ~~~~
 
 ### Port numbers with range validation
@@ -105,7 +111,7 @@ const port = option("-p", "--port",
     v.integer(),
     v.minValue(1024),
     v.maxValue(65535)
-  ))
+  ), { placeholder: 0 }),
 );
 ~~~~
 
@@ -117,7 +123,8 @@ import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
 const logLevel = option("--log-level",
-  valibot(v.picklist(["debug", "info", "warn", "error"]))
+  valibot(v.picklist(["debug", "info", "warn", "error"]),
+    { placeholder: "debug" }),
 );
 ~~~~
 
@@ -129,7 +136,8 @@ import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
 const startDate = argument(
-  valibot(v.pipe(v.string(), v.transform((s: string) => new Date(s))))
+  valibot(v.pipe(v.string(), v.transform((s: string) => new Date(s))),
+    { placeholder: new Date(0) }),
 );
 ~~~~
 
@@ -146,6 +154,7 @@ import { message } from "@optique/core/message";
 import * as v from "valibot";
 
 const email = option("--email", valibot(v.pipe(v.string(), v.email()), {
+  placeholder: "",
   metavar: "EMAIL",
   errors: {
     valibotError: (issues, input) =>
@@ -169,7 +178,9 @@ import { valibot } from "@optique/valibot";
 import * as v from "valibot";
 
 // ✅ Correct
-const port = option("-p", valibot(v.pipe(v.string(), v.transform(Number))));
+const port = option("-p",
+  valibot(v.pipe(v.string(), v.transform(Number)), { placeholder: 0 }),
+);
 
 // ❌ Won't work (CLI arguments are always strings)
 // const port = option("-p", valibot(v.number()));
@@ -187,7 +198,9 @@ import * as v from "valibot";
 
 // ❌ Not supported
 const email = option("--email",
-  valibot(v.pipeAsync(v.string(), v.checkAsync(async (val) => await checkDB(val))))
+  valibot(v.pipeAsync(v.string(),
+    v.checkAsync(async (val) => await checkDB(val))),
+    { placeholder: "" }),
 );
 ~~~~
 

package/dist/index.cjs

@@ -302,7 +302,8 @@ function inferChoices(schema) {
 *
 * @template T The output type of the Valibot schema.
 * @param schema A Valibot 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 { valibot } from "@optique/valibot";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+* const email = option("--email",
+*   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+* );
 * ```
 *
 * @example Number validation with pipeline
@@ -328,8 +331,8 @@ function inferChoices(schema) {
 *     v.number(),
 *     v.integer(),
 *     v.minValue(1024),
-*     v.maxValue(65535)
-*   ))
+*     v.maxValue(65535),
+*   ), { placeholder: 1024 }),
 * );
 * ```
 *
@@ -340,7 +343,9 @@ function inferChoices(schema) {
 * import { option } from "@optique/core/primitives";
 *
 * const logLevel = option("--log-level",
-*   valibot(v.picklist(["debug", "info", "warn", "error"]))
+*   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+*     placeholder: "debug",
+*   }),
 * );
 * ```
 *
@@ -353,21 +358,26 @@ function inferChoices(schema) {
 *
 * const email = option("--email",
 *   valibot(v.pipe(v.string(), v.email()), {
+*     placeholder: "",
 *     metavar: "EMAIL",
 *     errors: {
 *       valibotError: (issues, 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 validations that cannot be
 *   executed synchronously.
 * @since 0.7.0
 */
-function valibot$1(schema, options = {}) {
+function valibot$1(schema, options) {
+	if (options == null || typeof options !== "object") throw new TypeError("valibot() requires an options object with a placeholder property.");
+	if (!("placeholder" in options)) throw new TypeError("valibot() options must include a placeholder property.");
 	if (containsAsyncSchema(schema)) throw new TypeError("Async Valibot schemas (e.g., async validations) are not supported by valibot(). Use synchronous schemas instead.");
 	const choices = inferChoices(schema);
 	const metavar = options.metavar ?? inferMetavar(schema);
@@ -375,6 +385,7 @@ function valibot$1(schema, options = {}) {
 	const parser = {
 		$mode: "sync",
 		metavar,
+		placeholder: options.placeholder,
 		...choices != null && choices.length > 0 ? {
 			choices: Object.freeze(choices),
 			*suggest(prefix) {

package/dist/index.d.cts

@@ -16,6 +16,13 @@ interface ValibotParserOptions<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 Valibot 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 ValibotParserOptions<T = unknown> {
  *
  * @template T The output type of the Valibot schema.
  * @param schema A Valibot 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 ValibotParserOptions<T = unknown> {
  * import { valibot } from "@optique/valibot";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+ * const email = option("--email",
+ *   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+ * );
  * ```
  *
  * @example Number validation with pipeline
@@ -84,8 +94,8 @@ interface ValibotParserOptions<T = unknown> {
  *     v.number(),
  *     v.integer(),
  *     v.minValue(1024),
- *     v.maxValue(65535)
- *   ))
+ *     v.maxValue(65535),
+ *   ), { placeholder: 1024 }),
  * );
  * ```
  *
@@ -96,7 +106,9 @@ interface ValibotParserOptions<T = unknown> {
  * import { option } from "@optique/core/primitives";
  *
  * const logLevel = option("--log-level",
- *   valibot(v.picklist(["debug", "info", "warn", "error"]))
+ *   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+ *     placeholder: "debug",
+ *   }),
  * );
  * ```
  *
@@ -109,20 +121,23 @@ interface ValibotParserOptions<T = unknown> {
  *
  * const email = option("--email",
  *   valibot(v.pipe(v.string(), v.email()), {
+ *     placeholder: "",
  *     metavar: "EMAIL",
  *     errors: {
  *       valibotError: (issues, 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 validations that cannot be
  *   executed synchronously.
  * @since 0.7.0
  */
-declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options?: ValibotParserOptions<T>): ValueParser<"sync", T>;
+declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options: ValibotParserOptions<T>): ValueParser<"sync", T>;
 //#endregion
 export { ValibotParserOptions, valibot };

package/dist/index.d.ts

@@ -16,6 +16,13 @@ interface ValibotParserOptions<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 Valibot 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 ValibotParserOptions<T = unknown> {
  *
  * @template T The output type of the Valibot schema.
  * @param schema A Valibot 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 ValibotParserOptions<T = unknown> {
  * import { valibot } from "@optique/valibot";
  * import { option } from "@optique/core/primitives";
  *
- * const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+ * const email = option("--email",
+ *   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+ * );
  * ```
  *
  * @example Number validation with pipeline
@@ -84,8 +94,8 @@ interface ValibotParserOptions<T = unknown> {
  *     v.number(),
  *     v.integer(),
  *     v.minValue(1024),
- *     v.maxValue(65535)
- *   ))
+ *     v.maxValue(65535),
+ *   ), { placeholder: 1024 }),
  * );
  * ```
  *
@@ -96,7 +106,9 @@ interface ValibotParserOptions<T = unknown> {
  * import { option } from "@optique/core/primitives";
  *
  * const logLevel = option("--log-level",
- *   valibot(v.picklist(["debug", "info", "warn", "error"]))
+ *   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+ *     placeholder: "debug",
+ *   }),
  * );
  * ```
  *
@@ -109,20 +121,23 @@ interface ValibotParserOptions<T = unknown> {
  *
  * const email = option("--email",
  *   valibot(v.pipe(v.string(), v.email()), {
+ *     placeholder: "",
  *     metavar: "EMAIL",
  *     errors: {
  *       valibotError: (issues, 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 validations that cannot be
  *   executed synchronously.
  * @since 0.7.0
  */
-declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options?: ValibotParserOptions<T>): ValueParser<"sync", T>;
+declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options: ValibotParserOptions<T>): ValueParser<"sync", T>;
 //#endregion
 export { ValibotParserOptions, valibot };

package/dist/index.js

@@ -279,7 +279,8 @@ function inferChoices(schema) {
 *
 * @template T The output type of the Valibot schema.
 * @param schema A Valibot 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 { valibot } from "@optique/valibot";
 * import { option } from "@optique/core/primitives";
 *
-* const email = option("--email", valibot(v.pipe(v.string(), v.email())));
+* const email = option("--email",
+*   valibot(v.pipe(v.string(), v.email()), { placeholder: "" }),
+* );
 * ```
 *
 * @example Number validation with pipeline
@@ -305,8 +308,8 @@ function inferChoices(schema) {
 *     v.number(),
 *     v.integer(),
 *     v.minValue(1024),
-*     v.maxValue(65535)
-*   ))
+*     v.maxValue(65535),
+*   ), { placeholder: 1024 }),
 * );
 * ```
 *
@@ -317,7 +320,9 @@ function inferChoices(schema) {
 * import { option } from "@optique/core/primitives";
 *
 * const logLevel = option("--log-level",
-*   valibot(v.picklist(["debug", "info", "warn", "error"]))
+*   valibot(v.picklist(["debug", "info", "warn", "error"]), {
+*     placeholder: "debug",
+*   }),
 * );
 * ```
 *
@@ -330,21 +335,26 @@ function inferChoices(schema) {
 *
 * const email = option("--email",
 *   valibot(v.pipe(v.string(), v.email()), {
+*     placeholder: "",
 *     metavar: "EMAIL",
 *     errors: {
 *       valibotError: (issues, 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 validations that cannot be
 *   executed synchronously.
 * @since 0.7.0
 */
-function valibot(schema, options = {}) {
+function valibot(schema, options) {
+	if (options == null || typeof options !== "object") throw new TypeError("valibot() requires an options object with a placeholder property.");
+	if (!("placeholder" in options)) throw new TypeError("valibot() options must include a placeholder property.");
 	if (containsAsyncSchema(schema)) throw new TypeError("Async Valibot schemas (e.g., async validations) are not supported by valibot(). Use synchronous schemas instead.");
 	const choices = inferChoices(schema);
 	const metavar = options.metavar ?? inferMetavar(schema);
@@ -352,6 +362,7 @@ function valibot(schema, options = {}) {
 	const parser = {
 		$mode: "sync",
 		metavar,
+		placeholder: options.placeholder,
 		...choices != null && choices.length > 0 ? {
 			choices: Object.freeze(choices),
 			*suggest(prefix) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/valibot",
-  "version": "1.0.0-dev.1499+1fd447f6",
+  "version": "1.0.0-dev.1500+dc0650e5",
   "description": "Valibot value parsers for Optique",
   "keywords": [
     "CLI",
@@ -57,7 +57,7 @@
     "valibot": "^1.2.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.1499+1fd447f6"
+    "@optique/core": "1.0.0-dev.1500+dc0650e5"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",