@comity/validation-zod 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+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,57 @@
+# @comity/validation-zod
+
+Zod adapter for @comity/validation contracts.
+
+---
+
+## Purpose
+
+Implements the `Validator` contract defined by `@comity/validation` using Zod schemas. Enables applications to validate domain data with Zod while depending only on the Comity validation contract.
+
+---
+
+## Scope
+
+This package:
+
+- ✅ implements the `Validator` contract
+- ✅ provides `ZodValidator`, a Zod-schema-backed validator
+- ✅ maps Zod errors to Comity validation errors
+- ✅ depends only on `@comity/primitives` and `@comity/validation`
+
+This package does NOT:
+
+- ❌ define validation contracts
+- ❌ provide framework-independent validation logic
+- ❌ depend on any Comity core module beyond `@comity/validation`
+
+---
+
+## Public API
+
+- `ZodValidator` — validator implementing `Validator<T>` from a `ZodType<T>` schema
+
+
+No exhaustive reference; see docs for constraints.
+---
+
+## Documentation
+
+None — no package-specific documentation exists.
+
+---
+
+## Related Packages
+
+- @comity/validation — defines the `Validator` contract this adapter implements
+- @comity/primitives — foundational `Result` types used by the contract
+
+---
+
+## Status
+
+Experimental
+
+_Review Completed: 2026-08-15_
+_Reviewer: Hobiri MAGI (DeepSeek v4 Pro)_
+_Compliance Score: 98% (Green)_

package/dist/cjs/adapter.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZodValidator = void 0;
+const result_1 = require("@comity/primitives/result");
+const zod_error_mapper_js_1 = require("./internal/zod-error-mapper.js");
+/**
+ * Zod-based validator implementation.
+ */
+class ZodValidator {
+    #schema;
+    /**
+     * @param schema - Zod schema to validate against
+     */
+    constructor(schema) {
+        this.#schema = schema;
+    }
+    /**
+     * @inheritdoc
+     */
+    async validate(value) {
+        const result = await this.#schema.safeParseAsync(value);
+        if (result.success) {
+            return (0, result_1.success)(value);
+        }
+        return (0, result_1.failure)((0, zod_error_mapper_js_1.mapZodError)(result.error));
+    }
+}
+exports.ZodValidator = ZodValidator;
+//# sourceMappingURL=adapter.js.map

