Skip to main content

ExpressJS

The @basketry/express generator automates the creation of Express-based APIs, streamlining the process of defining routes, handling requests, and enforcing API contracts. It generates a router factory that creates an Express router for structured error handling, middleware support, and type-safe DTO mappings between internal business objects and API responses. This ensures consistency, maintainability, and adherence to the API schema while allowing developers to focus on business logic rather than boilerplate code.

Install​

npm install @basketry/express

Basic Usage​

basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": ["@basketry/typescript", "@basketry/express", "@basketry/zod"],
  "output": "src",
  "options": {
    "express": {
      "validation": "zod"
    }
  }
}

File Structure​

This generator will create an express directory that contains all the necessary files for an Express-based API. Details about each of these files can be found in Advanced Usage section below.

my-project/
├── node_modules/
├── src/
│ ├── v1/
│ │ ├── express/             <-- generated
│ │ │ ├── dtos.ts            <-- generated
│ │ │ ├── errors.ts          <-- generated
│ │ │ ├── handlers.ts        <-- generated
│ │ │ ├── index.ts           <-- generated
│ │ │ ├── mappers.ts         <-- generated
│ │ │ ├── README.ts          <-- generated
│ │ │ ├── router-factory.ts  <-- generated
│ │ │ └── types.ts           <-- generated
│ │ ├── schemas.ts
│ │ └── types.ts
│ ├── app.ts
│ └── index.ts
├── .gitignore
├── basketry.config.json
├── package.json
├── petstore.json
└── README.md

Options​

This generator depends on the @basketry/typescript generator and all of their applied options will also apply to files emitted by this generator. See: @basketry/typescript options

The @basketry/express generator accepts the following additional options to customize the generated code:

validation​

  • Type: "zod" | "native" - The validation library to use for request validation.
  • Default: "native"
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": ["@basketry/typescript", "@basketry/express", "@basketry/zod"],
  "output": "src",
  "options": {
    "express": {
      "validation": "zod"
    }
  }
}

schemasImportPath​

  • Type: string - The location of the Zod schemas module. (This option is only applicable when validation is set to "zod".)
basketry.config.json
{
  "source": "petstore.json",
  "parser": "@basketry/openapi-3",
  "generators": ["@basketry/typescript", "@basketry/express", "@basketry/zod"],
  "output": "src",
  "options": {
    "express": {
      "validation": "zod",
      "schemasImportPath": "@custom/package/schemas"
    }
  }
}

Advanced Usage​

A project-specific set of docs will be generated in the express/README.md file. Here is a generalized overview of the files generated by this generator.

Router Factory​

The router factory provides the getRouter function, which generates an Express router for the API. The router factory is responsible for creating the Express router, registering the routes, and attaching the appropriate middleware to each route.

Basic Usage​

Mount the router on an Express app:

src/app.ts
import express from "express";
import { getRouter } from "./v1/express/router-factory";

const app = express();

app.use("/v1", [
  getRouter({
    // Update with your OpenAPI schema
    schema: require("./petstore.json"),

    // Update with your service initializers
    getUserService: (req) => new MyUserService(req),
    getWidgetService: (req) => new MyWidgetService(req),
  }),
]);

Custom Middleware​

You can provide custom middleware to the router factory by passing a middleware object to the middleware property of the input object. The middleware object should contain middleware functions keyed by the name of the service method they are associated with.

src/app.ts
import express from "express";
import { getRouter } from "./v1/express/router-factory";
import { authenticationMiddleware } from "../auth";

const app = express();

app.use("/v1", [
  getRouter({
    // TODO: add schema and service initializers

    // Update with your middleware as needed
    middleware: {
      // Added to all routes except the one that serves the Swagger UI
      _exceptSwaggerUI: authenticationMiddleware,

      getWidget: (req, res, next) => {
        // TODO: Implement your custom middleware here
        next();
      },

      deleteWidget: (req, res, next) => {
        // TODO: Implement your custom middleware here
        next();
      },
    },
  }),
]);

Custom Handlers​

The handlers module exports the default generated handlers. These handlers are added to the Express router and generally don't need to be manually imported anywhere to make the API work. Occasionally, the generated handlers won't be sufficient, so the router factory allows for supplying custom handler overrides.

src/app.ts
import express from "express";
import { getRouter } from "./v1/express/router-factory";

const app = express();

app.use("/v1", [
  getRouter({
    // TODO: add schema and service initializers

    // Update with your handlers as needed
    handlerOverrides: {
      getUser: (req, res, next) => {
        // TODO: Implement your custom handler here
        // Note that the params, body, and query values are statically typed
        // per the API contract
      },
    },
  }),
]);

Errors​

This module provides utility functions and types for creating and identifying errors in an ExpressJS API. It defines custom error types for different error conditions such as validation errors, method not allowed, handled exceptions, and unhandled exceptions. Each error type is accompanied by helper functions to generate and identify errors, which can be used in your ExpressJS API error-handling middleware.

