@visulima/crud 1.0.0

package/src/swagger/parameters.ts

@@ -0,0 +1,83 @@
+import { RouteType } from "../types.d";
+import type { SwaggerParameter } from "./types.d";
+
+const queryParameters: Record<string, SwaggerParameter> = {
+    select: {
+        name: "select",
+        description: "Fields to select. For nested fields, chain them separated with a dot, eg: user.posts",
+        schema: {
+            type: "string",
+        },
+    },
+    include: {
+        name: "include",
+        description: "Include relations, same as select",
+        schema: {
+            type: "string",
+        },
+    },
+    where: {
+        name: "where",
+        description: 'Fields to filter. See <a href="https://next-crud.js.org/query-params#where">the docs</a>',
+        schema: {
+            type: "string",
+        },
+    },
+    orderBy: {
+        name: "orderBy",
+        description: 'Field on which to order by a direction. See <a href="https://next-crud.js.org/query-params#orderBy">the docs</a>',
+        schema: {
+            type: "string",
+        },
+    },
+    limit: {
+        name: "limit",
+        description: "Maximum number of elements to retrieve",
+        schema: {
+            type: "integer",
+            minimum: 0,
+        },
+    },
+    skip: {
+        name: "skip",
+        description: "Number of rows to skip",
+        schema: {
+            type: "integer",
+            minimum: 0,
+        },
+    },
+    distinct: {
+        name: "distinct",
+        description: "Fields to distinctively retrieve",
+        schema: {
+            type: "string",
+        },
+    },
+    page: {
+        name: "page",
+        description: "Page number. Use only for pagination.",
+        schema: {
+            type: "integer",
+            minimum: 1,
+        },
+    },
+};
+
+export const commonQueryParameters = [queryParameters.select, queryParameters.include];
+export const listQueryParameters = [
+    ...commonQueryParameters,
+    queryParameters.limit,
+    queryParameters.skip,
+    queryParameters.where,
+    queryParameters.orderBy,
+    queryParameters.page,
+    queryParameters.distinct,
+];
+
+export const getQueryParameters = (routeType: RouteType, additionalQueryParameters: SwaggerParameter[] = []) => {
+    if (routeType === RouteType.READ_ALL) {
+        return [...listQueryParameters, ...additionalQueryParameters];
+    }
+
+    return [...commonQueryParameters, ...additionalQueryParameters];
+};

package/src/swagger/types.d.ts

@@ -0,0 +1,53 @@
+import { RouteType } from "../types.d";
+
+export type SwaggerType = {
+    name: string;
+    isArray?: boolean;
+    description?: string;
+    required?: boolean;
+};
+
+export type SwaggerOperation = {
+    summary?: string;
+    responses?: Record<number, any>;
+    body?: SwaggerType;
+    response: SwaggerType;
+};
+
+export type SwaggerTag = {
+    name?: string;
+    description?: string;
+    externalDocs?: {
+        description: string;
+        url: string;
+    };
+};
+
+export type SwaggerParameter = {
+    name: string;
+    description?: string;
+    schema: {
+        type: string;
+    } & any;
+};
+
+export type ModelsConfig = {
+    tag: SwaggerTag;
+    type?: SwaggerType;
+    routeTypes?: {
+        [RouteType.READ_ALL]?: SwaggerOperation;
+        [RouteType.READ_ONE]?: SwaggerOperation;
+        [RouteType.CREATE]?: SwaggerOperation;
+        [RouteType.UPDATE]?: SwaggerOperation;
+        [RouteType.DELETE]?: SwaggerOperation;
+    };
+    additionalQueryParams?: SwaggerParameter[];
+};
+
+export type SwaggerModelsConfig<M extends string> = {
+    [key in M]?: ModelsConfig;
+};
+
+export type Routes<M extends string> = {
+    [key in M]?: RouteType[];
+};

package/src/swagger/utils/format-example-ref.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line unicorn/prevent-abbreviations
+const formatExampleReference = (schemaName: string) => `#/components/examples/${schemaName}`;
+
+export default formatExampleReference;