package/dist/cjs/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZodValidator = void 0;
+var adapter_js_1 = require("./adapter.js");
+Object.defineProperty(exports, "ZodValidator", { enumerable: true, get: function () { return adapter_js_1.ZodValidator; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/internal/zod-error-mapper.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapZodError = mapZodError;
+const errors_1 = require("@comity/validation/errors");
+/**
+ * Maps a ZodError to a ValidationError.
+ *
+ * @param error - The ZodError to map
+ *
+ * @returns A ValidationError representing the ZodError
+ *
+ * @remarks This function transforms the structure of a ZodError into a more generic ValidationError format, preserving the error codes and paths for each validation issue.
+ */
+function mapZodError(error) {
+    const fields = {};
+    for (const issue of error.issues) {
+        const path = formatPath(issue.path);
+        (fields[path] ??= []).push({
+            code: issue.code,
+        });
+    }
+    return new errors_1.ValidationError("failed", {
+        details: {
+            fields,
+        },
+    });
+}
+/**
+ * Formats a path array into a string representation.
+ *
+ * @param path - An array of strings and/or numbers representing the path to a validation issue
+ *
+ * @returns A string representation of the path, where each segment is separated by a dot (.) and array indices are enclosed in square brackets ([]).
+ *
+ * @remarks This function is used to convert the path information from Zod's error structure into a more readable format for the ValidationError.
+ */
+function formatPath(path) {
+    if (path.length === 0) {
+        return "$";
+    }
+    let result = "";
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            result += `[${segment}]`;
+            continue;
+        }
+        if (result.length > 0) {
+            result += ".";
+        }
+        result += String(segment);
+    }
+    return result;
+}
+//# sourceMappingURL=zod-error-mapper.js.map

package/dist/esm/adapter.js

@@ -0,0 +1,25 @@
+import { failure, success } from "@comity/primitives/result";
+import { mapZodError } from "./internal/zod-error-mapper.js";
+/**
+ * Zod-based validator implementation.
+ */
+export class ZodValidator {
+    #schema;
+    /**
+     * @param schema - Zod schema to validate against
+     */
+    constructor(schema) {
+        this.#schema = schema;
+    }
+    /**
+     * @inheritdoc
+     */
+    async validate(value) {
+        const result = await this.#schema.safeParseAsync(value);
+        if (result.success) {
+            return success(value);
+        }
+        return failure(mapZodError(result.error));
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { ZodValidator } from "./adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/internal/zod-error-mapper.js

@@ -0,0 +1,51 @@
+import { ValidationError } from "@comity/validation/errors";
+/**
+ * Maps a ZodError to a ValidationError.
+ *
+ * @param error - The ZodError to map
+ *
+ * @returns A ValidationError representing the ZodError
+ *
+ * @remarks This function transforms the structure of a ZodError into a more generic ValidationError format, preserving the error codes and paths for each validation issue.
+ */
+export function mapZodError(error) {
+    const fields = {};
+    for (const issue of error.issues) {
+        const path = formatPath(issue.path);
+        (fields[path] ??= []).push({
+            code: issue.code,
+        });
+    }
+    return new ValidationError("failed", {
+        details: {
+            fields,
+        },
+    });
+}
+/**
+ * Formats a path array into a string representation.
+ *
+ * @param path - An array of strings and/or numbers representing the path to a validation issue
+ *
+ * @returns A string representation of the path, where each segment is separated by a dot (.) and array indices are enclosed in square brackets ([]).
+ *
+ * @remarks This function is used to convert the path information from Zod's error structure into a more readable format for the ValidationError.
+ */
+function formatPath(path) {
+    if (path.length === 0) {
+        return "$";
+    }
+    let result = "";
+    for (const segment of path) {
+        if (typeof segment === "number") {
+            result += `[${segment}]`;
+            continue;
+        }
+        if (result.length > 0) {
+            result += ".";
+        }
+        result += String(segment);
+    }
+    return result;
+}
+//# sourceMappingURL=zod-error-mapper.js.map

package/dist/types/adapter.d.ts

@@ -0,0 +1,18 @@
+import type { Result } from "@comity/primitives/result";
+import type { Validator } from "@comity/validation";
+import type { ValidationError } from "@comity/validation/errors";
+import type { ZodType } from "zod";
+/**
+ * Zod-based validator implementation.
+ */
+export declare class ZodValidator<T> implements Validator<T> {
+    #private;
+    /**
+     * @param schema - Zod schema to validate against
+     */
+    constructor(schema: ZodType<T>);
+    /**
+     * @inheritdoc
+     */
+    validate(value: T): Promise<Result<T, ValidationError>>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { ZodValidator } from "./adapter.js";

package/dist/types/internal/zod-error-mapper.d.ts

@@ -0,0 +1,12 @@
+import type { ZodError } from "zod";
+import { ValidationError } from "@comity/validation/errors";
+/**
+ * Maps a ZodError to a ValidationError.
+ *
+ * @param error - The ZodError to map
+ *
+ * @returns A ValidationError representing the ZodError
+ *
+ * @remarks This function transforms the structure of a ZodError into a more generic ValidationError format, preserving the error codes and paths for each validation issue.
+ */
+export declare function mapZodError(error: ZodError): ValidationError;

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@comity/validation-zod",
+  "version": "0.9.0",
+  "description": "Zod adapter for @comity/validation contracts.",
+  "type": "module",
+  "private": false,
+  "author": "Filippo Bovo <hello@filippobovo.com>",
+  "license": "MIT",
+  "comity": {
+    "layer": "technology-adapter",
+    "implements": "@comity/validation"
+  },
+  "homepage": "https://github.com/comityjs/framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/comityjs/framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/comityjs/framework/issues"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "comity",
+    "comityjs",
+    "adapter",
+    "typescript",
+    "validation",
+    "zod"
+  ],
+  "files": [
+    "./dist",
+    "!./dist/**/*.map"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {}
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "zod": "^4",
+    "@comity/validation": "0.9.0"
+  },
+  "dependencies": {
+    "@comity/primitives": "0.9.0",
+    "@comity/validation": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "node ../../scripts/build.mjs --watch",
+    "test": "vitest run --coverage",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .ts src"
+  }
+}