Method Not Allowed​

This error type is used to indicate that the HTTP method is not defined on the route in the API contract.

import { RequestHandler } from "express";
import { isMethodNotAllowed } from "./v1/express/errors";

export const handler: RequestHandler = (err, req, res, next) => {
  // Checks to see if the error is a MethodNotAllowedError
  if (isMethodNotAllowed(err)) {
    // TODO: log/instrument occurence of the error

    if (!res.headersSent) {
      // TODO: return an error response
    }
  }
  next(err);
};

Validation Error​

This error type is used to indicate that the request data failed validation against the API contract. This error will contain an array of validation errors provided by the validation library (eg. zod, native, etc).

import { RequestHandler } from "express";
import { isValidationErrors } from "./v1/express/errors";

export const handler: RequestHandler = (err, req, res, next) => {
  // Checks to see if the error is a ValidationErrorsError
  if (isValidationErrors(err)) {
    // TODO: log/instrument occurence of the error

    if (!res.headersSent) {
      // TODO: return an error response
    }
  }
  next(err);
};

Handled Exception​

This error type is used to indicate that an error occured in a service method as was returned in a well-structured format. (This is not supported if the service does not return response envelopes.)

import { RequestHandler } from "express";
import { isHandledException } from "./express/errors";

export const handler: RequestHandler = (err, req, res, next) => {
  // Checks to see if the error is a HandledExceptionError
  if (isHandledException(err)) {
    // TODO: log/instrument occurence of the error

    if (!res.headersSent) {
      // TODO: return an error response
    }
  }
  next(err);
};

Unhandled Exception​

This error type is used to indicate that an unexpected error occured in the API.

import { RequestHandler } from "express";
import { isUnhandledException } from "./v1/express/errors";

export const handler: RequestHandler = (err, req, res, next) => {
  // Checks to see if the error is a UnhandledExceptionError
  if (isUnhandledException(err)) {
    // TODO: log/instrument occurence of the error

    if (!res.headersSent) {
      // TODO: return an error response
    }
  }
  next(err);
};

Data Transfer Objects (DTOs)​

In the generated ExpressJS API code, we use two distinct sets of types: Business Object Types and DTO (Data Transfer Object) Types. These types serve different purposes and are essential for maintaining a clear separation of concerns between internal data structures and the external API contract.

Why Two Sets of Types?​

  • Business Object Types are written in a way that is idiomatic to TypeScript. While they are generated from the API contract, they follow a naming and casing convention consistent with the rest of the codebase.

  • DTO Types represent the over-the-wire format defined by the API contract. These types are used to communicate with external clients, ensuring consistency in the structure and casing of the data being exposed or accepted by the API. These types may have different naming conventions (e.g., snake_case for JSON fields) and might not always align one-to-one with our internal types.

When to Use Business Object Types vs. DTO Types​

Use Business Object Types when you are working within the server and need to interact with our business logic. The vast majority of hand-written code will use these types. Examples of this type of code include service class implementations that contain the actual business logic that powers the API. When in doubt, use Business Object Types.

Use DTO Types when interacting with external clients through the API. This includes:

  • Response Serialization: Transforming internal Business Object Types into DTO Types before sending them in API responses. In most cases, this is handled by the generated mappers.
  • Custom Response handlers: Each service method has a generated response handler that runs the appropriate service method and serializes the response into a DTO. You can override this behavior by providing a custom response handler.

Mappers​

The mappers module exports generated mapper functions. These functions are responsible for mapping between Business Object Types and DTO (Data Transfer Object) Types, both of which are generated from the API contract. The mapper functions guarantee correct transformations between these two sets of types, maintaining consistency between the internal business logic and the external API contract.

Why Use Generated Mapper Functions?​

  • Consistency: Manually mapping between Business Object Types and DTO Types can lead to errors and inconsistencies. By generating the mapper types, we eliminate human error and ensure that the mappings always follow the API contract.

  • Maintainability: As the API evolves, regenerating the mapper types ensures that mappings between types are updated automatically. This significantly reduces the amount of manual work required when the API changes.

When to Use the Mapper Types​

The generated Express API code contains default implementations for the request handlers than can be used as-is. However, if you decide to hand-write custom Express handlers, there are several scenarios where you may need to interact with the mapper types directly:

  • Custom Response handlers: When writing custom response handlers, use the mapper types to convert Business Object Types from and two DTO (Data Transfer Object) Types when interacting with the data on the Express request object.

  • Response Serialization: After processing a request, use the mapper types to convert Business Object Types back into DTO Types to send as the API response.

  • Integration Testing: When validating the interaction between internal logic and the external API, the mapper types can be used to ensure that data is being transformed correctly.