Сегодня я расскажу о том, как мы можем с помощью типов написать простое расширение для ExpressJS.

А если вы в своём приложении/приложениях используете только решения на TypeScript(JavaScript), то у вас отпадёт необходимость в Swagger.

Вообще, одно из главных преимуществ разработки серверного кода на NodeJS — это один язык программирования с Web-интерфейсом/React/Vue Native. Это даёт возможность написать общий код в одном месте только один раз и использовать его затем везде.

Именно это мы сейчас с вами и попытаемся сделать.

Представим простой монорепозиторий, который состоит из двух проектов:

• server: Backend WebAPI, написанный на ExpressJS;

• client: Frontend SPA-клиент, написанный на VanillaJS.

Приложение крайне простое - todo, которое должно уметь создавать, получать и удалять задания. Как обычно поступают в таких условиях? Пишут backend сервер, в лучшем случае подключают к нему swagger (что приводит к существенным изменениям в коде), или ведут Google Table со списком контрактов. В худшем - вам придётся каждый раз смотреть исходный код сервера, и подгонять под него свой код.

Объявляем общие типы

Для начала создадим другую папку в нашем монорепозитории и назовём её shared. Сделаем его npm проектом на typescript, выполнив в корне папке команды:

npm init
npm install typescript --save-dev

Для имени этого проекта я буду использовать имя монорепозитория и название папки:

// shared/package.json
{

    name: @express-ts-react/shared,
    ...
}

Несколько замечаний об этом проекте

Поскольку подразумевается, что код в этом проекте будет использоваться в разных службах и приложениях, то необходимо соблюдать следующие правила:

- Не устанавливать специфичные фреймворки и библиотеки;

- Желательно вообще ничего не устанавливать :)

- Старайтесь писать здесь максимально абстрактный код, или код, который будет работать везде.

- Каждое приложение или сервер, если предоставляет какие-то контракты для работы с ним, должно иметь собственную папку, и оно не должно ниоткуда, кроме common импортировать код.

Теперь создадим папку common в проекте @express-ts-react/shared и объявим её локальным модулем:

// shared/common/package.json

{

  "sideEffects": false,

  "main": "./index.js"

}

Там же создадим файл, в котором мы объявим самые важные генерики, которых уже будет достаточно, чтобы заменить нам swagger. EndpointMeta<T,U> — это тип, который описывает один endpoint. По сути, любой метод нашего RestApi задаётся таким набором. T и U здесь использованы не просто так, они понадобятся для автоматического и динамического формирования интерфейсов наших контроллеров. Пока вам нужно знать, что T —это параметры аргументов, которые принимает метод контроллера, а U — это формат ответа.

// shared/common/index.tsx

/**
 * REST description about endpoint
 * Can be extended with additional fields or methods. For instance, auth protected endpoint
 */

export type EndpointMeta<T = {}, U = {}> = {
  /**
   * helper for type in runtime definition
   */
  _: "endpointMeta";

  /**
   * Endpoint route
   */
  route: `/${string}` | `*`;

  /**
   * Url in express format without route prefix
   */
  url: `/${string}` | `*`;
  
  /**
   * Method in express format, can be extended by others
   */
  method?: "get" | "post" | "put" | "delete";
};

/**
 * Get argument types of endpoint method
 */

export type GetInnerArgsOfMeta<S> = S extends EndpointMeta<infer T, infer S>
  ? T
  : never;

/**
 * Get Response type of endpoint method
 */
export type GetInnerResponseOfMeta<S> = S extends EndpointMeta<infer T, infer S>
  ? S
  : never;

/**
 * Get endpoint type, where key is the endpoint name,
 * args - is the endpoint method arguments
 * and result is endpoint response
 */
export type EndpointsProvider<T extends typeof endpoints> = {
  [key in keyof T]: (
    args: GetInnerArgsOfMeta<T[key]>
  ) => GetInnerResponseOfMeta<T[key]>;
};

А теперь используя только эти четыре типа вы можете легко создавать интерфейсы/контракты для ваших контроллеров, и использовать этот код как на сервере, так и на клиенте. Снизу, например, представлены методы для нашего ToDo приложения:

// shared/server/index.tsx

import { EndpointMeta, EndpointsProvider } from "../shared";

const getTasks: EndpointMeta<
  {
    query?: {
      status?: boolean;
      ids?: string[];
    };
  },
  Promise<Task[]>
