@athenna/http 3.0.10 → 3.1.0

package/build/Router/Route.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @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 { RouteJSON } from '#src/Types/Router/RouteJSON';
+import { RequestHandler } from '#src/Types/Contexts/Context';
+import { RouteHandler } from '#src/Types/Router/RouteHandler';
+import { HTTPMethods, FastifySchema, RouteOptions } from 'fastify';
+import { MiddlewareRecord } from '#src/Types/Middlewares/MiddlewareHandler';
+import { MiddlewareRouteType } from '#src/Types/Middlewares/MiddlewareRouteType';
+import { TerminatorRouteType } from '#src/Types/Middlewares/TerminatorRouteType';
+import { InterceptorRouteType } from '#src/Types/Middlewares/InterceptorRouteType';
+export declare class Route {
+    /**
+     * Holds all the route implementations to be registered in the Server.
+     */
+    route: {
+        url?: string;
+        methods: HTTPMethods[];
+        handler?: RequestHandler;
+        name?: string;
+        deleted?: boolean;
+        prefixes?: string[];
+        middlewares?: MiddlewareRecord;
+        fastify?: Partial<RouteOptions>;
+    };
+    constructor(url: string, methods: HTTPMethods[], handler: RouteHandler);
+    /**
+     * Set the route name.
+     *
+     * @example
+     * ```ts
+     * Route.name('profile')
+     * ```
+     */
+    name(name: string): Route;
+    /**
+     * Set fastify vanilla route options.
+     *
+     * @example
+     * ```ts
+     * Route.vanillaOptions({ schema: {} })
+     * ```
+     */
+    vanillaOptions(options: Partial<RouteOptions>): Route;
+    /**
+     * Set a prefix for the route.
+     *
+     * @example
+     * ```ts
+     * Route.prefix('/api/v1')
+     * ```
+     */
+    prefix(prefix: string): Route;
+    /**
+     * Set a named middleware, middleware closure or a MiddlewareContract implementation
+     * in the route.
+     */
+    middleware(middleware: MiddlewareRouteType, prepend?: boolean): Route;
+    /**
+     * Set a named interceptor, interceptor closure or a InterceptorContract implementation
+     * in the route.
+     */
+    interceptor(interceptor: InterceptorRouteType, prepend?: boolean): Route;
+    /**
+     * Set a named terminator, terminator closure or a TerminatorContract implementation
+     * in the route.
+     */
+    terminator(terminator: TerminatorRouteType, prepend?: boolean): Route;
+    /**
+     * Set up all helmet options for route.
+     *
+     * @example
+     * ```ts
+     * Route.helmet({
+     *  dnsPrefetchControl: { allow: true }
+     * })
+     * ```
+     */
+    helmet(options: Omit<import('@fastify/helmet').FastifyHelmetOptions, 'global'>): Route;
+    /**
+     * Set up all schema options for route.
+     *
+     * @example
+     * ```ts
+     * Route.schema({
+     *  body: {
+     *    type: 'array',
+     *    items: {
+     *      oneOf: [{ type: 'string', description: 'User name' }]
+     *    }
+     *  }
+     * })
+     * ```
+     */
+    schema(options: FastifySchema): Route;
+    /**
+     * Set up all rate limit options for route.
+     *
+     * @example
+     * ```ts
+     * Route.rateLimit({
+     *  max: 3,
+     *  timeWindow: '1 minute'
+     * })
+     * ```
+     */
+    rateLimit(options: import('@fastify/rate-limit').RateLimitOptions): Route;
+    /**
+     * Hide the route in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.hide()
+     * ```
+     */
+    hide(): Route;
+    /**
+     * Set the route as deprecated in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.deprecated()
+     * ```
+     */
+    deprecated(): Route;
+    /**
+     * Set a summary for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.summary('List all users')
+     * ```
+     */
+    summary(summary: string): Route;
+    /**
+     * Set a description for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.description('List all users')
+     * ```
+     */
+    description(description: string): Route;
+    /**
+     * Set tags for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.tags(['v1'])
+     * ```
+     */
+    tags(tags: string[]): Route;
+    /**
+     * Set body param for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.body('name', {
+     *  type: 'string',
+     *  description: 'User name'
+     * })
+     * ```
+     */
+    body(name: string, body?: any): Route;
+    /**
+     * Set param for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.param('id', { description: 'Set the user id' })
+     * ```
+     */
+    param(name: string, param?: any): Route;
+    /**
+     * Set query string for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.queryString('page', { description: 'Set the pagination page' })
+     * ```
+     */
+    queryString(name: string, queryString?: any): Route;
+    /**
+     * Set response for the route swagger docs.
+     *
+     * @example
+     * For objects
+     * ```ts
+     * Route.response(200, {
+     *  description: 'Return one user',
+     *  properties: {
+     *    name: { type: 'string', description: 'User name' }
+     *  }
+     * })
+     * ```
+     *
+     * For arrays
+     * ```ts
+     * Route.response(200, {
+     *  description: 'Return users paginated',
+     *  schema: {
+     *    type: 'array'
+     *    oneOf: [
+     *      { type: 'string', description: 'User name' }
+     *    ]
+     *  }
+     * })
+     * ```
+     */
+    response(statusCode: number, response?: any): Route;
+    /**
+     * Set the route security in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.security('apiToken', [])
+     * ```
+     */
+    security(key: string, values: string[]): Route;
+    /**
+     * Set the external documentation url in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.externalDocs('https://github.com/athennaio/docs', 'Athenna Framework Documentation')
+     * ```
+     */
+    externalDocs(url: string, description?: string): Route;
+    /**
+     * Set the type of the content that the API consumes in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.consumes(['json', 'yaml', ...])
+     * ```
+     */
+    consumes(consumes: string[]): Route;
+    /**
+     * Set the type of the content that the API produces in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.produces(['json', 'yaml', ...])
+     * ```
+     */
+    produces(produces: string[]): Route;
+    /**
+     * Get the route as JSON.
+     *
+     * @example
+     * ```ts
+     * Route.toJSON()
+     * ```
+     */
+    toJSON(): RouteJSON;
+    private getUrl;
+    private removeSlashes;
+}