package/src/swagger/utils/format-schema-ref.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line unicorn/prevent-abbreviations
+const formatSchemaReference = (schemaName: string) => `#/components/schemas/${schemaName}`;
+
+export default formatSchemaReference;

package/src/swagger/utils/get-models-accessible-routes.ts

@@ -0,0 +1,23 @@
+import type { ModelOption, ModelsOptions } from "../../types.d";
+import getAccessibleRoutes from "../../utils/get-accessible-routes";
+import type { Routes } from "../types.d";
+
+const getModelsAccessibleRoutes = <M extends string>(
+    modelNames: M[],
+    models?: ModelsOptions<M>,
+    defaultExposeStrategy: "all" | "none" = "all",
+): Routes<M> => modelNames.reduce((accumulator, modelName) => {
+        if (models?.[modelName]) {
+            return {
+                ...accumulator,
+                [modelName]: getAccessibleRoutes((models[modelName] as ModelOption).only, (models[modelName] as ModelOption).exclude, defaultExposeStrategy),
+            };
+        }
+
+        return {
+            ...accumulator,
+            [modelName]: getAccessibleRoutes(undefined, undefined, defaultExposeStrategy),
+        };
+    }, {});
+
+export default getModelsAccessibleRoutes;

package/src/swagger/utils/get-swagger-paths.ts