> = {
  _: "endpointMeta",
  url: "/",
  method: "get",
};

const getTaskById: EndpointMeta<
  {
    params: {
      id: string;
    };
  },
  Promise<Task>
> = {
  _: "endpointMeta",
 url: "/:id",
  method: "get",
};

const addTask: EndpointMeta<{ body: Task }, Promise<Task>> = {
  _: "endpointMeta",
  url: "/:id",
  method: "post",
};

const deleteTaskById: EndpointMeta<
  {
    params: {
      id: string;
    };
  },
  Promise<Task>
> = {
  _: "endpointMeta",
  url: "/:id",
  method: "delete",
};

// Our final endpoints collection
const endpoints = {
  getTasks,
  getTaskById,
  addTask,
  deleteTaskById,
};

Четыре переменные, по сути, содержат всю необходимую информацию, которую нужно, чтобы:

• Создать ExpressJs роутинг;

• Без подглядывания в сторонние данные написать клиент для этого сервера.

Почему я уверен, что не придётся подглядывать? Давайте создадим простой класс, который можно использовать везде, независимо от среды исполнения и объявим его, как реализующим этот непонятный тип EndpointsProvider:

// shard/server/index.tsx

class TaskController implements EndpointsProvider<typeof endpoints> {}

Если мы оставим класс как есть, то, во-первых, на нас будет ругаться vscode, а во-вторых, при попытки собрать проект командой npx tsc мы увидим ошибку:

blog/index.ts:77:7 - error TS2420: Class 'TaskController' incorrectly implements interface 'EndpointsProvider<{ getTasks: EndpointMeta<{ query?: { status?: boolean | undefined; ids?: string[] | undefined; } | undefined; }, Task[]>; getTaskById: EndpointMeta<{ params: { id: string; }; }, Task>; addTask: EndpointMeta<...>; deleteTaskById: EndpointMeta<...>; }>'.

  Type 'TaskController' is missing the following properties from type 'EndpointsProvider<{ getTasks: EndpointMeta<{ query?: { status?: boolean | undefined; ids?: string[] | undefined; } | undefined; }, Task[]>; getTaskById: EndpointMeta<{ params: { id: string; }; }, Task>; addTask: EndpointMeta<...>; deleteTaskById: EndpointMeta<...>; }>': getTasks, getTaskById, addTask, deleteTaskById

77 class TaskController implements EndpointsProvider<typeof endpoints> {}

Found 1 error.

Эта ошибка говорит, что наш класс TaskController неправильно реализует EndpointsProvider: отсутствуют функции addTask, getTaskById, getTasks, deleteTask. Давайте теперь попробуем реализовать эти методы.

// shared/server/index.tsx

...

class TaskController implements EndpointsProvider<typeof endpoints> {
  getTaskById: (args: {
    params: {
      id: string;
    };
  }) => Task = (args) => {
    return {
      id: "",
      description: "",
      done: true,
    };
  };

  getTasks: (args: {
    query?: {
          status?: boolean;
          ids?: string[];
        };
  }) => Task[] = (args) => {
    return [{
        id: "",
        description: "",
        done: true,
    }];
  };

  addTask: (args: { body: Task }) => Task = (args) => {
    return args.body;
  };

  deleteTaskById: (args: {
    params: {
      id: string;
    };
  }) => Task = (args) => {
    return {
      id: "",
      description: "",
      done: true,
    };
  };
}

Теперь команда npx tsx ничего не пишет нам, а значит, всё работает! Как видно, это класс для контроллера, и в нём уже содержится информация о конкретной реализации методов, поэтому по-хорошему этот класс нужно уже выносить в проект нашего сервера. Чтобы сделать клиент, нужно унаследовать точно такой же интерфейс, но уже вместо конкретной реализации, нужно заменять url на параметры и формировать fetch запрос на сервер.

В следующей части я покажу, как можно автоматизировать на основе const endpoints формирование сервера и класса клиента. А также мы создадим базовый контроллер, запрос и ответ, сделаем их расширяемыми собственными свойствами и спасём себе жизнь от ошибок и сохраним часы и дни для синхронизации работы серверов и клиентов.

При использовании TypeScript код заметно увеличивается в размере, и кому-то это может казаться некрасивым. Но когда вы работаете в современной IDE или текстовом редакторе на стероидах (VSCode) - то вы оцените, насколько силён TypeScript. Его использование существенно снижает количество ошибок, а также доступность для понимания кода для вас и членов вашей команды.