@visulima/api-platform 1.0.0

package/src/connect/middleware/serializers-middleware.ts

@@ -0,0 +1,121 @@
+import type { NextHandler } from "@visulima/connect";
+import accepts from "accepts";
+import { header as headerCase } from "case";
+import type { NextApiResponse } from "next";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { Serializer } from "../serializers/types";
+import xmlTransformer from "../serializers/xml";
+import yamlTransformer from "../serializers/yaml";
+
+function hasJsonStructure(string_: any): boolean {
+    if (typeof string_ !== "string") {
+        return false;
+    }
+
+    try {
+        const result = JSON.parse(string_);
+        const type = Object.prototype.toString.call(result);
+
+        return type === "[object Object]" || type === "[object Array]";
+    } catch {
+        return false;
+    }
+}
+
+const contentTypeKey = "Content-Type";
+
+// eslint-disable-next-line max-len
+const serialize = <Request extends IncomingMessage, Response extends ServerResponse>(
+    serializers: Serializers,
+    request: Request,
+    response: Response | NextApiResponse,
+    data: any,
+    options: {
+        defaultContentType: string;
+    },
+    // eslint-disable-next-line radar/cognitive-complexity
+) => {
+    const contentType = response.getHeader(contentTypeKey) as string | undefined;
+
+    // skip serialization when Content-Type is already set
+    if (typeof contentType === "string") {
+        return data;
+    }
+
+    const accept = accepts(request);
+    const types: string[] = [...(accept.types() as string[]), options.defaultContentType];
+
+    let serializedData = data;
+
+    // eslint-disable-next-line no-restricted-syntax
+    types.every((type) => {
+        let breakTypes = false;
+
+        serializers.forEach(({ regex, serializer }) => {
+            if (!regex.test(type)) {
+                return;
+            }
+
+            response.setHeader(contentTypeKey, type);
+            serializedData = serializer(serializedData);
+            breakTypes = true;
+        });
+
+        if (!breakTypes) {
+            if (/yaml|yml/.test(type)) {
+                response.setHeader(contentTypeKey, type);
+
+                serializedData = yamlTransformer(hasJsonStructure(data) ? JSON.parse(data) : data);
+            } else if (/xml/.test(type)) {
+                response.setHeader(contentTypeKey, type);
+
+                serializedData = xmlTransformer({
+                    [headerCase(`${request.url?.replace("/api/", "")}`.trim())]: hasJsonStructure(data) ? JSON.parse(data) : data,
+                });
+            }
+        }
+
+        return breakTypes;
+    });
+
+    // eslint-disable-next-line no-param-reassign
+    return serializedData;
+};
+
+// eslint-disable-next-line max-len
+const serializersMiddleware = (serializers: Serializers = [], defaultContentType: string = "application/json; charset=utf-8") => async <Request extends IncomingMessage, Response extends ServerResponse>(request: Request, response: Response | NextApiResponse, next: NextHandler) => {
+    if (typeof (response as NextApiResponse)?.send === "function") {
+        const oldSend = (response as NextApiResponse).send;
+
+        (response as NextApiResponse).send = (data) => {
+            (response as NextApiResponse).send = oldSend;
+
+            // eslint-disable-next-line no-param-reassign
+            data = serialize<Request, Response>(serializers, request, response, data, { defaultContentType });
+
+            return (response as NextApiResponse).send(data);
+        };
+    } else {
+        const oldEnd = response.end;
+
+        // @ts-ignore
+        response.end = (data, ...arguments_) => {
+            response.end = oldEnd;
+
+            // eslint-disable-next-line no-param-reassign
+            data = serialize<Request, Response>(serializers, request, response, data, { defaultContentType });
+
+            // @ts-ignore
+            return response.end(data, ...arguments_);
+        };
+    }
+
+    return next();
+};
+
+export type Serializers = {
+    regex: RegExp;
+    serializer: Serializer;
+}[];
+export default serializersMiddleware;

package/src/connect/serializers/types.d.ts

@@ -0,0 +1 @@
+export type Serializer = (data: any) => string | Buffer | Uint8Array;

package/src/connect/serializers/xml.ts

@@ -0,0 +1,13 @@
+import type { XmlElement } from "jstoxml";
+import { toXML } from "jstoxml";
+
+import type { Serializer } from "./types";
+
+const config = {
+    header: true,
+    indent: "  ",
+};
+
+const xmlTransformer: Serializer = (data?: XmlElement | XmlElement[]) => toXML(data, config);
+
+export default xmlTransformer;

package/src/connect/serializers/yaml.ts