package/build/Router/Route.js

@@ -0,0 +1,447 @@
+/**
+ * @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, Route as RouteHelper } from '@athenna/common';
+import { UndefinedMethodException } from '#src/Exceptions/UndefinedMethodException';
+export class Route {
+    /**
+     * Holds all the route implementations to be registered in the Server.
+     */
+    route;
+    constructor(url, methods, handler) {
+        this.route = {
+            url,
+            methods,
+            deleted: false,
+            prefixes: [],
+            middlewares: {
+                middlewares: [],
+                terminators: [],
+                interceptors: [],
+            },
+            fastify: { schema: {} },
+        };
+        if (Is.String(handler)) {
+            const [controller, method] = handler.split('.');
+            const dependency = ioc.safeUse(`App/Http/Controllers/${controller}`);
+            if (!dependency[method]) {
+                throw new UndefinedMethodException(method, controller);
+            }
+            this.route.handler = dependency[method].bind(dependency);
+        }
+        else {
+            this.route.handler = handler;
+        }
+        RouteHelper.getParamsName(url).forEach(param => this.param(param));
+    }
+    /**
+     * Set the route name.
+     *
+     * @example
+     * ```ts
+     * Route.name('profile')
+     * ```
+     */
+    name(name) {
+        this.route.name = name;
+        return this;
+    }
+    /**
+     * Set fastify vanilla route options.
+     *
+     * @example
+     * ```ts
+     * Route.vanillaOptions({ schema: {} })
+     * ```
+     */
+    vanillaOptions(options) {
+        this.route.fastify = {
+            ...this.route.fastify,
+            ...options,
+        };
+        return this;
+    }
+    /**
+     * Set a prefix for the route.
+     *
+     * @example
+     * ```ts
+     * Route.prefix('/api/v1')
+     * ```
+     */
+    prefix(prefix) {
+        this.route.prefixes.push(prefix);
+        return this;
+    }
+    /**
+     * Set a named middleware, middleware closure or a MiddlewareContract implementation
+     * in the route.
+     */
+    middleware(middleware, prepend = false) {
+        const insertionType = prepend ? 'unshift' : 'push';
+        if (Is.String(middleware)) {
+            const mid = ioc.use(`App/Http/Middlewares/Names/${middleware}`) ||
+                ioc.safeUse(`App/Http/Middlewares/${middleware}`);
+            this.route.middlewares.middlewares[insertionType](mid.handle.bind(mid));
+            return this;
+        }
+        if (Is.Function(middleware)) {
+            this.route.middlewares.middlewares[insertionType](middleware);
+            return this;
+        }
+        this.route.middlewares.middlewares[insertionType](middleware.handle.bind(middleware));
+        return this;
+    }
+    /**
+     * Set a named interceptor, interceptor closure or a InterceptorContract implementation
+     * in the route.
+     */
+    interceptor(interceptor, prepend = false) {
+        const insertionType = prepend ? 'unshift' : 'push';
+        if (Is.String(interceptor)) {
+            const inte = ioc.use(`App/Http/Interceptors/Names/${interceptor}`) ||
+                ioc.safeUse(`App/Http/Interceptors/${interceptor}`);
+            this.route.middlewares.interceptors[insertionType](inte.intercept.bind(inte));
+            return this;
+        }
+        if (Is.Function(interceptor)) {
+            this.route.middlewares.interceptors[insertionType](interceptor);
+            return this;
+        }
+        this.route.middlewares.interceptors[insertionType](interceptor.intercept.bind(interceptor));
+        return this;
+    }
+    /**
+     * Set a named terminator, terminator closure or a TerminatorContract implementation
+     * in the route.
+     */
+    terminator(terminator, prepend = false) {
+        const insertionType = prepend ? 'unshift' : 'push';
+        if (Is.String(terminator)) {
+            const ter = ioc.use(`App/Http/Terminators/Names/${terminator}`) ||
+                ioc.safeUse(`App/Http/Terminators/${terminator}`);
+            this.route.middlewares.terminators[insertionType](ter.terminate.bind(ter));
+            return this;
+        }
+        if (Is.Function(terminator)) {
+            this.route.middlewares.terminators[insertionType](terminator);
+            return this;
+        }
+        this.route.middlewares.terminators[insertionType](terminator.terminate.bind(terminator));
+        return this;
+    }
+    /**
+     * Set up all helmet options for route.
+     *
+     * @example
+     * ```ts
+     * Route.helmet({
+     *  dnsPrefetchControl: { allow: true }
+     * })
+     * ```
+     */
+    helmet(options) {
+        this.route.fastify.helmet = options;
+        return this;
+    }
+    /**
+     * Set up all schema options for route.
+     *
+     * @example
+     * ```ts
+     * Route.schema({
+     *  body: {
+     *    type: 'array',
+     *    items: {
+     *      oneOf: [{ type: 'string', description: 'User name' }]
+     *    }
+     *  }
+     * })
+     * ```
+     */
+    schema(options) {
+        this.route.fastify.schema = options;
+        return this;
+    }
+    /**
+     * Set up all rate limit options for route.
+     *
+     * @example
+     * ```ts
+     * Route.rateLimit({
+     *  max: 3,
+     *  timeWindow: '1 minute'
+     * })
+     * ```
+     */
+    rateLimit(options) {
+        if (!this.route.fastify.config) {
+            this.route.fastify.config = {};
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        this.route.fastify.config.rateLimit = options;
+        return this;
+    }
+    /**
+     * Hide the route in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.hide()
+     * ```
+     */
+    hide() {
+        this.route.fastify.schema.hide = true;
+        return this;
+    }
+    /**
+     * Set the route as deprecated in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.deprecated()
+     * ```
+     */
+    deprecated() {
+        this.route.fastify.schema.deprecated = true;
+        return this;
+    }
+    /**
+     * Set a summary for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.summary('List all users')
+     * ```
+     */
+    summary(summary) {
+        this.route.fastify.schema.summary = summary;
+        return this;
+    }
+    /**
+     * Set a description for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.description('List all users')
+     * ```
+     */
+    description(description) {
+        this.route.fastify.schema.description = description;
+        return this;
+    }
+    /**
+     * Set tags for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.tags(['v1'])
+     * ```
+     */
+    tags(tags) {
+        if (!this.route.fastify.schema.tags) {
+            this.route.fastify.schema.tags = [];
+        }
+        tags.forEach(tag => this.route.fastify.schema.tags.push(tag));
+        return this;
+    }
+    /**
+     * Set body param for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.body('name', {
+     *  type: 'string',
+     *  description: 'User name'
+     * })
+     * ```
+     */
+    body(name, body = {}) {
+        if (!this.route.fastify.schema.body) {
+            this.route.fastify.schema.body = {
+                type: 'object',
+                properties: {},
+            };
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        this.route.fastify.schema.body.properties[name] = body;
+        return this;
+    }
+    /**
+     * Set param for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.param('id', { description: 'Set the user id' })
+     * ```
+     */
+    param(name, param = {}) {
+        if (!this.route.fastify.schema.params) {
+            this.route.fastify.schema.params = {
+                type: 'object',
+                properties: {},
+            };
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        this.route.fastify.schema.params.properties[name] = param;
+        return this;
+    }
+    /**
+     * Set query string for the route swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.queryString('page', { description: 'Set the pagination page' })
+     * ```
+     */
+    queryString(name, queryString = {}) {
+        if (!this.route.fastify.schema.querystring) {
+            this.route.fastify.schema.querystring = {
+                type: 'object',
+                properties: {},
+            };
+        }
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        this.route.fastify.schema.querystring.properties[name] = queryString;
+        return this;
+    }
+    /**
+     * Set response for the route swagger docs.
+     *
+     * @example
+     * For objects
+     * ```ts
+     * Route.response(200, {
+     *  description: 'Return one user',
+     *  properties: {
+     *    name: { type: 'string', description: 'User name' }
+     *  }
+     * })
+     * ```
+     *
+     * For arrays
+     * ```ts
+     * Route.response(200, {
+     *  description: 'Return users paginated',
+     *  schema: {
+     *    type: 'array'
+     *    oneOf: [
+     *      { type: 'string', description: 'User name' }
+     *    ]
+     *  }
+     * })
+     * ```
+     */
+    response(statusCode, response = {}) {
+        if (!this.route.fastify.schema.response) {
+            this.route.fastify.schema.response = {};
+        }
+        this.route.fastify.schema.response[statusCode] = response;
+        return this;
+    }
+    /**
+     * Set the route security in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.security('apiToken', [])
+     * ```
+     */
+    security(key, values) {
+        if (!this.route.fastify.schema.security) {
+            this.route.fastify.schema.security = [];
+        }
+        this.route.fastify.schema.security.push({ [key]: values });
+        return this;
+    }
+    /**
+     * Set the external documentation url in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.externalDocs('https://github.com/athennaio/docs', 'Athenna Framework Documentation')
+     * ```
+     */
+    externalDocs(url, description) {
+        if (!this.route.fastify.schema.externalDocs) {
+            this.route.fastify.schema.externalDocs = {
+                url: '',
+                description: '',
+            };
+        }
+        this.route.fastify.schema.externalDocs.url = url;
+        this.route.fastify.schema.externalDocs.description = description;
+        return this;
+    }
+    /**
+     * Set the type of the content that the API consumes in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.consumes(['json', 'yaml', ...])
+     * ```
+     */
+    consumes(consumes) {
+        this.route.fastify.schema.consumes = consumes;
+        return this;
+    }
+    /**
+     * Set the type of the content that the API produces in swagger docs.
+     *
+     * @example
+     * ```ts
+     * Route.produces(['json', 'yaml', ...])
+     * ```
+     */
+    produces(produces) {
+        this.route.fastify.schema.produces = produces;
+        return this;
+    }
+    /**
+     * Get the route as JSON.
+     *
+     * @example
+     * ```ts
+     * Route.toJSON()
+     * ```
+     */
+    toJSON() {
+        return {
+            url: this.getUrl(),
+            methods: this.route.methods,
+            name: this.route.name,
+            deleted: this.route.deleted,
+            prefixes: this.route.prefixes,
+            handler: this.route.handler,
+            middlewares: this.route.middlewares,
+            fastify: this.route.fastify,
+        };
+    }
+    getUrl() {
+        const url = this.removeSlashes(this.route.url);
+        const prefix = this.route.prefixes
+            .reverse()
+            .map(p => this.removeSlashes(p))
+            .join('');
+        return prefix ? `${prefix}${url === '/' ? '' : url}` : url;
+    }
+    removeSlashes(url) {
+        if (url === '/') {
+            return url;
+        }
+        const matcher = url => `/${url.replace(/^\//, '').replace(/\/$/, '')}`;
+        if (Is.Array(url)) {
+            return url.map(u => matcher(u));
+        }
+        return matcher(url);
+    }
+}