@@ -0,0 +1,244 @@
+import type { ModelOption, ModelsOptions } from "../../types.d";
+import { RouteType } from "../../types.d";
+import { getQueryParameters } from "../parameters";
+import type { Routes, SwaggerModelsConfig } from "../types.d";
+import formatExampleReference from "./format-example-ref";
+import formatSchemaReference from "./format-schema-ref";
+
+interface GenerateSwaggerPathObjectParameters<M extends string> {
+    tag: string;
+    routeTypes: RouteType[];
+    modelsConfig?: SwaggerModelsConfig<M>;
+    modelName: M;
+    hasId?: boolean;
+}
+
+type HttpMethod = "get" | "post" | "put" | "delete";
+
+const generateContentForSchema = (schemaName: string, isArray?: boolean) => {
+    if (isArray) {
+        return {
+            type: "array",
+            items: {
+                $ref: formatSchemaReference(schemaName),
+            },
+        };
+    }
+
+    return {
+        $ref: formatSchemaReference(schemaName),
+    };
+};
+
+const generateSwaggerResponse = (routeType: RouteType, modelName: string): { statusCode: number; content: any } | undefined => {
+    if (routeType === RouteType.CREATE) {
+        return {
+            statusCode: 201,
+            content: {
+                description: `${modelName} created`,
+                content: {
+                    "application/json": {
+                        schema: generateContentForSchema(modelName),
+                    },
+                },
+            },
+        };
+    }
+
+    if (routeType === RouteType.DELETE) {
+        return {
+            statusCode: 200,
+            content: {
+                description: `${modelName} item deleted`,
+                content: {
+                    "application/json": {
+                        schema: generateContentForSchema(modelName),
+                    },
+                },
+            },
+        };
+    }
+
+    if (routeType === RouteType.READ_ALL) {
+        return {
+            statusCode: 200,
+            content: {
+                description: `${modelName} list retrieved`,
+                content: {
+                    "application/json": {
+                        schema: {
+                            oneOf: [generateContentForSchema(modelName, true), generateContentForSchema(`${modelName}Page`, false)],
+                        },
+                        examples: {
+                            Default: {
+                                $ref: formatExampleReference(`${modelName}`),
+                            },
+                            Pagination: {
+                                $ref: formatExampleReference(`${modelName}Page`),
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    }
+
+    if (routeType === RouteType.READ_ONE) {
+        return {
+            statusCode: 200,
+            content: {
+                description: `${modelName} item retrieved`,
+                content: {
+                    "application/json": {
+                        schema: generateContentForSchema(modelName),
+                    },
+                },
+            },
+        };
+    }
+
+    if (routeType === RouteType.UPDATE) {
+        return {
+            statusCode: 200,
+            content: {
+                description: `${modelName} item updated`,
+                content: {
+                    "application/json": {
+                        schema: generateContentForSchema(modelName),
+                    },
+                },
+            },
+        };
+    }
+
+    return undefined;
+};
+
+const generateRequestBody = (schemaStartName: string, modelName: string) => {
+    return {
+        content: {
+            "application/json": {
+                schema: {
+                    $ref: formatSchemaReference(`${schemaStartName}${modelName}`),
+                },
+            },
+        },
+    };
+};
+
+const getRouteTypeMethod = (routeType: RouteType): HttpMethod => {
+    switch (routeType) {
+        case RouteType.CREATE: {
+            return "post";
+        }
+        case RouteType.READ_ALL:
+        case RouteType.READ_ONE: {
+            return "get";
+        }
+        case RouteType.UPDATE: {
+            return "put";
+        }
+        case RouteType.DELETE: {
+            return "delete";
+        }
+        default: {
+            throw new TypeError(`Method for route type ${routeType} was not found.`);
+        }
+    }
+};
+
+const generateSwaggerPathObject = <M extends string>({
+    tag, routeTypes, modelName, modelsConfig, hasId,
+}: GenerateSwaggerPathObjectParameters<M>) => {
+    const methods: { [key: string]: any } = {};
+
+    routeTypes.forEach((routeType) => {
+        if (routeTypes.includes(routeType)) {
+            const returnType = modelsConfig?.[modelName]?.routeTypes?.[routeType]?.response?.name ?? modelsConfig?.[modelName]?.type?.name ?? modelName;
+            const method: HttpMethod = getRouteTypeMethod(routeType);
+            const response = generateSwaggerResponse(routeType, returnType);
+
+            if (typeof response === "undefined") {
+                throw new TypeError(`Route type ${routeType}; response config was not found.`);
+            }
+
+            methods[method as HttpMethod] = {
+                tags: [tag],
+                summary: modelsConfig?.[modelName]?.routeTypes?.[routeType]?.summary,
+                parameters: getQueryParameters(routeType).map((queryParameter) => {
+                    return { ...queryParameter, in: "query" };
+                }),
+                responses: {
+                    [response.statusCode]: response.content,
+                    ...modelsConfig?.[modelName]?.routeTypes?.[routeType]?.responses,
+                },
+            };
+
+            if (hasId) {
+                methods[method as HttpMethod].parameters.push({
+                    in: "path",
+                    name: "id",
+                    description: `ID of the ${modelName}`,
+                    required: true,
+                    schema: {
+                        type: "string",
+                    },
+                });
+            }
+
+            if (routeType === RouteType.UPDATE || routeType === RouteType.CREATE) {
+                if (routeType === RouteType.UPDATE) {
+                    methods[method as HttpMethod].requestBody = generateRequestBody("Update", returnType);
+                } else if (routeType === RouteType.CREATE) {
+                    methods[method as HttpMethod].requestBody = generateRequestBody("Create", returnType);
+                }
+            }
+        }
+    });
+
+    return methods;
+};
+
+interface GetSwaggerPathsParameters<M extends string> {
+    routes: Routes<M>;
+    modelsConfig?: SwaggerModelsConfig<M>;
+    models?: ModelsOptions<M>;
+    routesMap?: { [key in M]?: string };
+}
+
+const getSwaggerPaths = <M extends string>({
+    routes, models, modelsConfig, routesMap,
+}: GetSwaggerPathsParameters<M>) => Object.keys(routes).reduce((accumulator: { [key: string]: any }, value: string | M) => {
+        const routeTypes = routes[value] as RouteType[];
+        const resourceName = models?.[value]?.name ? (models[value] as ModelOption).name : routesMap?.[value as M] || value;
+        const tag = modelsConfig?.[value]?.tag?.name || value;
+
+        if (routeTypes.includes(RouteType.CREATE) || routeTypes.includes(RouteType.READ_ALL)) {
+            const path = `/${resourceName}`;
+            const routeTypesToUse = [RouteType.READ_ALL, RouteType.CREATE].filter((routeType) => routeTypes.includes(routeType));
+
+            accumulator[path] = generateSwaggerPathObject({
+                tag,
+                modelName: value as M,
+                modelsConfig,
+                routeTypes: routeTypesToUse,
+            });
+        }
+
+        if (routeTypes.includes(RouteType.READ_ONE) || routeTypes.includes(RouteType.UPDATE) || routeTypes.includes(RouteType.DELETE)) {
+            const path = `/${resourceName}/{id}`;
+            const routeTypesToUse = [RouteType.READ_ONE, RouteType.UPDATE, RouteType.DELETE].filter((routeType) => routeTypes.includes(routeType));
+
+            accumulator[path] = generateSwaggerPathObject({
+                tag,
+                modelName: value as M,
+                modelsConfig,
+                routeTypes: routeTypesToUse,
+                hasId: true,
+            });
+        }
+
+        return accumulator;
+    }, {});
+
+export default getSwaggerPaths;

package/src/swagger/utils/get-swagger-tags.ts

@@ -0,0 +1,13 @@
+import type { ModelsConfig, SwaggerModelsConfig, SwaggerTag } from "../types.d";
+
+const getSwaggerTags = <M extends string>(modelNames: M[], modelsConfig?: SwaggerModelsConfig<M>): SwaggerTag[] => modelNames.map((modelName) => {
+    if (modelsConfig?.[modelName]?.tag) {
+        return (modelsConfig[modelName as M] as ModelsConfig).tag;
+    }
+
+    return {
+        name: modelName,
+    };
+});
+
+export default getSwaggerTags;

package/src/types.d.ts

@@ -0,0 +1,124 @@
+import type { Handler as CreateHandler } from "./handler/create";
+import type { Handler as DeleteHandler } from "./handler/delete";
+import type { Handler as ListHandler } from "./handler/list";
+import type { Handler as GetHandler } from "./handler/read";
+import type { Handler as UpdateHandler } from "./handler/update";
+
+export enum RouteType {
+    CREATE = "CREATE",
+    READ_ALL = "READ_ALL",
+    READ_ONE = "READ_ONE",
+    UPDATE = "UPDATE",
+    DELETE = "DELETE",
+}
+
+export type ModelOption = {
+    name?: string
+    only?: RouteType[]
+    exclude?: RouteType[]
+    formatResourceId?: (resourceId: string) => string | number
+};
+
+export type ModelsOptions<M extends string = string> = {
+    [key in M]?: ModelOption
+};
+
+export type HandlerOptions<M extends string = string> = {
+    formatResourceId?: (resourceId: string) => string | number;
+    models?: ModelsOptions<M>;
+    exposeStrategy?: "all" | "none";
+    pagination?: PaginationConfig,
+    handlers?: {
+        create?: CreateHandler;
+        delete?: DeleteHandler;
+        get?: GetHandler;
+        list?: ListHandler;
+        update?: UpdateHandler;
+    },
+};
+
+export type PaginationConfig = {
+    perPage: number
+};
+
+export interface HandlerParameters<T, Q> {
+    adapter: Adapter<T, Q>;
+    query: Q;
+    resourceName: string;
+}
+
+export interface UniqueResourceHandlerParameters<T, Q> {
+    adapter: Adapter<T, Q>;
+    query: Q;
+    resourceName: string;
+    resourceId: string | number;
+}
+
+export interface Adapter<T, Q, M extends string = string> {
+    models?: M[];
+    init?: () => Promise<void>;
+    parseQuery(resourceName: M, query: ParsedQueryParameters): Q;
+    getAll(resourceName: M, query: Q): Promise<T[]>;
+    getOne(resourceName: M, resourceId: string | number, query: Q): Promise<T>;
+    create(resourceName: M, data: any, query: Q): Promise<T>;
+    update(resourceName: M, resourceId: string | number, data: any, query: Q): Promise<T>;
+    delete(resourceName: M, resourceId: string | number, query: Q): Promise<T>;
+    getPaginationData(resourceName: M, query: Q): Promise<PaginationData>;
+    getModels(): M[];
+    connect?: () => Promise<void>;
+    disconnect?: () => Promise<void>;
+    handleError?: (error: Error) => void;
+    mapModelsToRouteNames?: () => Promise<{ [key in M]?: string }>;
+}
+
+export type PaginationData = {
+    total: number
+    pageCount: number
+    page: number
+};
+
+export type RecursiveField = {
+    [key: string]: boolean | TRecursiveField;
+};
+
+export type WhereOperator = "$eq" | "$neq" | "$in" | "$notin" | "$lt" | "$lte" | "$gt" | "$gte" | "$cont" | "$starts" | "$ends" | "$isnull";
+
+export type SearchCondition = string | boolean | number | Date | null;
+
+export type WhereCondition = {
+    [key in TWhereOperator]?: TSearchCondition;
+};
+
+export type Condition = {
+    [key: string]: TSearchCondition | TWhereCondition | TCondition;
+};
+
+export type WhereField = Condition & {
+    $and?: TCondition | TCondition[];
+    $or?: TCondition | TCondition[];
+    $not?: TCondition | TCondition[];
+};
+
+export type OrderByOperator = "$asc" | "$desc";
+
+export type OrderByField = {
+    [key: string]: TOrderByOperator;
+};
+
+export interface ParsedQueryParameters {
+    select?: RecursiveField;
+    include?: RecursiveField;
+    where?: WhereField;
+    orderBy?: OrderByField;
+    limit?: number;
+    skip?: number;
+    distinct?: string;
+    page?: number;
+    originalQuery?: {
+        [key: string]: any;
+    };
+}
+
+export interface ExecuteHandler<Request, Response> {
+    (request: Request, response: Response): Promise<void>;
+}

package/src/utils/format-resource-id.ts

@@ -0,0 +1,3 @@
+const formatResourceId = (resourceId: string): string | number => (Number.isSafeInteger(+resourceId) ? +resourceId : resourceId);
+
+export default formatResourceId;

package/src/utils/get-accessible-routes.ts

@@ -0,0 +1,18 @@
+import { RouteType } from "../types.d";
+
+const getAccessibleRoutes = (only?: RouteType[], exclude?: RouteType[], defaultExposeStrategy: "all" | "none" = "all"): RouteType[] => {
+    // eslint-disable-next-line max-len
+    let accessibleRoutes: RouteType[] = defaultExposeStrategy === "none" ? [] : [RouteType.READ_ALL, RouteType.READ_ONE, RouteType.UPDATE, RouteType.DELETE, RouteType.CREATE];
+
+    if (Array.isArray(only)) {
+        accessibleRoutes = only;
+    }
+
+    if (exclude?.length) {
+        accessibleRoutes = accessibleRoutes.filter((element) => !exclude.includes(element));
+    }
+
+    return accessibleRoutes;
+};
+
+export default getAccessibleRoutes;

package/src/utils/get-resource-name-from-url.ts

@@ -0,0 +1,23 @@
+export const ensureCamelCase = (string_: string) => `${string_.charAt(0).toLowerCase()}${string_.slice(1)}`;
+
+export const getResourceNameFromUrl = <M extends string = string>(url: string, models: { [key in M]?: string }) => {
+    // Exclude the query params from the path
+    const realPath = url.split("?")[0];
+
+    if (typeof realPath === "undefined") {
+        throw new TypeError("Path is undefined");
+    }
+
+    const modelName = (Object.keys(models) as M[]).find((name) => {
+        const routeName = models[name] as string;
+        const camelCaseModel = ensureCamelCase(routeName);
+
+        // eslint-disable-next-line @rushstack/security/no-unsafe-regexp
+        return new RegExp(`(${routeName}|${camelCaseModel}$)|(${routeName}|${camelCaseModel}/)`, "g").test(realPath);
+    });
+
+    return {
+        modelName,
+        resourceName: models[modelName] as string,
+    };
+};