@@ -0,0 +1,7 @@
+import { stringify } from "yaml";
+
+import type { Serializer } from "./types";
+
+const yamlTransformer: Serializer = (data) => stringify(data, { indent: 2 });
+
+export default yamlTransformer;

package/src/error-handler/jsonapi-error-handler.ts

@@ -0,0 +1,46 @@
+import { HttpError } from "http-errors";
+import { getReasonPhrase } from "http-status-codes";
+import { ErrorSerializer, JapiError } from "ts-japi";
+
+import type { ErrorHandler } from "./types";
+import { addStatusCodeToResponse, sendJson, setErrorHeaders } from "./utils";
+
+const defaultTitle = "An error occurred";
+
+const jsonapiErrorHandler: ErrorHandler = (error: HttpError | JapiError | Error, _request, response) => {
+    addStatusCodeToResponse(response, error);
+
+    setErrorHeaders(response, error);
+
+    if (error instanceof JapiError || JapiError.isLikeJapiError(error)) {
+        const serializer = new ErrorSerializer();
+
+        sendJson(response, serializer.serialize(error));
+    } else if (error instanceof HttpError) {
+        const { statusCode, title, message } = error;
+
+        sendJson(response, {
+            errors: [
+                {
+                    code: statusCode,
+                    title: title || getReasonPhrase(statusCode) || defaultTitle,
+                    detail: message,
+                },
+            ],
+        });
+    } else {
+        const { message } = error;
+
+        sendJson(response, {
+            errors: [
+                {
+                    code: "500",
+                    title: getReasonPhrase(response.statusCode) || defaultTitle,
+                    detail: message,
+                },
+            ],
+        });
+    }
+};
+
+export default jsonapiErrorHandler;

package/src/error-handler/problem-error-handler.ts

@@ -0,0 +1,44 @@
+import { HttpError } from "http-errors";
+import { getReasonPhrase } from "http-status-codes";
+
+import type { ErrorHandler } from "./types";
+import { addStatusCodeToResponse, sendJson, setErrorHeaders } from "./utils";
+
+const defaultType = "https://tools.ietf.org/html/rfc2616#section-10";
+const defaultTitle = "An error occurred";
+/**
+ * Normalizes errors according to the API Problem spec (RFC 7807).
+ *
+ * @see https://tools.ietf.org/html/rfc7807
+ */
+const problemErrorHandler: ErrorHandler = (error: HttpError | Error, _request, response) => {
+    const { stack, message } = error;
+
+    if (error instanceof HttpError) {
+        const {
+            statusCode, expose, title, type,
+        } = error;
+
+        response.statusCode = statusCode;
+
+        setErrorHeaders(response, error);
+
+        sendJson(response, {
+            type: type || defaultType,
+            title: title || getReasonPhrase(statusCode) || defaultTitle,
+            details: message,
+            ...(expose ? { trace: stack } : {}),
+        });
+    } else {
+        addStatusCodeToResponse(response, error);
+
+        sendJson(response, {
+            type: defaultType,
+            title: getReasonPhrase(response.statusCode) || defaultTitle,
+            details: message,
+            ...((error as { expose: boolean } & Error).expose ? { trace: stack } : {}),
+        });
+    }
+};
+
+export default problemErrorHandler;

package/src/error-handler/types.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export type ErrorHandler = <Request extends IncomingMessage, Response extends ServerResponse>(
+    error: any,
+    request: Request,
+    response: Response,
+) => any | Promise<any>;
+
+export type ErrorHandlers = {
+    regex: RegExp;
+    handler: ErrorHandler;
+}[];
+
+export type ApiFormat = "jsonapi" | "problem";

package/src/error-handler/utils.ts

@@ -0,0 +1,39 @@
+import { StatusCodes } from "http-status-codes";
+import type { ServerResponse } from "node:http";
+
+export const setErrorHeaders = (response: ServerResponse, error: any) => {
+    const headers: { [key: string]: number | string | ReadonlyArray<string> } = error.headers || {};
+
+    Object.keys(headers).forEach((header: string) => {
+        response.setHeader(header, headers[header] as number | string | ReadonlyArray<string>);
+    });
+};
+
+/**
+ * Send `JSON` object
+ * @param response response object
+ * @param jsonBody of data
+ */
+export const sendJson = (response: ServerResponse, jsonBody: any): void => {
+    // Set header to application/json
+    response.setHeader("content-type", "application/json; charset=utf-8");
+
+    response.end(JSON.stringify(jsonBody));
+};
+
+export const addStatusCodeToResponse = (response: ServerResponse, error: any): void => {
+    // respect err.statusCode
+    if (typeof error.statusCode !== "undefined") {
+        response.statusCode = error.statusCode;
+    }
+
+    // respect err.status
+    if (typeof error.status !== "undefined") {
+        response.statusCode = error.status;
+    }
+
+    // default status code to 500
+    if (response.statusCode < 400) {
+        response.statusCode = StatusCodes.INTERNAL_SERVER_ERROR;
+    }
+};

