@lucaapp/service-utils 1.31.0 → 1.32.0

package/dist/lib/api/api.d.ts

@@ -3,6 +3,7 @@ import 'express-async-errors';
 import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 import { EndpointHandler, EndpointOptions } from './types/endpoint';
 import { Middleware, EndpointResponseSchema } from './types/middleware';
+import { ZodObjectSchemaOrUndefined } from './types/utils';
 type OpenApiVersion = '3.0.0' | '3.0.1' | '3.0.2' | '3.0.3' | '3.1.0';
 type ApiConstructorOptions = {
     prefixPath?: string;
@@ -11,6 +12,13 @@ type ApiConstructorOptions = {
     apiTitle?: string;
     apiDescription?: string;
     debug?: boolean;
+    tags?: string[];
+    registry?: OpenAPIRegistry;
+    router?: Router;
+};
+type ApiChildOptions = {
+    prefixPath?: string;
+    tags?: string[];
 };
 export declare class Api {
     router: Router;
@@ -21,12 +29,14 @@ export declare class Api {
     apiDescription: string;
     private prefixPath;
     debug: boolean;
+    tags: string[];
     constructor(options?: ApiConstructorOptions);
-    get<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>): void;
-    post<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>): void;
-    patch<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>): void;
-    put<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>): void;
-    delete<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>): void;
+    child(options: ApiChildOptions): Api;
+    get<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined = undefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>): void;
+    post<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined = undefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>): void;
+    patch<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined = undefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>): void;
+    put<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined = undefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>): void;
+    delete<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined = undefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined = undefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined>(path: string, summary: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>): void;
     generateOpenAPISpec(): import("openapi3-ts").OpenAPIObject;
     mountSwaggerMiddlewares(): void;
 }

package/dist/lib/api/api.js

@@ -11,35 +11,44 @@ const zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
 const endpoint_1 = require("./endpoint");
 class Api {
     constructor(options = {}) {
-        this.router = (0, express_1.Router)();
-        this.registry = new zod_to_openapi_1.OpenAPIRegistry();
+        this.router = options.router || (0, express_1.Router)();
+        this.registry = options.registry || new zod_to_openapi_1.OpenAPIRegistry();
         this.prefixPath = options.prefixPath || '';
         this.openApiVersion = options.openApiVersion || '3.0.0';
         this.apiVersion = options.apiVersion || '1.0.0';
         this.apiTitle = options.apiTitle || 'API';
         this.apiDescription = options.apiDescription || '';
         this.debug = options.debug || false;
-        this.mountSwaggerMiddlewares();
+        this.tags = options.tags || [];
+    }
+    child(options) {
+        return new Api({
+            prefixPath: this.prefixPath + (options.prefixPath || ''),
+            debug: this.debug,
+            tags: [...this.tags, ...(options.tags || [])],
+            registry: this.registry,
+            router: this.router,
+        });
     }
     get(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'get', path, options, handler, this.debug);
-        (0, endpoint_1.registerEndpoint)(this.registry, 'get', this.prefixPath, path, summary, options, this.debug);
+        (0, endpoint_1.registerEndpoint)(this.registry, 'get', this.prefixPath, path, summary, options, this.tags, this.debug);
     }
     post(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'post', path, options, handler, this.debug);
-        (0, endpoint_1.registerEndpoint)(this.registry, 'post', this.prefixPath, path, summary, options, this.debug);
+        (0, endpoint_1.registerEndpoint)(this.registry, 'post', this.prefixPath, path, summary, options, this.tags, this.debug);
     }
     patch(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'patch', path, options, handler, this.debug);
-        (0, endpoint_1.registerEndpoint)(this.registry, 'patch', this.prefixPath, path, summary, options, this.debug);
+        (0, endpoint_1.registerEndpoint)(this.registry, 'patch', this.prefixPath, path, summary, options, this.tags, this.debug);
     }
     put(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'put', path, options, handler, this.debug);
