@athenna/http 5.46.0 → 5.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@athenna/http",
-  "version": "5.46.0",
+  "version": "5.47.0",
   "description": "The Athenna Http server. Built on top of fastify.",
   "license": "MIT",
   "author": "João Lenon <lenon@athenna.io>",
@@ -110,7 +110,8 @@
     "ora": "^8.2.0",
     "prettier": "^2.8.8",
     "vite": "^6.4.1",
-    "vite-plugin-restart": "^0.4.2"
+    "vite-plugin-restart": "^0.4.2",
+    "zod": "^4.3.6"
   },
   "c8": {
     "all": true,

package/src/exceptions/ZodValidationException.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @athenna/http
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import type { ZodError } from 'zod';
+import { HttpException } from '#src/exceptions/HttpException';
+export declare class ZodValidationException extends HttpException {
+    constructor(error: ZodError);
+}

package/src/exceptions/ZodValidationException.js

@@ -0,0 +1,19 @@
+/**
+ * @athenna/http
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { HttpException } from '#src/exceptions/HttpException';
+export class ZodValidationException extends HttpException {
+    constructor(error) {
+        const name = 'ValidationException';
+        const code = 'E_VALIDATION_ERROR';
+        const status = 422;
+        const message = 'Validation error happened.';
+        const details = error.issues;
+        super({ name, message, status, code, details });
+    }
+}

package/src/index.d.ts

@@ -32,6 +32,7 @@ declare module 'fastify' {
     }
 }
 export * from '#src/types';
+export * from '#src/router/RouteSchema';
 export * from '#src/context/Request';
 export * from '#src/context/Response';
 export * from '#src/annotations/Controller';

package/src/index.js

@@ -7,6 +7,7 @@
  * file that was distributed with this source code.
  */
 export * from '#src/types';
+export * from '#src/router/RouteSchema';
 export * from '#src/context/Request';
 export * from '#src/context/Response';
 export * from '#src/annotations/Controller';

package/src/router/Route.d.ts

@@ -7,8 +7,9 @@
  * file that was distributed with this source code.
  */
 import type { RouteJson, RouteHandler, RequestHandler, MiddlewareRecord, MiddlewareRouteType, TerminatorRouteType, InterceptorRouteType } from '#src/types';
-import type { HTTPMethods, FastifySchema, RouteOptions } from 'fastify';
+import type { HTTPMethods, RouteOptions } from 'fastify';
 import { Macroable } from '@athenna/common';
+import { type RouteSchemaOptions } from '#src/router/RouteSchema';
 export declare class Route extends Macroable {
     /**
      * Holds all the route implementations to be registered in the Server.
@@ -111,7 +112,7 @@ export declare class Route extends Macroable {
      * })
      * ```
      */
-    schema(options: FastifySchema): Route;
+    schema(options: RouteSchemaOptions): Route;
     /**
      * Set up all rate limit options for route.
      *

package/src/router/Route.js

@@ -9,6 +9,7 @@
 import { Is, Options, Macroable, Route as RouteHelper } from '@athenna/common';
 import { UndefinedMethodException } from '#src/exceptions/UndefinedMethodException';
 import { NotFoundValidatorException } from '#src/exceptions/NotFoundValidatorException';
+import { normalizeRouteSchema } from '#src/router/RouteSchema';
 import { NotFoundMiddlewareException } from '#src/exceptions/NotFoundMiddlewareException';
 export class Route extends Macroable {
     constructor(url, methods, handler) {
@@ -237,7 +238,18 @@ export class Route extends Macroable {
      * ```
      */
     schema(options) {
-        this.route.fastify.schema = options;
+        const { schema, zod } = normalizeRouteSchema(options);
+        this.route.fastify.schema = schema;
+        if (zod) {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            this.route.fastify.config.zod = zod;
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            delete this.route.fastify.config.zod;
+        }
         return this;
     }
     /**

package/src/router/RouteResource.d.ts

@@ -8,6 +8,7 @@
  */
 import type { RouteResourceTypes, TerminatorRouteType, MiddlewareRouteType, InterceptorRouteType } from '#src/types';
 import { Route } from '#src/router/Route';
+import type { RouteSchemaOptions } from '#src/router/RouteSchema';
 import { Macroable } from '@athenna/common';
 export declare class RouteResource extends Macroable {
     /**
@@ -112,6 +113,18 @@ export declare class RouteResource extends Macroable {
      * ```
      */
     rateLimit(options: import('@fastify/rate-limit').RateLimitOptions): RouteResource;
+    /**
+     * Set up schema options for specific route resource methods.
+     *
+     * @example
+     * ```ts
+     * Route.resource('/test', 'TestController').schema({
+     *  index: { response: { 200: { type: 'object' } } },
+     *  store: { body: { type: 'object' } }
+     * })
+     * ```
+     */
+    schema(options: Partial<Record<RouteResourceTypes, RouteSchemaOptions>>): RouteResource;
     /**
      * Filter routes by name.
      */

package/src/router/RouteResource.js

@@ -171,6 +171,26 @@ export class RouteResource extends Macroable {
         this.routes.forEach(route => route.rateLimit(options));
         return this;
     }
+    /**
+     * Set up schema options for specific route resource methods.
+     *
+     * @example
+     * ```ts
+     * Route.resource('/test', 'TestController').schema({
+     *  index: { response: { 200: { type: 'object' } } },
+     *  store: { body: { type: 'object' } }
+     * })
+     * ```
+     */
+    schema(options) {
+        Object.entries(options).forEach(([name, schema]) => {
+            if (!schema) {
+                return;
+            }
+            this.filter([name]).forEach(route => route.schema(schema));
+        });
+        return this;
+    }
     /**
      * Filter routes by name.
      */

package/src/router/RouteSchema.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @athenna/http
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import type { ZodAny } from 'zod';
+import type { FastifyReply, FastifyRequest, FastifySchema } from 'fastify';
+type ZodRequestSchema = Partial<Record<'body' | 'headers' | 'params' | 'querystring', ZodAny>>;
+type ZodResponseSchema = Record<number | string, ZodAny>;
+export type RouteSchemaOptions = FastifySchema & {
+    body?: FastifySchema['body'] | ZodAny;
+    headers?: FastifySchema['headers'] | ZodAny;
+    params?: FastifySchema['params'] | ZodAny;
+    querystring?: FastifySchema['querystring'] | ZodAny;
+    response?: FastifySchema['response'] | ZodResponseSchema;
+};
+export type RouteZodSchemas = {
+    request: ZodRequestSchema;
+    response: ZodResponseSchema;
+};
+export declare function normalizeRouteSchema(options: RouteSchemaOptions): {
+    schema: FastifySchema;
+    zod: RouteZodSchemas | null;
+};
+export declare function parseRequestWithZod(req: FastifyRequest, schemas: RouteZodSchemas): Promise<void>;
+export declare function parseResponseWithZod(reply: FastifyReply, payload: any, schemas: RouteZodSchemas): Promise<any>;
+export {};

package/src/router/RouteSchema.js

@@ -0,0 +1,144 @@
+/**
+ * @athenna/http
+ *
+ * (c) João Lenon <lenon@athenna.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { Is } from '@athenna/common';
+import { ZodValidationException } from '#src/exceptions/ZodValidationException';
+export function normalizeRouteSchema(options) {
+    const request = {};
+    const response = {};
+    const schema = { ...options };
+    const requestKeys = ['body', 'headers', 'params', 'querystring'];
+    requestKeys.forEach(key => {
+        if (!isZodSchema(options[key])) {
+            return;
+        }
+        request[key] = options[key];
+        schema[key] = toJsonSchema(options[key], 'input');
+    });
+    if (options.response && Is.Object(options.response)) {
+        schema.response = { ...options.response };
+        Object.entries(options.response).forEach(([statusCode, value]) => {
+            if (!isZodSchema(value)) {
+                return;
+            }
+            response[statusCode] = value;
+            schema.response[statusCode] = toJsonSchema(value, 'output');
+        });
+    }
+    const hasZodSchemas = Object.keys(request).length > 0 || Object.keys(response).length > 0;
+    return {
+        schema,
+        zod: hasZodSchemas ? { request, response } : null
+    };
+}
+export async function parseRequestWithZod(req, schemas) {
+    const requestSchemas = schemas.request;
+    if (requestSchemas.body) {
+        req.body = await parseSchema(requestSchemas.body, req.body);
+    }
+    if (requestSchemas.headers) {
+        req.headers = await parseSchema(requestSchemas.headers, req.headers);
+    }
+    if (requestSchemas.params) {
+        req.params = await parseSchema(requestSchemas.params, coerceDataForValidation(requestSchemas.params, req.params));
+    }
+    if (requestSchemas.querystring) {
+        req.query = await parseSchema(requestSchemas.querystring, coerceDataForValidation(requestSchemas.querystring, req.query));
+    }
+}
+export async function parseResponseWithZod(reply, payload, schemas) {
+    const schema = getResponseSchema(reply.statusCode, schemas.response);
+    if (!schema) {
+        return payload;
+    }
+    return parseSchema(schema, payload);
+}
+function getResponseSchema(statusCode, schemas) {
+    return (schemas[statusCode] ||
+        schemas[String(statusCode)] ||
+        schemas[`${String(statusCode)[0]}xx`] ||
+        schemas.default ||
+        null);
+}
+async function parseSchema(schema, data) {
+    const result = await schema.safeParseAsync(data);
+    if (!result.success) {
+        throw new ZodValidationException(result.error);
+    }
+    return result.data;
+}
+function toJsonSchema(schema, io) {
+    const jsonSchemaMethod = schema['~standard']?.jsonSchema?.[io] ||
+        schema.toJSONSchema;
+    if (!jsonSchemaMethod) {
+        return {};
+    }
+    const jsonSchema = jsonSchemaMethod({
+        target: 'draft-07',
+        libraryOptions: { unrepresentable: 'any' }
+    });
+    delete jsonSchema.$schema;
+    return jsonSchema;
+}
+function coerceDataForValidation(schema, data) {
+    return coerceDataByJsonSchema(toJsonSchema(schema, 'input'), data);
+}
+function coerceDataByJsonSchema(schema, data) {
+    if (Is.Undefined(data) || Is.Null(data) || !schema) {
+        return data;
+    }
+    if (schema.anyOf) {
+        return coerceWithAlternatives(schema.anyOf, data);
+    }
+    if (schema.oneOf) {
+        return coerceWithAlternatives(schema.oneOf, data);
+    }
+    if (schema.type === 'object' && Is.Object(data)) {
+        const coerced = { ...data };
+        const properties = schema.properties || {};
+        Object.entries(properties).forEach(([key, childSchema]) => {
+            if (!Object.hasOwn(coerced, key)) {
+                return;
+            }
+            coerced[key] = coerceDataByJsonSchema(childSchema, coerced[key]);
+        });
+        return coerced;
+    }
+    if (schema.type === 'array' && Is.Array(data) && schema.items) {
+        return data.map(item => coerceDataByJsonSchema(schema.items, item));
+    }
+    if (schema.type === 'number' || schema.type === 'integer') {
+        return coerceNumber(data, schema.type === 'integer');
+    }
+    return data;
+}
+function coerceWithAlternatives(schemas, data) {
+    let coerced = data;
+    schemas.forEach(schema => {
+        coerced = coerceDataByJsonSchema(schema, coerced);
+    });
+    return coerced;
+}
+function coerceNumber(value, integerOnly) {
+    if (!Is.String(value) || value.trim() === '') {
+        return value;
+    }
+    const parsed = integerOnly ? Number.parseInt(value, 10) : Number(value);
+    if (Number.isNaN(parsed)) {
+        return value;
+    }
+    if (integerOnly && !Number.isInteger(parsed)) {
+        return value;
+    }
+    return parsed;
+}
+function isZodSchema(value) {
+    return (Is.Defined(value) &&
+        Is.Function(value.parse) &&
+        Is.Function(value.safeParseAsync));
+}

package/src/server/ServerImpl.d.ts

@@ -136,4 +136,11 @@ export declare class ServerImpl extends Macroable {
      * Add a new OPTIONS route to the http server.
      */
     options(options: Omit<RouteJson, 'methods'>): void;
+    private toRouteHooks;
+    private getFastifyOptionsWithOpenApiSchema;
+    private getOpenApiRouteSchema;
+    private getOpenApiPathCandidates;
+    private normalizePath;
+    private mergeFastifySchemas;
+    private mergeZodSchemas;
 }

package/src/server/ServerImpl.js

@@ -7,6 +7,7 @@
  * file that was distributed with this source code.
  */
 import fastify from 'fastify';
+import { normalizeRouteSchema, parseRequestWithZod, parseResponseWithZod } from '#src/router/RouteSchema';
 import { Options, Macroable, Is } from '@athenna/common';
 import { FastifyHandler } from '#src/handlers/FastifyHandler';
 export class ServerImpl extends Macroable {
@@ -187,9 +188,15 @@ export class ServerImpl extends Macroable {
             return;
         }
         const { middlewares, interceptors, terminators } = options.middlewares;
+        const fastifyOptions = this.getFastifyOptionsWithOpenApiSchema(options);
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        const zodSchemas = fastifyOptions?.config?.zod;
         const route = {
             onSend: [],
+            preValidation: [],
             preHandler: [],
+            preSerialization: [],
             onResponse: [],
             url: options.url,
             method: options.methods,
@@ -204,6 +211,12 @@ export class ServerImpl extends Macroable {
         if (terminators.length) {
             route.onResponse = terminators.map(t => FastifyHandler.terminate(t));
         }
+        if (zodSchemas) {
+            route.preValidation = [async (req) => parseRequestWithZod(req, zodSchemas)];
+            route.preSerialization = [
+                async (_, reply, payload) => parseResponseWithZod(reply, payload, zodSchemas)
+            ];
+        }
         if (options.data && Is.Array(route.preHandler)) {
             route.preHandler?.unshift((req, _, done) => {
                 req.data = {
@@ -213,7 +226,17 @@ export class ServerImpl extends Macroable {
                 done();
             });
         }
-        this.fastify.route({ ...route, ...options.fastify });
+        if (zodSchemas) {
+            fastifyOptions.preValidation = [
+                ...this.toRouteHooks(route.preValidation),
+                ...this.toRouteHooks(fastifyOptions.preValidation)
+            ];
+            fastifyOptions.preSerialization = [
+                ...this.toRouteHooks(route.preSerialization),
+                ...this.toRouteHooks(fastifyOptions.preSerialization)
+            ];
+        }
+        this.fastify.route({ ...route, ...fastifyOptions });
     }
     /**
      * Add a new GET route to the http server.
@@ -257,4 +280,91 @@ export class ServerImpl extends Macroable {
     options(options) {
         this.route({ ...options, methods: ['OPTIONS'] });
     }
+    toRouteHooks(hooks) {
+        if (!hooks) {
+            return [];
+        }
+        return Array.isArray(hooks) ? hooks : [hooks];
+    }
+    getFastifyOptionsWithOpenApiSchema(options) {
+        const automaticSchema = this.getOpenApiRouteSchema(options);
+        const fastifyOptions = { ...options.fastify };
+        if (!automaticSchema) {
+            return fastifyOptions;
+        }
+        const normalizedSchema = normalizeRouteSchema(automaticSchema);
+        const currentConfig = { ...(fastifyOptions.config || {}) };
+        fastifyOptions.schema = this.mergeFastifySchemas(normalizedSchema.schema, fastifyOptions.schema);
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        const currentZod = currentConfig.zod;
+        const mergedZod = this.mergeZodSchemas(normalizedSchema.zod, currentZod);
+        if (mergedZod) {
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            currentConfig.zod = mergedZod;
+        }
+        fastifyOptions.config = currentConfig;
+        return fastifyOptions;
+    }
+    getOpenApiRouteSchema(options) {
+        const paths = Config.get('openapi.paths', {});
+        const methods = options.methods || [];
+        if (!Is.Object(paths) || !options.url || !methods.length) {
+            return null;
+        }
+        const candidates = this.getOpenApiPathCandidates(options.url);
+        for (const candidate of candidates) {
+            const pathConfig = paths[candidate];
+            if (!Is.Object(pathConfig)) {
+                continue;
+            }
+            for (const method of methods) {
+                const methodConfig = pathConfig[method.toLowerCase()];
+                if (Is.Object(methodConfig)) {
+                    return methodConfig;
+                }
+            }
+        }
+        return null;
+    }
+    getOpenApiPathCandidates(url) {
+        const normalized = this.normalizePath(url);
+        const openApi = normalized.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+        return Array.from(new Set([normalized, openApi]));
+    }
+    normalizePath(url) {
+        if (url === '/') {
+            return url;
+        }
+        return `/${url.replace(/^\//, '').replace(/\/$/, '')}`;
+    }
+    mergeFastifySchemas(base, override) {
+        const merged = {
+            ...base,
+            ...override
+        };
+        if (base?.response || override?.response) {
+            merged.response = {
+                ...(base?.response || {}),
+                ...(override?.response || {})
+            };
+        }
+        return merged;
+    }
+    mergeZodSchemas(base, override) {
+        if (!base && !override) {
+            return null;
+        }
+        return {
+            request: {
+                ...(base?.request || {}),
+                ...(override?.request || {})
+            },
+            response: {
+                ...(base?.response || {}),
+                ...(override?.response || {})
+            }
+        };
+    }
 }