package/src/index-browser.tsx

@@ -0,0 +1 @@
+export * as zod from "./zod";

package/src/index-server.ts

@@ -0,0 +1,75 @@
+export * from "./index-browser";
+
+export {
+    default as createHttpError,
+    BadRequest,
+    Forbidden,
+    BadGateway,
+    BandwidthLimitExceeded,
+    Conflict,
+    ExpectationFailed,
+    FailedDependency,
+    GatewayTimeout,
+    Gone,
+    HTTPVersionNotSupported,
+    ImATeapot,
+    InsufficientStorage,
+    InternalServerError,
+    VariantAlsoNegotiates,
+    ProxyAuthenticationRequired,
+    NetworkAuthenticationRequire,
+    LengthRequired,
+    LoopDetected,
+    Locked,
+    MethodNotAllowed,
+    MisdirectedRequest,
+    NotAcceptable,
+    NotExtended,
+    NotFound,
+    NotImplemented,
+    PayloadTooLarge,
+    RequestHeaderFieldsTooLarge,
+    PaymentRequired,
+    PreconditionFailed,
+    PreconditionRequired,
+    RangeNotSatisfiable,
+    RequestTimeout,
+    ServiceUnavailable,
+    TooManyRequests,
+    Unauthorized,
+    UnorderedCollection,
+    UnprocessableEntity,
+    UnavailableForLegalReasons,
+    UnsupportedMediaType,
+    UpgradeRequired,
+    URITooLong,
+} from "http-errors";
+
+export { default as createNodeRouter } from "./connect/create-node-router";
+export { onError, onNoMatch } from "./connect/handler";
+export type {
+    EdgeRequestHandler,
+    ExpressRequestHandler,
+    NodeRequestHandler,
+    Route,
+    HandlerOptions,
+    NextHandler,
+    FunctionLike,
+    Nextable,
+    ValueOrPromise,
+    FindResult,
+    RouteShortcutMethod,
+    HttpMethod,
+} from "@visulima/connect";
+export {
+    createEdgeRouter, EdgeRouter, expressWrapper, NodeRouter, Router, withZod, sendJson,
+} from "@visulima/connect";
+
+export { default as rateLimiterMiddleware } from "./connect/middleware/rate-limiter-middleware";
+export { default as corsMiddleware } from "./connect/middleware/cors-middleware";
+export { default as serializersMiddleware } from "./connect/middleware/serializers-middleware";
+export { default as httpHeaderNormalizerMiddleware } from "./connect/middleware/http-header-normalizer";
+
+export { default as swaggerHandler } from "./swagger/swagger-handler";
+
+export { dateIn, dateOut } from "./zod";

package/src/next/cli/index.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line import/prefer-default-export
+export { default as listCommand } from "./list/list-command";

package/src/next/cli/list/api-route-file-parser.ts