-        (0, endpoint_1.registerEndpoint)(this.registry, 'put', this.prefixPath, path, summary, options, this.debug);
+        (0, endpoint_1.registerEndpoint)(this.registry, 'put', this.prefixPath, path, summary, options, this.tags, this.debug);
     }
     delete(path, summary, options, handler) {
         (0, endpoint_1.mountEndpoint)(this.router, 'delete', path, options, handler, this.debug);
-        (0, endpoint_1.registerEndpoint)(this.registry, 'delete', this.prefixPath, path, summary, options, this.debug);
+        (0, endpoint_1.registerEndpoint)(this.registry, 'delete', this.prefixPath, path, summary, options, this.tags, this.debug);
     }
     generateOpenAPISpec() {
         const generator = new zod_to_openapi_1.OpenAPIGenerator(this.registry.definitions, this.openApiVersion);

package/dist/lib/api/endpoint.d.ts

@@ -2,7 +2,8 @@ import { Router } from 'express';
 import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
 import { Middleware, EndpointResponseSchema } from './types/middleware';
 import { EndpointOptions, EndpointHandler } from './types/endpoint';
+import { ZodObjectSchemaOrUndefined } from './types/utils';
 type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
-export declare const mountEndpoint: <TResponseSchemas extends readonly EndpointResponseSchema[], TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends readonly Middleware<any, any, any, any, any, any>[] | undefined = undefined>(router: Router, method: HttpMethod, path: string, options: EndpointOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TMiddlewares>, debug: boolean) => void;
-export declare const registerEndpoint: (registry: OpenAPIRegistry, method: HttpMethod, prefixPath: string, path: string, summary: string, options: EndpointOptions<any, any, any, any, any, any>, debug: boolean) => void;
+export declare const mountEndpoint: <TResponseSchemas extends readonly EndpointResponseSchema[], TRequestBodySchema extends ZodObjectSchemaOrUndefined, TRequestParamsSchema extends ZodObjectSchemaOrUndefined, TRequestQuerySchema extends ZodObjectSchemaOrUndefined, TRequestHeadersSchema extends ZodObjectSchemaOrUndefined, TMiddlewares extends readonly Middleware<any, any, any, any, any, any>[] | undefined = undefined>(router: Router, method: HttpMethod, path: string, options: EndpointOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, handler: EndpointHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares>, debug: boolean) => void;
+export declare const registerEndpoint: (registry: OpenAPIRegistry, method: HttpMethod, prefixPath: string, path: string, summary: string, options: EndpointOptions<any, any, any, any, any, any>, tags: string[], debug: boolean) => void;
 export {};

package/dist/lib/api/endpoint.js

@@ -7,6 +7,7 @@ exports.registerEndpoint = exports.mountEndpoint = void 0;
 const zod_1 = require("zod");
 const assert_1 = __importDefault(require("assert"));
 const http_1 = require("./types/http");
+const mapExpressParamsToOpenAPIParams = (path) => path.replaceAll(/\:([^\:\/]+)/g, '{$1}');
 const buildResponseConfig = (responseOptions) => {
     const responses = {};
     responseOptions.forEach(response => {
@@ -213,7 +214,7 @@ const mountEndpoint = (router, method, path, options, handler, debug) => {
 exports.mountEndpoint = mountEndpoint;
 const registerEndpoint = (registry, method, prefixPath, path, summary, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-options, debug) => {
+options, tags, debug) => {
     let bodySchema = options.schemas?.body || undefined;
     let paramsSchema = options.schemas?.params || undefined;
     let querySchema = options.schemas?.query || undefined;
@@ -297,8 +298,9 @@ options, debug) => {
     const responseMap = buildResponseConfig(responseSchemas);
     registry.registerPath({
         method,
-        path: (prefixPath + path).replaceAll(/\:([^\:\/]+)/g, '{$1}'),
+        path: mapExpressParamsToOpenAPIParams(prefixPath + path),
         summary,
+        tags,
         // description: summary,
         request: {
             ...(bodySchema && {

package/dist/lib/api/types/endpoint.d.ts

@@ -1,18 +1,17 @@
-import { z } from 'zod';
 import { Middleware, EndpointResponseSchema } from './middleware';
-import { ArrayToUnion, ExtractZodOutput, ExtractZodOutputFromMiddleware, Always, Merge } from './utils';
-export type EndpointHandler<TResponse, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares = undefined> = (request: {
-    body: TRequestBody;
-    params: TRequestParams;
-    query: TRequestQuery;
-    headers: TRequestHeaders;
+import { ArrayToUnion, ExtractZodOutput, ExtractZodOutputFromMiddleware, Always, Merge, ZodSchemaOuput } from './utils';
+export type EndpointHandler<TResponse, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares> = (request: {
+    body: ZodSchemaOuput<TRequestBodySchema>;
+    params: ZodSchemaOuput<TRequestParamsSchema>;
+    query: ZodSchemaOuput<TRequestQuerySchema>;
+    headers: ZodSchemaOuput<TRequestHeadersSchema>;
 }, context: Merge<Always<ExtractZodOutputFromMiddleware<ArrayToUnion<TMiddlewares>>>>, send: (response: ExtractZodOutput<ArrayToUnion<TResponse>>) => void) => Promise<void>;
-export type EndpointOptions<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined = undefined> = {
+export type EndpointOptions<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TMiddlewares extends ReadonlyArray<Middleware<any, any, any, any, any, any>> | undefined> = {
     schemas?: {
-        body?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestBody>;
-        params?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestParams>;
-        query?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestQuery>;
-        headers?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestHeaders>;
+        body?: TRequestBodySchema;
+        params?: TRequestParamsSchema;
+        query?: TRequestQuerySchema;
+        headers?: TRequestHeadersSchema;
     };
     middlewares?: TMiddlewares;
     responses: TResponseSchemas;

package/dist/lib/api/types/middleware.d.ts

@@ -1,32 +1,32 @@
 import { z } from 'zod';
-import { ArrayToUnion, ExtractZodOutput } from './utils';
+import { ArrayToUnion, ExtractZodOutput, ZodSchemaOuput } from './utils';
 export type EndpointResponseSchema = {
     status: number;
     description: string;
     schema: z.ZodSchema<any> | z.ZodVoid;
 };
-export type MiddlewareHandler<TResponseSchema, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TContext = undefined> = (request: {
-    body: TRequestBody;
-    params: TRequestParams;
-    query: TRequestQuery;
-    headers: TRequestHeaders;
+export type MiddlewareHandler<TResponseSchema, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema> = (request: {
+    body: ZodSchemaOuput<TRequestBodySchema>;
+    params: ZodSchemaOuput<TRequestParamsSchema>;
+    query: ZodSchemaOuput<TRequestQuerySchema>;
+    headers: ZodSchemaOuput<TRequestHeadersSchema>;
     ip: string;
     baseUrl: string;
     path: string;
     method: string;
-}, send: (response: ExtractZodOutput<ArrayToUnion<TResponseSchema>>) => void, next: (context: TContext) => void) => Promise<void>;
-export type MiddlewareOptions<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TContext = undefined> = {
+}, send: (response: ExtractZodOutput<ArrayToUnion<TResponseSchema>>) => void, next: (context: ZodSchemaOuput<TContextSchema>) => void) => Promise<void>;
+export type MiddlewareOptions<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema> = {
     schemas?: {
-        body?: z.ZodSchema<TRequestBody>;
-        params?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestParams>;
-        query?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestQuery>;
-        headers?: z.ZodObject<z.ZodRawShape, 'strip', z.ZodTypeAny, TRequestHeaders>;
-        context?: z.ZodSchema<TContext>;
+        body?: TRequestBodySchema;
+        params?: TRequestParamsSchema;
+        query?: TRequestQuerySchema;
+        headers?: TRequestHeadersSchema;
+        context?: TContextSchema;
     };
     responses: TResponseSchemas;
     errors?: Record<string, number>;
 };
-export type Middleware<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBody = undefined, TRequestParams = undefined, TRequestQuery = undefined, TRequestHeaders = undefined, TContext = undefined> = {
-    options: MiddlewareOptions<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TContext>;
-    handler: MiddlewareHandler<TResponseSchemas, TRequestBody, TRequestParams, TRequestQuery, TRequestHeaders, TContext>;
+export type Middleware<TResponseSchemas extends ReadonlyArray<EndpointResponseSchema>, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema> = {
+    options: MiddlewareOptions<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema>;
+    handler: MiddlewareHandler<TResponseSchemas, TRequestBodySchema, TRequestParamsSchema, TRequestQuerySchema, TRequestHeadersSchema, TContextSchema>;
 };

package/dist/lib/api/types/utils.d.ts

@@ -7,6 +7,8 @@ export type ExtractZodOutput<T> = T extends {
     status: Z;
     body: V;
 } : never;
+export type ZodObjectSchemaOrUndefined = z.ZodObject<any> | undefined;
+export type ZodSchemaOuput<T> = T extends z.ZodSchema<any> ? z.infer<T> : undefined;
 export type ExtractZodOutputFromMiddleware<T> = T extends {
     options: {
         schemas?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [