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

package/README.md

@@ -142,6 +142,46 @@ const startDate = argument(
 ~~~~
 
 
+Async schemas
+-------------
+
+Use `valibotAsync()` when a schema depends on async validations, 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 { valibotAsync } from "@optique/valibot";
+import * as v from "valibot";
+
+async function checkProject(value: string): Promise<boolean> {
+  return await Promise.resolve(value.startsWith("project-"));
+}
+
+const parser = object({
+  project: option("--project",
+    valibotAsync(
+      v.pipeAsync(v.string(), v.checkAsync(checkProject, "Unknown project.")),
+      { placeholder: "" },
+    ),
+  ),
+});
+
+const cli = await runAsync(parser);
+~~~~
+
+The `valibot()` helper remains synchronous and rejects schemas that require
+Valibot's async parse path.  `valibotAsync()` preserves metavar inference,
+choices, suggestions, 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
 ---------------------
 
@@ -186,25 +226,30 @@ const port = option("-p",
 // const port = option("-p", valibot(v.number()));
 ~~~~
 
-### Async validations are not supported
+### `valibot()` is synchronous
 
-Optique's `ValueParser.parse()` is synchronous, so async Valibot features like
-async validations cannot be supported:
+The `valibot()` helper returns a sync value parser, so async Valibot features
+like `pipeAsync()` require `valibotAsync()`:
 
 ~~~~ typescript
 import { option } from "@optique/core/primitives";
-import { valibot } from "@optique/valibot";
+import { valibot, valibotAsync } from "@optique/valibot";
 import * as v from "valibot";
 
-// ❌ Not supported
-const email = option("--email",
+// ❌ Not supported by valibot()
+const syncEmail = option("--email",
   valibot(v.pipeAsync(v.string(),
     v.checkAsync(async (val) => await checkDB(val))),
     { placeholder: "" }),
 );
-~~~~
 
-If you need async validation, perform it after parsing the CLI arguments.
+// ✅ Use valibotAsync() and runAsync()
+const asyncEmail = option("--email",
+  valibotAsync(v.pipeAsync(v.string(),
+    v.checkAsync(async (val) => await checkDB(val))),
+    { placeholder: "" }),
+);
+~~~~
 
 
 For more resources

package/dist/index.cjs

@@ -285,6 +285,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 Valibot schema.
 *
@@ -376,8 +393,7 @@ function inferChoices(schema) {
 * @since 0.7.0
 */
 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.");
+	validateOptions("valibot", options);
 	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);
@@ -413,21 +429,76 @@ function valibot$1(schema, options) {
 			};
 		},
 		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 Valibot schema.
+*
+* This parser validates CLI argument strings with Valibot's async safe-parse
+* path, so schemas using `pipeAsync()`, `checkAsync()`, or other async actions
+* can be reused directly in asynchronous Optique parsers.
+*
+* The metavar, choices, suggestions, formatting, and error customization
+* follow the same rules as {@link valibot}.  Because the returned parser runs
+* asynchronously, use it with `parseAsync()`, `run()`, or `runAsync()`.
+*
+* @template T The output type of the Valibot schema.
+* @param schema A Valibot 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 valibotAsync(schema, options) {
+	validateOptions("valibotAsync", options);
+	const syncSchema = schema;
+	const choices = inferChoices(syncSchema);
+	const metavar = options.metavar ?? inferMetavar(syncSchema);
+	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
+	const parser = {
+		mode: "async",
+		metavar,
+		placeholder: options.placeholder,
+		...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) {
+			const result = await (0, valibot.safeParseAsync)(schema, input);
+			if (result.success) return {
+				success: true,
+				value: result.output
+			};
+			if (options.errors?.valibotError) return {
+				success: false,
+				error: typeof options.errors.valibotError === "function" ? options.errors.valibotError(result.issues, input) : options.errors.valibotError
+			};
+			const firstIssue = result.issues[0];
+			return {
+				success: false,
+				error: __optique_core_message.message`${firstIssue?.message ?? "Validation failed"}`
+			};
+		},
+		format(value) {
+			return formatValue(value, options.format);
 		}
 	};
 	return parser;
 }
 
 //#endregion
-exports.valibot = valibot$1;
+exports.valibot = valibot$1;
+exports.valibotAsync = valibotAsync;

package/dist/index.d.cts

@@ -139,5 +139,30 @@ interface ValibotParserOptions<T = unknown> {
  * @since 0.7.0
  */
 declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options: ValibotParserOptions<T>): ValueParser<"sync", T>;
+type AnyValibotSchema<T> = v.BaseSchema<unknown, T, v.BaseIssue<unknown>> | v.BaseSchemaAsync<unknown, T, v.BaseIssue<unknown>>;
+/**
+ * Creates an async value parser from a Valibot schema.
+ *
+ * This parser validates CLI argument strings with Valibot's async safe-parse
+ * path, so schemas using `pipeAsync()`, `checkAsync()`, or other async actions
+ * can be reused directly in asynchronous Optique parsers.
+ *
+ * The metavar, choices, suggestions, formatting, and error customization
+ * follow the same rules as {@link valibot}.  Because the returned parser runs
+ * asynchronously, use it with `parseAsync()`, `run()`, or `runAsync()`.
+ *
+ * @template T The output type of the Valibot schema.
+ * @param schema A Valibot 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 valibotAsync<T>(schema: AnyValibotSchema<T>, options: ValibotParserOptions<T>): ValueParser<"async", T>;
 //#endregion
-export { ValibotParserOptions, valibot };
+export { ValibotParserOptions, valibot, valibotAsync };

package/dist/index.d.ts

@@ -139,5 +139,30 @@ interface ValibotParserOptions<T = unknown> {
  * @since 0.7.0
  */
 declare function valibot<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, options: ValibotParserOptions<T>): ValueParser<"sync", T>;