@@ -0,0 +1,74 @@
+import type { OpenApiObject } from "@visulima/jsdoc-open-api";
+import { jsDocumentCommentsToOpenApi, parseFile, swaggerJsDocumentCommentsToOpenApi } from "@visulima/jsdoc-open-api";
+import fs from "node:fs";
+import process from "node:process";
+
+import type { Route } from "./types";
+
+const extensionRegex = /\.(js|ts|mjs|cjs)$/;
+
+const apiRouteFileParser = (apiRouteFile: string, cwdPath: string, verbose: boolean = false): Route[] => {
+    let specs: OpenApiObject[] = [];
+
+    const parsedJsDocumentFile = parseFile(apiRouteFile, jsDocumentCommentsToOpenApi, verbose);
+
+    specs = [...specs, ...parsedJsDocumentFile.map((item) => item.spec)];
+
+    const parsedSwaggerJsDocumentFile = parseFile(apiRouteFile, swaggerJsDocumentCommentsToOpenApi, verbose);
+
+    specs = [...specs, ...parsedSwaggerJsDocumentFile.map((item) => item.spec)];
+
+    const routes: Route[] = [];
+
+    if (specs.length === 0) {
+        const apiRouteFileContent = fs.readFileSync(apiRouteFile, "utf8");
+
+        apiRouteFileContent.split(/\r?\n/).forEach((line) => {
+            const match = line.match(/[=aces|]+\s["'|](GET|POST|PUT|PATCH|HEAD|DELETE|OPTIONS)["'|]/);
+
+            if (match) {
+                let [, method] = match;
+
+                if (method === "GET") {
+                    method = "GET|HEAD";
+                }
+
+                routes.push({
+                    method: method as string,
+                    path: apiRouteFile.replace(cwdPath, "").replace(extensionRegex, ""),
+                    tags: [],
+                    file: apiRouteFile.replace(`${process.cwd()}/`, ""),
+                });
+            }
+        });
+
+        if (routes.length === 0) {
+            routes.push({
+                method: "GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS",
+                path: apiRouteFile.replace(cwdPath, "").replace(extensionRegex, ""),
+                tags: [],
+                file: apiRouteFile.replace(`${process.cwd()}/`, ""),
+            });
+        }
+
+        return routes;
+    }
+
+    specs.forEach((spec) => {
+        const paths = Object.entries(spec.paths);
+
+        paths.forEach(([path, pathSpec]) => {
+            const methods = Object.entries(pathSpec);
+
+            methods.forEach(([method, methodSpec]) => {
+                routes.push({
+                    path, method: method.toUpperCase(), tags: methodSpec.tags, file: apiRouteFile.replace(`${process.cwd()}/`, ""),
+                });
+            });
+        });
+    });
+
+    return routes;
+};
+
+export default apiRouteFileParser;

package/src/next/cli/list/collect-api-route-files.ts

@@ -0,0 +1,42 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { collect } from "@visulima/readdir";
+import fs from "node:fs";
+import { join } from "node:path";
+
+const isDirectory = (path: string): boolean => {
+    try {
+        return fs.statSync(path).isDirectory();
+    } catch {
+        return false;
+    }
+};
+
+const collectApiRouteFiles = async (path: string = "", verbose: boolean = false): Promise<string[]> => {
+    let apiFolderPath = join(path, "pages/api");
+
+    // src/pages will be ignored if pages is present in the root directory
+    if (!isDirectory(apiFolderPath)) {
+        apiFolderPath = join(path, "src/pages/api");
+
+        if (!isDirectory(apiFolderPath)) {
+            return [];
+        }
+    }
+
+    return collect(apiFolderPath, {
+        extensions: [".js", ".cjs", ".mjs", ".ts"],
+        includeDirs: false,
+        minimatchOptions: {
+            match: {
+                debug: verbose,
+                matchBase: true,
+            },
+            skip: {
+                debug: verbose,
+                matchBase: true,
+            },
+        },
+    });
+};
+
+export default collectApiRouteFiles;

package/src/next/cli/list/list-command.ts

@@ -0,0 +1,105 @@
+import colors from "chalk";
+import { join } from "node:path";
+import process from "node:process";
+
+import apiRouteFileParser from "./api-route-file-parser";
+import collectApiRouteFiles from "./collect-api-route-files";
+import routesRender from "./routes-render";
+import type { Route } from "./types";
+
+type RenderOptions = {
+    includePaths: string[];
+    excludePaths: string[];
+    methods: string[];
+    group: string;
+};
+
+const groupBy = (list: Route[], keyGetter: (item: Route) => keyof Route): Map<string, Route[]> => {
+    const map = new Map();
+
+    list.forEach((item) => {
+        const key = keyGetter(item);
+        const collection = map.get(key);
+
+        if (!collection) {
+            map.set(key, [item]);
+        } else {
+            collection.push(item);
+        }
+    });
+
+    return map;
+};
+
+const listCommand = async (
+    path: string = "",
+    options: Partial<
+    {
+        verbose: boolean;
+    } & RenderOptions
+    > = {},
+// eslint-disable-next-line radar/cognitive-complexity
+) => {
+    const routePath = join(process.cwd(), path);
+
+    const apiRouteFiles = await collectApiRouteFiles(routePath, options.verbose || false);
+
+    if (apiRouteFiles.length === 0) {
+        // eslint-disable-next-line no-console
+        console.error(`No API routes found, in "${routePath}".`);
+        // eslint-disable-next-line unicorn/no-process-exit
+        process.exit(1);
+    }
+
+    let parsedApiRoutes = apiRouteFiles.flatMap((apiRouteFile) => apiRouteFileParser(apiRouteFile, routePath, options.verbose || false));
+
+    if (options.includePaths) {
+        parsedApiRoutes = options.includePaths.flatMap((ipath) => parsedApiRoutes.filter((route) => route.path.startsWith(ipath)));
+    }
+
+    if (options.excludePaths) {
+        parsedApiRoutes = options.excludePaths.flatMap((epath) => parsedApiRoutes.filter((route) => !route.path.startsWith(epath)));
+    }
+
+    if (typeof options.group !== "undefined") {
+        const groupedMap = groupBy(parsedApiRoutes, (route) => {
+            if (options.group === "path") {
+                return route.path.replace("/pages", "").split("/")[1];
+            }
+
+            return route.tags[0] || "unsorted";
+        });
+
+        let counter = 0;
+
+        groupedMap.forEach((routes, key) => {
+            if (counter > 0) {
+                // eslint-disable-next-line no-console
+                console.log();
+            }
+
+            const dotsCount = (process.stdout.columns - 16 - key.length) / 2;
+            const dots = dotsCount > 0 ? Array.from({ length: dotsCount }).fill(" ").join("") : "";
+            // eslint-disable-next-line no-console
+            console.log(dots + colors.bold.underline(key));
+
+            routesRender(routes, options).forEach((renderedRoute) => {
+                // eslint-disable-next-line no-console
+                console.log(renderedRoute);
+            });
+
+            counter += 1;
+        });
+    } else {
+        routesRender([], options).forEach((renderedRoute) => {
+            // eslint-disable-next-line no-console
+            console.log(renderedRoute);
+        });
+    }
+    // });
+
+    // eslint-disable-next-line no-console
+    console.log(`\n  Listed ${colors.greenBright(String(apiRouteFiles.length))} HTTP ${apiRouteFiles.length === 1 ? "route" : "routes"}.\n`);
+};
+
+export default listCommand;

package/src/next/cli/list/routes-render.ts

@@ -0,0 +1,62 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import colors from "chalk";
+
+import type { Route } from "./types";
+
+const renderRoute = (method: string, routePath: string): string => {
+    const colorMap = {
+        GET: colors.blue,
+        POST: colors.yellow,
+        PATCH: colors.yellow,
+        PUT: colors.yellow,
+        DELETE: colors.redBright,
+        OPTIONS: colors.hex("#6C7280"),
+        ANY: colors.redBright,
+        HEAD: colors.hex("#6C7280"),
+    };
+
+    let methodText: string;
+
+    if (method === "GET|HEAD") {
+        methodText = `${colors.blue("GET")}${colors.grey("|HEAD")}`;
+    } else {
+        const coloredMethod = colorMap[method as keyof typeof colorMap](method);
+
+        methodText = method === "GET" ? `${coloredMethod}${colors.grey("|HEAD")}` : coloredMethod;
+    }
+
+    const spacesCount = method === "GET" ? 6 : 14 - method.length;
+    const spaces = Array.from({ length: spacesCount }).fill(" ").join("");
+
+    const dotsCount = process.stdout.columns - 16 - routePath.length - 4;
+    const dots = dotsCount > 0 ? Array.from({ length: dotsCount }).fill(".").join("") : "";
+
+    const routeText = routePath
+        .split("/")
+        .map((segment) => {
+            const isDynamicSegment = ["[", ":"].includes(segment[0] || "");
+
+            return isDynamicSegment ? colors.yellowBright(segment) : segment;
+        })
+        .join("/");
+
+    return `  ${methodText}${spaces}${routeText}${colors.grey(dots)}`;
+};
+
+const routesRender = (routesMap: Route[], options: { methods?: string[]; } = {}) => routesMap
+    .map((route) => {
+        if (options.methods && options.methods.includes(route.method)) {
+            return;
+        }
+
+        if (route.method === "GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS") {
+            // eslint-disable-next-line no-param-reassign
+            route.method = "ANY";
+        }
+
+        // eslint-disable-next-line consistent-return
+        return renderRoute(route.method, route.path.replace("/pages", ""));
+    })
+    .filter(Boolean);
+
+export default routesRender;

package/src/next/cli/list/types.d.ts

@@ -0,0 +1 @@
+export type Route = { path: string; method: string; tags: any; file: string };

package/src/next/index-browser.tsx

@@ -0,0 +1,3 @@
+export { default as RedocPage } from "./routes/pages/swagger/redoc";
+export { default as SwaggerPage } from "./routes/pages/swagger/swagger";
+export { default as getSwaggerStaticProps } from "./routes/pages/swagger/get-static-properties-swagger";

package/src/next/index-server.ts

@@ -0,0 +1,6 @@
+export * from "./index-browser";
+
+// eslint-disable-next-line import/prefer-default-export
+export { default as withOpenApi } from "./webpack/with-open-api";
+
+export { default as swaggerApiRoute } from "./routes/api/swagger";