@optique/zod 0.7.0-dev.1

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+@optique/zod
+============
+
+> [!WARNING]
+> The API is stabilizing, but may change before the 1.0 release.
+
+Zod value parsers for Optique. This package provides seamless integration
+between [Zod] schemas and *@optique/core*, enabling powerful validation and
+type-safe parsing of command-line arguments.
+
+[Zod]: https://zod.dev/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/zod jsr:@optique/run jsr:@optique/core zod
+npm  add     @optique/zod     @optique/run     @optique/core zod
+pnpm add     @optique/zod     @optique/run     @optique/core zod
+yarn add     @optique/zod     @optique/run     @optique/core zod
+bun  add     @optique/zod     @optique/run     @optique/core zod
+~~~~
+
+This package supports Zod versions 3.25.0 and above, including Zod v4.
+
+
+Quick example
+-------------
+
+The following example uses the `zod()` value parser to validate an email
+address.
+
+~~~~ typescript
+import { run } from "@optique/run";
+import { option } from "@optique/core/parser";
+import { zod } from "@optique/zod";
+import { z } from "zod";
+
+const cli = run({
+  email: option("--email", zod(z.string().email())),
+});
+
+console.log(`Welcome, ${cli.email}!`);
+~~~~
+
+Run it:
+
+~~~~ bash
+$ node cli.js --email user@example.com
+Welcome, user@example.com!
+
+$ node cli.js --email invalid-email
+Error: Invalid email
+~~~~
+
+
+Common use cases
+----------------
+
+### Email validation
+
+~~~~ typescript
+import { zod } from "@optique/zod";
+import { z } from "zod";
+
+const email = option("--email", zod(z.string().email()));
+~~~~
+
+### URL validation
+
+~~~~ typescript
+import { zod } from "@optique/zod";
+import { z } from "zod";
+
+const url = option("--url", zod(z.string().url()));
+~~~~
+
+### Port numbers with range validation
+
+> [!IMPORTANT]
+> Always use `z.coerce` for non-string types, since CLI arguments are
+> always strings.
+
+~~~~ typescript
+import { zod } from "@optique/zod";
+import { z } from "zod";
+
+const port = option("-p", "--port",
+  zod(z.coerce.number().int().min(1024).max(65535))
+);
+~~~~
+
+### Enum choices
+
+~~~~ typescript
+import { zod } from "@optique/zod";
+import { z } from "zod";
+
+const logLevel = option("--log-level",
+  zod(z.enum(["debug", "info", "warn", "error"]))
+);
+~~~~
+
+### Date transformations
+
+~~~~ typescript
+import { zod } from "@optique/zod";
+import { z } from "zod";
+
+const startDate = argument(
+  zod(z.string().transform((s) => new Date(s)))
+);
+~~~~
+
+
+Custom error messages
+---------------------
+
+You can customize error messages using the `errors` option:
+
+~~~~ typescript
+import { zod } from "@optique/zod";
+import { message } from "@optique/core/message";
+import { z } from "zod";
+
+const email = option("--email", zod(z.string().email(), {
+  metavar: "EMAIL",
+  errors: {
+    zodError: (error, input) =>
+      message`Please provide a valid email address, got ${input}.`
+  }
+}));
+~~~~
+
+
+Important notes
+---------------
+
+### Always use `z.coerce` for non-string types
+
+CLI arguments are always strings. If you want to parse numbers, booleans,
+or other types, you must use `z.coerce`:
+
+~~~~ typescript
+// ✅ Correct
+const port = option("-p", zod(z.coerce.number()));
+
+// ❌ Won't work (CLI arguments are always strings)
+const port = option("-p", zod(z.number()));
+~~~~
+
+### Async refinements are not supported
+
+Optique's `ValueParser.parse()` is synchronous, so async Zod features like
+async refinements cannot be supported:
+
+~~~~ typescript
+// ❌ Not supported
+const email = option("--email",
+  zod(z.string().refine(async (val) => await checkDB(val)))
+);
+~~~~
+
+If you need async validation, perform it after parsing the CLI arguments.
+
+
+Zod version compatibility
+--------------------------
+
+This package supports both Zod v3 (3.25.0+) and Zod v4 (4.0.0+). The basic
+functionality works identically in both versions.
+
+ -  **Zod v3**: Uses standard error messages from `error.issues[0].message`
+ -  **Zod v4**: Automatically uses `prettifyError()` when available for better
+    error formatting
+
+### Testing with different Zod versions
+
+For contributors and users who want to test compatibility:
+
+~~~~ bash
+# Test with Zod v3
+pnpm run test:zod3
+
+# Test with Zod v4
+pnpm run test:zod4
+
+# Test with both versions sequentially
+pnpm run test:all-versions
+~~~~
+
+
+For more resources
+------------------
+
+ -  [Optique documentation](https://optique.dev/)
+ -  [Zod documentation](https://zod.dev/)
+ -  [Examples directory](/examples/)

package/dist/index.cjs

@@ -0,0 +1,123 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __optique_core_message = __toESM(require("@optique/core/message"));
+
+//#region src/index.ts
+/**
+* Creates a value parser from a Zod schema.
+*
+* This parser validates CLI argument strings using Zod schemas, enabling
+* powerful validation and transformation capabilities for command-line
+* interfaces.
+*
+* @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.
+* @returns A value parser that validates inputs using the provided schema.
+*
+* @example Basic string validation
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* import { option } from "@optique/core/primitives";
+*
+* const email = option("--email", zod(z.string().email()));
+* ```
+*
+* @example Number validation with coercion
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* import { option } from "@optique/core/primitives";
+*
+* // 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))
+* );
+* ```
+*
+* @example Enum validation
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* import { option } from "@optique/core/primitives";
+*
+* const logLevel = option("--log-level",
+*   zod(z.enum(["debug", "info", "warn", "error"]))
+* );
+* ```
+*
+* @example Custom error messages
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* 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}.`
+*   }
+* }));
+* ```
+*
+* @since 0.7.0
+*/
+function zod(schema, options = {}) {
+	return {
+		metavar: options.metavar ?? "VALUE",
+		parse(input) {
+			const result = schema.safeParse(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, input) : 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"}`
+			};
+		},
+		format(value) {
+			return String(value);
+		}
+	};
+}
+
+//#endregion
+exports.zod = zod;

package/dist/index.d.cts

@@ -0,0 +1,96 @@
+import { ValueParser } from "@optique/core/valueparser";
+import { Message } from "@optique/core/message";
+import { z } from "zod";
+
+//#region src/index.d.ts
+
+/**
+ * Options for creating a Zod value parser.
+ * @since 0.7.0
+ */
+interface ZodParserOptions {
+  /**
+   * The metavariable name for this parser. This is used in help messages to
+   * indicate what kind of value this parser expects. Usually a single
+   * word in uppercase, like `VALUE` or `SCHEMA`.
+   * @default `"VALUE"`
+   */
+  readonly metavar?: string;
+  /**
+   * Custom error messages for Zod validation failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input fails Zod validation.
+     * Can be a static message or a function that receives the Zod error
+     * and input string.
+     * @since 0.7.0
+     */
+    zodError?: Message | ((error: z.ZodError, input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser from a Zod schema.
+ *
+ * This parser validates CLI argument strings using Zod schemas, enabling
+ * powerful validation and transformation capabilities for command-line
+ * interfaces.
+ *
+ * @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.
+ * @returns A value parser that validates inputs using the provided schema.
+ *
+ * @example Basic string validation
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * import { option } from "@optique/core/primitives";
+ *
+ * const email = option("--email", zod(z.string().email()));
+ * ```
+ *
+ * @example Number validation with coercion
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * import { option } from "@optique/core/primitives";
+ *
+ * // 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))
+ * );
+ * ```
+ *
+ * @example Enum validation
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * import { option } from "@optique/core/primitives";
+ *
+ * const logLevel = option("--log-level",
+ *   zod(z.enum(["debug", "info", "warn", "error"]))
+ * );
+ * ```
+ *
+ * @example Custom error messages
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * 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}.`
+ *   }
+ * }));
+ * ```
+ *
+ * @since 0.7.0
+ */
+declare function zod<T>(schema: z.Schema<T>, options?: ZodParserOptions): ValueParser<T>;
+//#endregion
+export { ZodParserOptions, zod };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { Message } from "@optique/core/message";
+import { ValueParser } from "@optique/core/valueparser";
+import { z } from "zod";
+
+//#region src/index.d.ts
+
+/**
+ * Options for creating a Zod value parser.
+ * @since 0.7.0
+ */
+interface ZodParserOptions {
+  /**
+   * The metavariable name for this parser. This is used in help messages to
+   * indicate what kind of value this parser expects. Usually a single
+   * word in uppercase, like `VALUE` or `SCHEMA`.
+   * @default `"VALUE"`
+   */
+  readonly metavar?: string;
+  /**
+   * Custom error messages for Zod validation failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input fails Zod validation.
+     * Can be a static message or a function that receives the Zod error
+     * and input string.
+     * @since 0.7.0
+     */
+    zodError?: Message | ((error: z.ZodError, input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser from a Zod schema.
+ *
+ * This parser validates CLI argument strings using Zod schemas, enabling
+ * powerful validation and transformation capabilities for command-line
+ * interfaces.
+ *
+ * @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.
+ * @returns A value parser that validates inputs using the provided schema.
+ *
+ * @example Basic string validation
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * import { option } from "@optique/core/primitives";
+ *
+ * const email = option("--email", zod(z.string().email()));
+ * ```
+ *
+ * @example Number validation with coercion
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * import { option } from "@optique/core/primitives";
+ *
+ * // 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))
+ * );
+ * ```
+ *
+ * @example Enum validation
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * import { option } from "@optique/core/primitives";
+ *
+ * const logLevel = option("--log-level",
+ *   zod(z.enum(["debug", "info", "warn", "error"]))
+ * );
+ * ```
+ *
+ * @example Custom error messages
+ * ```typescript
+ * import { z } from "zod";
+ * import { zod } from "@optique/zod";
+ * 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}.`
+ *   }
+ * }));
+ * ```
+ *
+ * @since 0.7.0
+ */
+declare function zod<T>(schema: z.Schema<T>, options?: ZodParserOptions): ValueParser<T>;
+//#endregion
+export { ZodParserOptions, zod };

package/dist/index.js

@@ -0,0 +1,100 @@
+import { message } from "@optique/core/message";
+
+//#region src/index.ts
+/**
+* Creates a value parser from a Zod schema.
+*
+* This parser validates CLI argument strings using Zod schemas, enabling
+* powerful validation and transformation capabilities for command-line
+* interfaces.
+*
+* @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.
+* @returns A value parser that validates inputs using the provided schema.
+*
+* @example Basic string validation
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* import { option } from "@optique/core/primitives";
+*
+* const email = option("--email", zod(z.string().email()));
+* ```
+*
+* @example Number validation with coercion
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* import { option } from "@optique/core/primitives";
+*
+* // 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))
+* );
+* ```
+*
+* @example Enum validation
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* import { option } from "@optique/core/primitives";
+*
+* const logLevel = option("--log-level",
+*   zod(z.enum(["debug", "info", "warn", "error"]))
+* );
+* ```
+*
+* @example Custom error messages
+* ```typescript
+* import { z } from "zod";
+* import { zod } from "@optique/zod";
+* 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}.`
+*   }
+* }));
+* ```
+*
+* @since 0.7.0
+*/
+function zod(schema, options = {}) {
+	return {
+		metavar: options.metavar ?? "VALUE",
+		parse(input) {
+			const result = schema.safeParse(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, input) : 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"}`
+			};
+		},
+		format(value) {
+			return String(value);
+		}
+	};
+}
+
+//#endregion
+export { zod };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@optique/zod",
+  "version": "0.7.0-dev.1",
+  "description": "Zod value parsers for Optique",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "zod",
+    "validation"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/zod/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "dependencies": {
+    "@optique/core": ""
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3",
+    "zod": "^4.0.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test",
+    "test:deno": "deno test",
+    "test:zod3": "cp package.json .package.json.bak && pnpm add -D zod@^3.25.0 && pnpm test && mv .package.json.bak package.json && pnpm install",
+    "test:zod4": "cp package.json .package.json.bak && pnpm add -D zod@^4.0.0 && pnpm test && mv .package.json.bak package.json && pnpm install",
+    "test:all-versions": "pnpm run test:zod3 && pnpm run test:zod4",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}