@optique/zod 1.0.0-dev.1375 → 1.0.0-dev.1388

package/dist/index.cjs

@@ -296,7 +296,17 @@ function zod(schema, options = {}) {
 			};
 		},
 		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;

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,18 @@ interface ZodParserOptions {
    * @default `"VALUE"`
    */
   readonly metavar?: NonEmptyString;
+  /**
+   * 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.
    */
@@ -102,6 +114,6 @@ interface ZodParserOptions {
  *   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

@@ -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,18 @@ interface ZodParserOptions {
    * @default `"VALUE"`
    */
   readonly metavar?: NonEmptyString;
+  /**
+   * 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.
    */
@@ -102,6 +114,6 @@ interface ZodParserOptions {
  *   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

@@ -273,7 +273,17 @@ function zod(schema, options = {}) {
 			};
 		},
 		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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/zod",
-  "version": "1.0.0-dev.1375+69c819ec",
+  "version": "1.0.0-dev.1388+3660675f",
   "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.1375+69c819ec"
+    "@optique/core": "1.0.0-dev.1388+3660675f"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",