express-zod-api 14.2.2 → 15.0.0-beta1

package/CHANGELOG.md

@@ -1,7 +1,67 @@
 # Changelog
 
+## Version 15
+
+### 15.0.0
+
+- **Breaking changes**:
+  - `express-fileupload` and `compression` become optional peer dependencies;
+  - Methods `createServer()` and `attachRouting()` become async;
+  - Method `testEndpoint()` requires an additional argument;
+  - Method `createLogger()` removed as redundant;
+  - Read the migration guide below.
+- Features:
+  - `winston` is now optional: supporting any logger having `debug()`, `warn()`, `info()` and `error()` methods;
+  - Introducing module augmentation approach for setting the type of chosen logger;
+  - Supporting both `jest` and `vitest` frameworks for `testEndpoint()`.
+- How to migrate while maintaining previous functionality and behavior:
+  - If you're going to continue using `winston`:
+    - Near your `const config = createConfig(...)` add the module augmentation statement (see example below).
+  - If you have `upload` option enabled in your config:
+    - Install `express-fileupload` and `@types/express-fileupload` packages;
+  - If you have `compression` option enabled in your config:
+    - Install `compression` and `@types/compression` packages;
+  - If you're using `createLogger()` method:
+    - Place its argument as a value of `logger` property supplied to `createConfig()`.
+  - If you're using the entities returned from `createServer()` or `attachRouting()` methods:
+    - Add `await` before calling them: `const {...} = await createServer(...)`.
+    - If you can not use `await` (on the top level of CommonJS):
+      - Wrap your code with async IIFE or use `.then()` (see example below).
+  - If you're using `testEndpoint()` method:
+    - Specify either `fnMethod: jest.fn` or `fnMethod: vi.fn` within its object argument.
+
+```typescript
+import type { Logger } from "winston";
+import { createConfig, createServer, testEndpoint } from "express-zod-api";
+
+// The configuration remains the same
+const config = createConfig({
+  logger: { level: "debug", color: true },
+});
+
+// Set the type of logger used near your configuration
+declare module "express-zod-api" {
+  interface LoggerOverrides extends Logger {}
+}
+
+// await is only needed when you're using the returns of createServer() or attachRouting()
+// For using await on the top level CJS, wrap it in async IIFE:
+// (async () => { await ... })();
+const { app, httpServer } = await createServer(config, routing);
+
+// Adjust your tests:
+const { responseMock } = await testEndpoint({
+  endpoint,
+  fnMethod: jest.fn, // or vi.fn from vitest, required
+});
+```
+
 ## Version 14
 
+### v14.2.3
+
+- `express-fileupload` version is 1.4.3.
+
 ### v14.2.2
 
 - Hotfix: exporting `AppConfig` and `ServerConfig` types to in order to prevent the issue #952.

package/README.md

@@ -64,7 +64,7 @@ You can find the release notes and migration guides in [Changelog](CHANGELOG.md)
 # Why and what is it for
 
 I made this library because of the often repetitive tasks of starting a web server APIs with the need to validate input
-data. It integrates and provides the capabilities of popular web server, logger, validation and documenting solutions.
+data. It integrates and provides the capabilities of popular web server, logging, validation and documenting solutions.
 Therefore, many basic tasks can be accomplished faster and easier, in particular:
 
 - You can describe web server routes as a hierarchical object.
