@bram-dc/fastify-type-provider-zod 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 turkerdev
+
+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,145 @@
+# Fastify Type Provider Zod
+
+[![NPM Version](https://img.shields.io/npm/v/fastify-type-provider-zod.svg)](https://npmjs.org/package/fastify-type-provider-zod)
+[![NPM Downloads](https://img.shields.io/npm/dm/fastify-type-provider-zod.svg)](https://npmjs.org/package/fastify-type-provider-zod)
+[![Build Status](https://github.com//bram-dc/fastify-type-provider-zod/workflows/CI/badge.svg)](https://github.com/bram-dc/fastify-type-provider-zod/actions)
+
+## How to use?
+
+```js
+import Fastify from "fastify";
+import { ZodSerializerCompiler, ZodValidatorCompiler, ZodTypeProvider } from "fastify-type-provider-zod";
+import z from "zod";
+
+const app = Fastify()
+
+// Add schema validator and serializer
+app.setValidatorCompiler(ZodValidatorCompiler);
+app.setSerializerCompiler(ZodSerializerCompiler);
+
+app.withTypeProvider<ZodTypeProvider>().route({
+  method: "GET",
+  url: "/",
+  // Define your schema
+  schema: {
+    querystring: z.object({
+      name: z.string().min(4),
+    }),
+    response: {
+      200: z.string(),
+    },
+  },
+  handler: (req, res) => {
+    res.send(req.query.name);
+  },
+});
+
+app.listen({ port: 4949 });
+```
+
+## How to use together with @fastify/swagger
+
+```ts
+import fastify from "fastify";
+import fastifySwagger from "@fastify/swagger";
+import fastifySwaggerUI from "@fastify/swagger-ui";
+import { z } from "zod";
+
+import {
+  jsonSchemaTransform,
+  createJsonSchemaTransform,
+  ZodSerializerCompiler,
+  ZodValidatorCompiler,
+  ZodTypeProvider,
+} from "fastify-type-provider-zod";
+
+const app = fastify();
+app.setValidatorCompiler(ZodValidatorCompiler);
+app.setSerializerCompiler(ZodSerializerCompiler);
+
+app.register(fastifySwagger, {
+  openapi: {
+    info: {
+      title: "SampleApi",
+      description: "Sample backend service",
+      version: "1.0.0",
+    },
+    servers: [],
+  },
+  transform: jsonSchemaTransform,
+  // You can also create transform with custom skiplist of endpoints that should not be included in the specification:
+  //
+  // transform: createJsonSchemaTransform({
+  //   skipList: [ "/documentation/static/*" ]
+  // })
+  
+  // In order to create refs to the schemas, you need to provide the schemas to the transformObject using createJsonSchemaTransformObject
+  //
+  // transformObject: createJsonSchemaTransformObject({
+  //    schemas: {
+  //      User: z.object({
+  //        id: z.string(),
+  //        name: z.string(),
+  //      }),
+  //    }
+  // }),
+});
+
+app.register(fastifySwaggerUI, {
+  routePrefix: "/documentation",
+});
+
+const LOGIN_SCHEMA = z.object({
+  username: z.string().max(32).describe("Some description for username"),
+  password: z.string().max(32),
+});
+
+app.after(() => {
+  app.withTypeProvider<ZodTypeProvider>().route({
+    method: "POST",
+    url: "/login",
+    schema: { body: LOGIN_SCHEMA },
+    handler: (req, res) => {
+      res.send("ok");
+    },
+  });
+});
+
+async function run() {
+  await app.ready();
+
+  await app.listen({
+    port: 4949,
+  });
+
+  console.log(`Documentation running at http://localhost:4949/documentation`);
+}
+
+run();
+```
+
+## How to create a plugin?
+
+```ts
+import { z } from "zod";
+import { FastifyPluginAsyncZod } from "fastify-type-provider-zod";
+
+const plugin: FastifyPluginAsyncZod = async function (fastify, _opts) {
+  fastify.route({
+    method: "GET",
+    url: "/",
+    // Define your schema
+    schema: {
+      querystring: z.object({
+        name: z.string().min(4),
+      }),
+      response: {
+        200: z.string(),
+      },
+    },
+    handler: (req, res) => {
+      res.send(req.query.name);
+    },
+  });
+};
+```

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import type { FastifyPluginAsync, FastifyPluginCallback, FastifyPluginOptions, FastifySchema, FastifySchemaCompiler, FastifyTypeProvider, RawServerBase, RawServerDefault } from "fastify";
+import type { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
+import type { FastifySerializerCompiler } from "fastify/types/schema";
+import type { z } from "zod";
+type FreeformRecord = Record<string, any>;
+export declare const ResponseValidationError: import("@fastify/error").FastifyErrorConstructor<{
+    code: string;
+}, [{
+    cause: Error;
+}]>;
+export declare const InvalidSchemaError: import("@fastify/error").FastifyErrorConstructor<{
+    code: string;
+}, [string]>;
+export interface ZodTypeProvider extends FastifyTypeProvider {
+    validator: this["schema"] extends z.ZodTypeAny ? z.output<this["schema"]> : unknown;
+    serializer: this["schema"] extends z.ZodTypeAny ? z.input<this["schema"]> : unknown;
+}
+interface Schema extends FastifySchema {
+    hide?: boolean;
+}
+export declare const createJsonSchemaTransform: ({ skipList }: {
+    skipList: readonly string[];
+}) => ({ schema, url }: {
+    schema: Schema;
+    url: string;
+}) => {
+    schema: Schema;
+    url: string;
+} | {
+    schema: FreeformRecord;
+    url: string;
+};
+export declare const jsonSchemaTransform: ({ schema, url }: {
+    schema: Schema;
+    url: string;
+}) => {
+    schema: Schema;
+    url: string;
+} | {
+    schema: FreeformRecord;
+    url: string;
+};
+export declare const ZodValidatorCompiler: FastifySchemaCompiler<z.ZodAny>;
+export declare const ZodSerializerCompiler: FastifySerializerCompiler<z.ZodAny | {
+    properties: z.ZodAny;
+}>;
+export declare const createJsonSchemaTransformObject: ({ schemas: zodSchemas }: {
+    schemas: Record<string, z.ZodTypeAny>;
+}) => (input: {
+    swaggerObject: Partial<OpenAPIV2.Document>;
+} | {
+    openapiObject: Partial<OpenAPIV3.Document | OpenAPIV3_1.Document>;
+}) => any;
+/**
+ * FastifyPluginCallbackZod with Zod automatic type inference
+ *
+ * @example
+ * ```typescript
+ * import { FastifyPluginCallbackZod } from "fastify-type-provider-zod"
+ *
+ * const plugin: FastifyPluginCallbackZod = (fastify, options, done) => {
+ *   done()
+ * }
+ * ```
+ */
+export type FastifyPluginCallbackZod<Options extends FastifyPluginOptions = Record<never, never>, Server extends RawServerBase = RawServerDefault> = FastifyPluginCallback<Options, Server, ZodTypeProvider>;
+/**
+ * FastifyPluginAsyncZod with Zod automatic type inference
+ *
+ * @example
+ * ```typescript
+ * import { FastifyPluginAsyncZod } from "fastify-type-provider-zod"
+ *
+ * const plugin: FastifyPluginAsyncZod = async (fastify, options) => {
+ * }
+ * ```
+ */
+export type FastifyPluginAsyncZod<Options extends FastifyPluginOptions = Record<never, never>, Server extends RawServerBase = RawServerDefault> = FastifyPluginAsync<Options, Server, ZodTypeProvider>;
+export {};

package/dist/index.js

@@ -0,0 +1,160 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJsonSchemaTransformObject = exports.ZodSerializerCompiler = exports.ZodValidatorCompiler = exports.jsonSchemaTransform = exports.createJsonSchemaTransform = exports.InvalidSchemaError = exports.ResponseValidationError = void 0;
+const error_1 = __importDefault(require("@fastify/error"));
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const defaultSkipList = [
+    "/documentation/",
+    "/documentation/initOAuth",
+    "/documentation/json",
+    "/documentation/uiConfig",
+    "/documentation/yaml",
+    "/documentation/*",
+    "/documentation/static/*",
+];
+exports.ResponseValidationError = (0, error_1.default)("FST_ERR_RESPONSE_VALIDATION", "Response doesn't match the schema", 500);
+exports.InvalidSchemaError = (0, error_1.default)("FST_ERR_INVALID_SCHEMA", "Invalid schema passed: %s", 500);
+const zodToJsonSchemaOptions = {
+    target: "openApi3",
+    $refStrategy: "none",
+};
+const createJsonSchemaTransform = ({ skipList }) => {
+    return ({ schema, url }) => {
+        if (!schema) {
+            return {
+                schema,
+                url,
+            };
+        }
+        const { response, headers, querystring, body, params, hide, ...rest } = schema;
+        const transformed = {};
+        if (skipList.includes(url) || hide) {
+            transformed.hide = true;
+            return { schema: transformed, url };
+        }
+        const zodSchemas = { headers, querystring, body, params };
+        for (const prop in zodSchemas) {
+            const zodSchema = zodSchemas[prop];
+            if (zodSchema) {
+                transformed[prop] = (0, zod_to_json_schema_1.zodToJsonSchema)(zodSchema, zodToJsonSchemaOptions);
+            }
+        }
+        if (response) {
+            transformed.response = {};
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            for (const prop in response) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const schema = resolveSchema(response[prop]);
+                const transformedResponse = (0, zod_to_json_schema_1.zodToJsonSchema)(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                schema, zodToJsonSchemaOptions);
+                transformed.response[prop] = transformedResponse;
+            }
+        }
+        for (const prop in rest) {
+            const meta = rest[prop];
+            if (meta) {
+                transformed[prop] = meta;
+            }
+        }
+        return { schema: transformed, url };
+    };
+};
+exports.createJsonSchemaTransform = createJsonSchemaTransform;
+exports.jsonSchemaTransform = (0, exports.createJsonSchemaTransform)({
+    skipList: defaultSkipList,
+});
+const ZodValidatorCompiler = ({ schema }) => (data) => {
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return { value: result.data };
+    }
+    else {
+        return {
+            error: result.error.errors.map(error => ({
+                keyword: error.code,
+                instancePath: `/${error.path.join("/")}`,
+                schemaPath: `#/${error.path.join("/")}/${error.code}`,
+                params: {
+                    code: error.code,
+                    zodError: result.error,
+                },
+                message: error.message,
+            })),
+        };
+    }
+};
+exports.ZodValidatorCompiler = ZodValidatorCompiler;
+const resolveSchema = (maybeSchema) => {
+    if ("safeParse" in maybeSchema) {
+        return maybeSchema;
+    }
+    if ("properties" in maybeSchema) {
+        return maybeSchema.properties;
+    }
+    throw new exports.InvalidSchemaError(JSON.stringify(maybeSchema));
+};
+const ZodSerializerCompiler = ({ schema: maybeSchema }) => (data) => {
+    const schema = resolveSchema(maybeSchema);
+    const result = schema.safeParse(data);
+    if (result.success) {
+        return JSON.stringify(result.data);
+    }
+    throw new exports.ResponseValidationError({ cause: result.error });
+};
+exports.ZodSerializerCompiler = ZodSerializerCompiler;
+const createJsonSchemaTransformObject = ({ schemas: zodSchemas }) => (input) => {
+    if ("swaggerObject" in input) {
+        console.warn("This package currently does not support component references for Swagger 2.0");
+        return input.swaggerObject;
+    }
+    const schemas = {};
+    for (const key in zodSchemas) {
+        schemas[key] = (0, zod_to_json_schema_1.zodToJsonSchema)(zodSchemas[key], zodToJsonSchemaOptions);
+    }
+    const document = {
+        ...input.openapiObject,
+        components: {
+            ...input.openapiObject.components,
+            schemas: {
+                ...input.openapiObject.components?.schemas,
+                ...schemas,
+            },
+        },
+    };
+    const componentMapVK = new Map();
+    Object.entries(schemas).forEach(([key, value]) => componentMapVK.set(JSON.stringify(value), key));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function componentReplacer(key, value) {
+        if (typeof value !== "object") {
+            return value;
+        }
+        // Check if the parent is the schemas object, if so, return the value as is
+        if (this === document.components.schemas) {
+            return value;
+        }
+        const stringifiedValue = JSON.stringify(value);
+        if (componentMapVK.has(stringifiedValue)) {
+            return { $ref: `#/components/schemas/${componentMapVK.get(stringifiedValue)}` };
+        }
+        if (value.nullable === true) {
+            const nonNullableValue = { ...value };
+            delete nonNullableValue.nullable;
+            const stringifiedNonNullableValue = JSON.stringify(nonNullableValue);
+            if (componentMapVK.has(stringifiedNonNullableValue)) {
+                return {
+                    anyOf: [
+                        { $ref: `#/components/schemas/${componentMapVK.get(stringifiedNonNullableValue)}` },
+                    ],
+                    nullable: true,
+                };
+            }
+        }
+        return value;
+    }
+    return JSON.parse(JSON.stringify(document, componentReplacer));
+};
+exports.createJsonSchemaTransformObject = createJsonSchemaTransformObject;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@bram-dc/fastify-type-provider-zod",
+  "private": false,
+  "version": "3.0.0",
+  "description": "Zod Type Provider for Fastify@5",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && npm run typescript && vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "typescript": "tsd",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0",
+    "zod": "^3.23.8"
+  },
+  "repository": {
+    "url": "https://github.com/bram-dc/fastify-type-provider-zod"
+  },
+  "keywords": [
+    "fastify",
+    "zod",
+    "type",
+    "provider"
+  ],
+  "author": "turkerd",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/bram-dc/fastify-type-provider-zod/issues"
+  },
+  "homepage": "https://github.com/bram-dc/fastify-type-provider-zod",
+  "dependencies": {
+    "@fastify/error": "^4.0.0",
+    "zod-to-json-schema": "^3.23.3"
+  },
+  "devDependencies": {
+    "@fastify/swagger": "^9.0.0",
+    "@fastify/swagger-ui": "^5.0.1",
+    "@stylistic/eslint-plugin": "^2.8.0",
+    "@types/node": "^22.5.5",
+    "eslint": "^9.10.0",
+    "fastify": "^5.0.0",
+    "fastify-plugin": "^5.0.0",
+    "oas-validator": "^5.0.8",
+    "openapi-types": "^12.1.3",
+    "tsd": "^0.31.2",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.6.0",
+    "vitest": "^2.1.1",
+    "zod": "^3.23.8"
+  },
+  "tsd": {
+    "directory": "types"
+  }
+}