+type AnyValibotSchema<T> = v.BaseSchema<unknown, T, v.BaseIssue<unknown>> | v.BaseSchemaAsync<unknown, T, v.BaseIssue<unknown>>;
+/**
+ * Creates an async value parser from a Valibot schema.
+ *
+ * This parser validates CLI argument strings with Valibot's async safe-parse
+ * path, so schemas using `pipeAsync()`, `checkAsync()`, or other async actions
+ * can be reused directly in asynchronous Optique parsers.
+ *
+ * The metavar, choices, suggestions, formatting, and error customization
+ * follow the same rules as {@link valibot}.  Because the returned parser runs
+ * asynchronously, use it with `parseAsync()`, `run()`, or `runAsync()`.
+ *
+ * @template T The output type of the Valibot schema.
+ * @param schema A Valibot 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 valibotAsync<T>(schema: AnyValibotSchema<T>, options: ValibotParserOptions<T>): ValueParser<"async", T>;
 //#endregion
-export { ValibotParserOptions, valibot };
+export { ValibotParserOptions, valibot, valibotAsync };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { message } from "@optique/core/message";
 import { ensureNonEmptyString } from "@optique/core/nonempty";
-import { safeParse } from "valibot";
+import { safeParse, safeParseAsync } from "valibot";
 
 //#region src/index.ts
 /**
@@ -262,6 +262,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 Valibot schema.
 *
@@ -353,8 +370,7 @@ function inferChoices(schema) {
 * @since 0.7.0
 */
 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.");
+	validateOptions("valibot", options);
 	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);
@@ -390,21 +406,75 @@ function valibot(schema, options) {
 			};
 		},
 		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 Valibot schema.
+*
+* This parser validates CLI argument strings with Valibot's async safe-parse
+* path, so schemas using `pipeAsync()`, `checkAsync()`, or other async actions
+* can be reused directly in asynchronous Optique parsers.
+*
+* The metavar, choices, suggestions, formatting, and error customization
+* follow the same rules as {@link valibot}.  Because the returned parser runs
+* asynchronously, use it with `parseAsync()`, `run()`, or `runAsync()`.
+*
+* @template T The output type of the Valibot schema.
+* @param schema A Valibot 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 valibotAsync(schema, options) {
+	validateOptions("valibotAsync", options);
+	const syncSchema = schema;
+	const choices = inferChoices(syncSchema);
+	const metavar = options.metavar ?? inferMetavar(syncSchema);
+	ensureNonEmptyString(metavar);
+	const parser = {
+		mode: "async",
+		metavar,
+		placeholder: options.placeholder,
+		...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) {
+			const result = await safeParseAsync(schema, input);
+			if (result.success) return {
+				success: true,
+				value: result.output
+			};
+			if (options.errors?.valibotError) return {
+				success: false,
+				error: typeof options.errors.valibotError === "function" ? options.errors.valibotError(result.issues, input) : options.errors.valibotError
+			};
+			const firstIssue = result.issues[0];
+			return {
+				success: false,
+				error: message`${firstIssue?.message ?? "Validation failed"}`
+			};
+		},
+		format(value) {
+			return formatValue(value, options.format);
 		}
 	};
 	return parser;
 }
 
 //#endregion
-export { valibot };
+export { valibot, valibotAsync };

package/package.json

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