@@ -85,7 +85,8 @@ Therefore, many basic tasks can be accomplished faster and easier, in particular
 - [Typescript](https://www.typescriptlang.org/) first.
 - Web server — [Express.js](https://expressjs.com/).
 - Schema validation — [Zod 3.x](https://github.com/colinhacks/zod).
-- Logger — [Winston](https://github.com/winstonjs/winston).
+- Logger — [Winston](https://github.com/winstonjs/winston) by default,
+  - Supports any logger having `info()`, `debug()`, `error()` and `warn()` methods.
 - Generators:
   - Documentation — [OpenAPI 3.x](https://github.com/metadevpro/openapi3-ts) (Swagger Specification).
   - Client side types — inspired by [zod-to-ts](https://github.com/sachinraja/zod-to-ts).
@@ -138,6 +139,7 @@ Create a minimal configuration. _See all available options
 [in sources](https://github.com/RobinTail/express-zod-api/blob/master/src/config-type.ts)._
 
 ```typescript
+import type { Logger } from "winston";
 import { createConfig } from "express-zod-api";
 
 const config = createConfig({
@@ -147,6 +149,11 @@ const config = createConfig({
   cors: true,
   logger: { level: "debug", color: true },
 });
+
+// Setting the type of logger used
+declare module "express-zod-api" {
+  interface LoggerOverrides extends Logger {}
+}
 ```
 
 ## Create an endpoints factory
@@ -483,7 +490,12 @@ const config = createConfig({
   // ... cors, logger, etc
 });
 
-const { app, httpServer, httpsServer, logger } = createServer(config, routing);
+// 'await' is only needed if you're going to use the returned entities.
+// For top level CJS you can wrap you code with (async () => { ... })()
+const { app, httpServer, httpsServer, logger } = await createServer(
+  config,
+  routing,
+);
 ```
 
 Ensure having `@types/node` package installed. At least you need to specify the port (usually it is 443) or UNIX socket,
@@ -492,44 +504,48 @@ your API at [Let's Encrypt](https://letsencrypt.org/).
 
 ## Customizing logger
 
-You can specify your custom Winston logger in config:
+You can uninstall `winston` (which is the default and recommended logger) and use another compatible one, having
+`info()`, `debug()`, `error()` and `warn()` methods. For example, `pino` logger with `pino-pretty` extension:
 
 ```typescript
-import winston from "winston";
+import pino, { Logger } from "pino";
 import { createConfig } from "express-zod-api";
 
-const logger = winston.createLogger({
-  /* ... */
+const logger = pino({
+  transport: {
+    target: "pino-pretty",
+    options: { colorize: true },
+  },
 });
-const config = createConfig({ logger /* ..., */ });
+const config = createConfig({ logger });
+
+// Setting the type of logger used
+declare module "express-zod-api" {
+  interface LoggerOverrides extends Logger {}
+}
 ```
 
 ## Enabling compression
 
 According to [Express.js best practices guide](http://expressjs.com/en/advanced/best-practice-performance.html)
-it might be a good idea to enable GZIP compression of your API responses. You can achieve and customize it by using the
-corresponding configuration option when using the `createServer()` method.
+it might be a good idea to enable GZIP compression of your API responses.
 
-In order to receive the compressed response the client should include the following header in the request:
-`Accept-Encoding: gzip, deflate`. Only responses with compressible content types are subject to compression. There is
-also a default threshold of 1KB that can be configured.
+Install the following additional packages: `compression` and `@types/compression`, and enable or configure compression:
 
 ```typescript
 import { createConfig } from "express-zod-api";
 
 const config = createConfig({
   server: {
-    // compression: true, or:
-    compression: {
-      // @see https://www.npmjs.com/package/compression#options
-      threshold: "100b",
-    },
-    // ... other options
+    /** @link https://www.npmjs.com/package/compression#options */
+    compression: { threshold: "1kb" }, // or true
   },
-  // ... other options
 });
 ```
 
+In order to receive a compressed response the client should include the following header in the request:
+`Accept-Encoding: gzip, deflate`. Only responses with compressible content types are subject to compression.
+
 # Advances features
 
 ## Customizing input sources
@@ -715,29 +731,34 @@ const fileStreamingEndpointsFactory = new EndpointsFactory(
 
 ## File uploads
 
-You can switch the `Endpoint` to handle requests with the `multipart/form-data` content type instead of JSON by using
-`ez.upload()` schema. Together with a corresponding configuration option, this makes it possible to handle file uploads.
-Here is a simplified example:
+Install the following additional packages: `express-fileupload` and `@types/express-fileupload`, and enable or
+configure file uploads:
 
 ```typescript
-import { z } from "zod";
-import { createConfig, ez, defaultEndpointsFactory } from "express-zod-api";
+import { createConfig } from "express-zod-api";
 
 const config = createConfig({
   server: {
-    upload: true, // <- required
-    // ...,
+    upload: true, // or options
   },
 });
+```
+
+Refer to [documentation](https://www.npmjs.com/package/express-fileupload#available-options) on available options.
+Then you can change the `Endpoint` to handle requests having the `multipart/form-data` content type instead of JSON by
+using `ez.upload()` schema. Together with a corresponding configuration option, this makes it possible to handle file
+uploads. Here is a simplified example:
+
+```typescript
+import { z } from "zod";
+import { ez, defaultEndpointsFactory } from "express-zod-api";
 
 const fileUploadEndpoint = defaultEndpointsFactory.build({
   method: "post",
   input: z.object({
     avatar: ez.upload(), // <--
   }),
-  output: z.object({
-    /* ... */
-  }),
+  output: z.object({}),
   handler: async ({ input: { avatar } }) => {
     // avatar: {name, mv(), mimetype, data, size, etc}
     // avatar.truncated is true on failure
@@ -782,12 +803,15 @@ const routing = {
   /* ... */
 };
 
-const { notFoundHandler, logger } = attachRouting(config, routing);
+// This async IIFE is only required for the top level CommonJS
+(async () => {
+  const { notFoundHandler, logger } = await attachRouting(config, routing);
 
-app.use(notFoundHandler); // optional
-app.listen();
+  app.use(notFoundHandler); // optional
+  app.listen();
 
-logger.info("Glory to science!");
+  logger.info("Glory to science!");
+})();
 ```
 
 **Please note** that in this case you probably need to parse `request.body`, call `app.listen()` and handle `404`
@@ -990,17 +1014,18 @@ const exampleEndpoint = taggedEndpointsFactory.build({
 
 The way to test endpoints is to mock the request, response, and logger objects, invoke the `execute()` method, and
 assert the expectations for calls of certain mocked methods. The library provides a special method that makes mocking
-easier, it requires `jest` (and optionally `@types/jest`) to be installed, so the test might look the following way:
+easier, it requires either `jest` (with `@types/jest`) or `vitest` to be installed, so the test might look this way:
 
 ```typescript
 import { testEndpoint } from "express-zod-api";
 
 test("should respond successfully", async () => {
   const { responseMock, loggerMock } = await testEndpoint({
+    fnMethod: jest.fn, // or vi.fn from vitest
     endpoint: yourEndpoint,
     requestProps: {
       method: "POST", // default: GET
-      body: { /* parsed JSON */ },
+      body: {}, // incoming data as if after parsing (JSON)
     },
     // responseProps, configProps, loggerProps
   });
@@ -1008,7 +1033,7 @@ test("should respond successfully", async () => {
   expect(responseMock.status).toHaveBeenCalledWith(200);
   expect(responseMock.json).toHaveBeenCalledWith({
     status: "success",
-    data: { ... },
+    data: {},
   });
 });
 ```

package/SECURITY.md

@@ -4,9 +4,10 @@
 
 | Version | Release |     Supported      |
 | ------: | :------ | :----------------: |
+|  15.x.x | 12.2023 | :white_check_mark: |
 |  14.x.x | 10.2023 | :white_check_mark: |
 |  12.x.x | 09.2023 | :white_check_mark: |
-|  11.x.x | 06.2023 | :white_check_mark: |
+|  11.x.x | 06.2023 |        :x:         |
 |  10.x.x | 03.2023 |        :x:         |
 |   9.x.x | 03.2023 |        :x:         |
 |   8.x.x | 09.2022 |        :x:         |
@@ -24,6 +25,6 @@
 Found a vulnerability or other security issue?
 
 Please urgently inform me privately by
-[email](https://github.com/RobinTail/express-zod-api/blob/master/package.json#L137).
+[email](https://github.com/RobinTail/express-zod-api/blob/master/package.json#L140).
 
 I will try to fix it as soon as possible.

package/dist/index.d.mts

@@ -2,7 +2,6 @@ import compression from 'compression';
 import express, { Request, Response, NextFunction, RequestHandler, Express } from 'express';
 import fileUpload, { UploadedFile } from 'express-fileupload';
 import https, { ServerOptions } from 'node:https';
-import winston, { Logger } from 'winston';
 import { z, ZodTypeDef, ZodType, ParseInput, ParseReturnType, ZodError } from 'zod';
 import { HttpError } from 'http-errors';
 import { ListenOptions } from 'node:net';
@@ -93,12 +92,26 @@ interface OAuth2Security<S extends string> {
  * */
 type Security<K extends string = string, S extends string = string> = BasicSecurity | BearerSecurity | InputSecurity<K> | CustomHeaderSecurity | CookieSecurity | OpenIdSecurity | OAuth2Security<S>;
 
+/**
+ * @desc Using module augmentation approach you can set the type of the actual logger used
+ * @example declare module "express-zod-api" { interface LoggerOverrides extends winston.Logger {} }
+ * @link https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
+ * */
+interface LoggerOverrides {
+}
+/** @desc You can use any logger compatible with this type. */
+type AbstractLogger = Record<"info" | "debug" | "warn" | "error", (message: string, meta?: any) => any> & LoggerOverrides;
+interface SimplifiedWinstonConfig {
+    level: "silent" | "warn" | "debug";
+    color: boolean;
+}
+
 interface MiddlewareParams<IN, OPT> {
     input: IN;
     options: OPT;
     request: Request;
     response: Response;
-    logger: Logger;
+    logger: AbstractLogger;
 }
 type Middleware<IN, OPT, OUT> = (params: MiddlewareParams<IN, OPT>) => Promise<OUT>;
 interface MiddlewareCreationProps<IN extends IOSchema<"strip">, OPT, OUT extends FlatObject, SCO extends string> {
@@ -261,6 +274,10 @@ declare class InputValidationError extends IOSchemaError {
     readonly originalError: ZodError;
     constructor(originalError: ZodError);
 }
+declare class MissingPeerError extends Error {
+    name: string;
+    constructor(module: string);
+}
 
 interface ResultHandlerParams<RES> {
     /** null in case of failure to parse or to find the matching endpoint (error: not found) */
@@ -270,7 +287,7 @@ interface ResultHandlerParams<RES> {
     error: Error | null;
     request: Request;
     response: Response<RES>;
-    logger: Logger;
+    logger: AbstractLogger;
 }
 type ResultHandler<RES> = (params: ResultHandlerParams<RES>) => void | Promise<void>;
 interface ResultHandlerDefinition<POS extends z.ZodTypeAny, NEG extends z.ZodTypeAny> {
@@ -407,7 +424,7 @@ declare const arrayResultHandler: ResultHandlerDefinition<z.ZodArray<z.ZodTypeAn
 type Handler<IN, OUT, OPT> = (params: {
     input: IN;
     options: OPT;
-    logger: Logger;
+    logger: AbstractLogger;
 }) => Promise<OUT>;
 type DescriptionVariant = "short" | "long";
 type IOVariant = "input" | "output";
@@ -417,7 +434,7 @@ declare abstract class AbstractEndpoint {
     abstract execute(params: {
         request: Request;
         response: Response;
-        logger: Logger;
+        logger: AbstractLogger;
         config: CommonConfig;
     }): Promise<void>;
     abstract getDescription(variant: DescriptionVariant): string | undefined;
@@ -467,15 +484,11 @@ declare class Endpoint<IN extends IOSchema, OUT extends IOSchema, OPT extends Fl
     execute({ request, response, logger, config, }: {
         request: Request;
         response: Response;
-        logger: Logger;
+        logger: AbstractLogger;
         config: CommonConfig;
     }): Promise<void>;
 }
 
-interface LoggerConfig {
-    level: "silent" | "warn" | "debug";
-    color: boolean;
-}
 type InputSource = keyof Pick<Request, "query" | "body" | "files" | "params" | "headers">;
 type InputSources = Record<Method, InputSource[]>;
 type Headers = Record<string, string>;
@@ -484,7 +497,7 @@ type HeadersProvider = (params: {
     defaultHeaders: Headers;
     request: Request;
     endpoint: AbstractEndpoint;
-    logger: Logger;
+    logger: AbstractLogger;
 }) => Headers | Promise<Headers>;
 type TagsConfig<TAG extends string> = Record<TAG, string | {
     description: string;
@@ -503,8 +516,11 @@ interface CommonConfig<TAG extends string = string> {
      * @see defaultResultHandler
      */
     errorHandler?: AnyResultHandlerDefinition;
-    /** @desc Logger configuration or your custom winston logger. */
-    logger: LoggerConfig | Logger;
+    /**
+     * @desc Logger configuration (winston) or instance of any other logger.
+     * @example { level: "debug", color: true }
+     * */
+    logger: SimplifiedWinstonConfig | AbstractLogger;
     /**
      * @desc You can disable the startup logo.
      * @default true
@@ -539,11 +555,13 @@ interface ServerConfig<TAG extends string = string> extends CommonConfig<TAG> {
         /**
          * @desc Enable or configure uploads handling.
          * @default false
+         * @requires express-fileupload
          * */
         upload?: boolean | UploadOptions;
         /**
          * @desc Enable or configure response compression.
          * @default false
+         * @requires compression
          */
         compression?: boolean | CompressionOptions;
         /**
@@ -594,11 +612,8 @@ declare class EndpointsFactory<POS extends z.ZodTypeAny, NEG extends z.ZodTypeAn
     #private;
     protected resultHandler: ResultHandlerDefinition<POS, NEG>;
     protected middlewares: AnyMiddlewareDef[];
+    /** @desc Consider using the "config" prop with the "tags" option to enforce constraints on tagging the endpoints */
     constructor(resultHandler: ResultHandlerDefinition<POS, NEG>);
-    /**
-     * @desc Consider using the "config" prop with the "tags" option to enforce constraints on tagging the endpoints
-     * @todo in next major release consider making config required for using in Endpoint::constructor
-     * */
     constructor(params: {
         resultHandler: ResultHandlerDefinition<POS, NEG>;
         config?: CommonConfig<TAG>;
@@ -733,8 +748,6 @@ declare const arrayEndpointsFactory: EndpointsFactory<z.ZodArray<z.ZodTypeAny, "
     example: (example: string) => z.ZodString & any;
 }, null, {}, string, string>;
 
-declare const createLogger: (loggerConfig: LoggerConfig) => winston.Logger;
-
 declare class DependsOnMethod {
     readonly endpoints: Partial<Record<Method, AbstractEndpoint>>;
     constructor(endpoints: Partial<Record<Method, AbstractEndpoint>>);
@@ -752,16 +765,16 @@ interface Routing {
     [SEGMENT: string]: Routing | DependsOnMethod | AbstractEndpoint | ServeStatic;
 }
 
-declare const attachRouting: (config: AppConfig, routing: Routing) => {
+declare const attachRouting: (config: AppConfig, routing: Routing) => Promise<{
     notFoundHandler: express.RequestHandler<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>;
-    logger: Logger;
-};
-declare const createServer: (config: ServerConfig, routing: Routing) => {
-    logger: Logger;
+    logger: AbstractLogger;
+}>;
+declare const createServer: (config: ServerConfig, routing: Routing) => Promise<{
+    logger: AbstractLogger;
     httpServer: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
     httpsServer: https.Server<typeof http.IncomingMessage, typeof http.ServerResponse> | undefined;
     app: express_serve_static_core.Express;
-};
+}>;
 
 interface DocumentationParams {
     title: string;
@@ -793,28 +806,51 @@ declare class Documentation extends OpenApiBuilder {
     constructor({ routing, config, title, version, serverUrl, successfulResponseDescription, errorResponseDescription, hasSummaryFromDescription, composition, serializer, }: DocumentationParams);
 }
 
-interface TestEndpointProps<REQ, RES, LOG> {
+type MockFunction = <S>(implementation?: (...args: any[]) => any) => S;
+interface TestEndpointProps<REQ, RES, LOG, FN> {
+    /** @desc The endpoint to test */
     endpoint: AbstractEndpoint;
+    /**
+     * @desc Additional properties to set on Request mock
+     * @default { method: "GET", header: () => "application/json" }
+     * */
     requestProps?: REQ;
+    /**
+     * @desc Additional properties to set on Response mock
+     * @default { writableEnded, statusCode, statusMessage, set, setHeader, header, status, json, send, end }
+     * */
     responseProps?: RES;
+    /**
+     * @desc Additional properties to set on config mock
+     * @default { cors: false, logger }
+     * */
     configProps?: Partial<CommonConfig>;
+    /**
+     * @desc Additional properties to set on logger mock
+     * @default { info, warn, error, debug }
+     * */
     loggerProps?: LOG;
-    /** @deprecated for testing purposes only */
-    __noJest?: boolean;
+    /**
+     * @example jest.fn
+     * @example vi.fn
+     * */
+    fnMethod: FN;
 }
 /**
- * @description You need to install Jest and probably @types/jest to use this method
- */
-declare const testEndpoint: <REQ extends Partial<Record<keyof Request<express_serve_static_core.ParamsDictionary, any, any, qs.ParsedQs, Record<string, any>>, any>> | undefined = undefined, RES extends Partial<Record<keyof Response<any, Record<string, any>>, any>> | undefined = undefined, LOG extends Partial<Record<keyof Logger, any>> | undefined = undefined>({ endpoint, requestProps, responseProps, configProps, loggerProps, __noJest, }: TestEndpointProps<REQ, RES, LOG>) => Promise<{
+ * @desc You need to install either jest (with @types/jest) or vitest in order to use this method
+ * @requires jest
+ * @requires vitest
+ * */
+declare const testEndpoint: <FN extends MockFunction, LOG extends Record<string, any>, REQ extends Record<string, any>, RES extends Record<string, any>>({ endpoint, requestProps, responseProps, configProps, loggerProps, fnMethod, }: TestEndpointProps<REQ, RES, LOG, FN>) => Promise<{
     requestMock: {
         method: string;
-    } & Record<"header", jest.Mock<any, any, any>> & (REQ extends undefined ? {} : REQ);
+    } & Record<"header", ReturnType<FN>> & REQ;
     responseMock: {
         writableEnded: boolean;
         statusCode: number;
         statusMessage: string;
-    } & Record<"status" | "set" | "header" | "end" | "send" | "json" | "setHeader", jest.Mock<any, any, any>> & (RES extends undefined ? {} : RES);
-    loggerMock: Record<"error" | "warn" | "debug" | "info", jest.Mock<any, any, any>> & (LOG extends undefined ? {} : LOG);
+    } & Record<"status" | "set" | "header" | "end" | "setHeader" | "json" | "send", ReturnType<FN>> & RES;
+    loggerMock: Record<"info" | "debug" | "warn" | "error", ReturnType<FN>> & LOG;
 }>;
 
 interface Registry {
@@ -887,4 +923,4 @@ declare namespace proprietarySchemas {
   export { proprietarySchemas_dateIn as dateIn, proprietarySchemas_dateOut as dateOut, proprietarySchemas_file as file, proprietarySchemas_raw as raw, proprietarySchemas_upload as upload };
 }
 
-export { AbstractEndpoint, type AppConfig, type BasicSecurity, type BearerSecurity, type CommonConfig, type CookieSecurity, type CustomHeaderSecurity, DependsOnMethod, Documentation, DocumentationError, EndpointsFactory, type FlatObject, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerConfig, type Metadata, type Method, type MiddlewareDefinition, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type ResultHandlerDefinition, type Routing, RoutingError, ServeStatic, type ServerConfig, type ZodDateInDef, type ZodDateOutDef, type ZodFileDef, type ZodUploadDef, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createLogger, createMiddleware, createResultHandler, createServer, defaultEndpointsFactory, defaultResultHandler, proprietarySchemas as ez, getExamples, getMessageFromError, getStatusCodeFromError, testEndpoint, withMeta };
+export { AbstractEndpoint, type AppConfig, type BasicSecurity, type BearerSecurity, type CommonConfig, type CookieSecurity, type CustomHeaderSecurity, DependsOnMethod, Documentation, DocumentationError, EndpointsFactory, type FlatObject, type IOSchema, type InputSecurity, InputValidationError, Integration, type LoggerOverrides, type Metadata, type Method, type MiddlewareDefinition, MissingPeerError, type OAuth2Security, type OpenIdSecurity, OutputValidationError, type ResultHandlerDefinition, type Routing, RoutingError, ServeStatic, type ServerConfig, type ZodDateInDef, type ZodDateOutDef, type ZodFileDef, type ZodUploadDef, arrayEndpointsFactory, arrayResultHandler, attachRouting, createConfig, createMiddleware, createResultHandler, createServer, defaultEndpointsFactory, defaultResultHandler, proprietarySchemas as ez, getExamples, getMessageFromError, getStatusCodeFromError, testEndpoint, withMeta };