DEV Community: Ilshat Khamitov

My RAG System: How I Built a RAG for My Business Card Website in 8 Days

Ilshat Khamitov — Tue, 27 Jan 2026 13:36:00 +0000

TL;DR:
In 8 days of part-time work, I built a RAG system using NestJS + PostgreSQL (pgvector) that processes ~11,000 document chunks.
The first version responded in about 4 minutes; after optimization, it took 40-60 seconds.
The main takeaway: RAG isn't "vector search + LLM," but rather data preparation, context filtering, and careful handling of prompts.

Why I did this

The main goal of the project was to create a RAG system that could answer questions based on my knowledge and experience. This allowed me to understand real-world work with large volumes of documents.

The RAG system was integrated with my business card website site15.ru. There, I showcase and describe some of my projects from the last 10 years: downloads, stars, views, npm libraries, group counters, posts, and karma on Habr and dev.to.

Technically, it's implemented like this: site15.ru frontend → site15.ru backend → rag-system server. The backend passes a special API key, which at least partially protects the site from unnecessary requests.

Thus, site15.ru acts as a demo and interface for interacting with RAG.

Chat frontend on site15.ru, example of a RAG request and response

Why RAG turned out to be more complicated than it seemed

At the start, the project looked simple:

RAG = vector search + LLM

In practice, it turned out that most of the time was spent on:

data preparation and segmentation,
context filtering,
generating and matching prompts.

The first version of the system did everything sequentially and responded in about 4 minutes even to a simple question.

System Architecture

Data Sources (Telegram messages, articles, portfolios, resumes)
↓
Backend (NestJS)
├─ LLM module
├─ PostgreSQL + pgvector
├─ RxJS asynchronous pipeline
├─ Dialog Manager
└─ API controller for site15.ru
↓
RAG Components
├─ Question Transformer
├─ Document and Section Filtering
├─ Vector Search
└─ Prompt Generation
↓
LLM Providers
(OpenAI / Groq / Ollama)

Choosing a Stack

Backend - NestJS
I constantly write backends in NestJS, so the choice was obvious.

Frontend - React Admin
I needed an admin panel to manage data and prompts.

PostgreSQL + pgvector
One system for regular data and vectors - simpler and more reliable than separate storage.

Multiple LLM Providers
Support for different providers allows you to use free limits and easily switch if needed.

Key Architectural Decision: Hierarchical Filtering

The main idea is to not send everything to LLM.
Request processing pipeline:

User request (frontend site15.ru)
↓
Backend site15.ru
↓
RAG server: query normalization
↓
Metadata filtering (11,000 → ~500)
↓
Section/header filtering (500 → ~200)
↓
Vector search (200 → 5–10)
↓
One optimized request in LLM

This significantly reduced the amount of data sent in LLM, and speed up responses.

The biggest technical challenge

Creating metadata for 11,005 document chunks.
The cloud didn't allow for processing everything at once; I had to run it locally through LM Studio with the qwen2.5-7b-instruct model - it took 2 days on an RTX 2060 SUPER.

Why the first version was slow

First version: 8 intermediate prompts, consecutive LLM calls → ~4 minutes per response.

After optimization: 4 coordinated prompts, some stages are parallel, asynchronous queue on RxJS → 40–60 seconds.

Prompts and Errors

Prompts turned out to be the most challenging aspect. Examples:

Context Leak

User: "Tell me about NestJS"
LLM: "NestJS is a great framework. By the way, I have a Telegram bot for coffee..."

Instruction Conflict

Prompt 1: Be brief
Prompt 2: Provide detailed examples

Conclusion: Fewer, but consistent prompts are better.

Using AI in Development

About 70% of the code was written with the help of AI assistants, but without my architectural editing and debugging, it wouldn't have worked.

Security

Checking the authorized IP address,
Checking the API key for requests from the site15.ru backend.

The project is not production-ready, but this allows us to at least somewhat protect the main site from unnecessary requests.

Deployment

RAG server on a separate VPS,
docker-compose for PostgreSQL and Ollama,
backend via pm2,
integration with site15.ru.

Current status

Experimental project, not MVP, not production-ready.
Site15.ru serves as an interface for demonstrating RAG and project statistics.

Future Plans

Writing user scenario tests (checking response and pipeline correctness).
Refactoring the LLM module to NestJS style.
Adding analytics: processing time, number of LLM calls, token consumption.
Automating deployment via Docker/Kubernetes.
Improving accuracy and speed by optimizing context filtering.

Conclusions

RAG is a complex engineering process: data preparation, context filtering, and careful prompt handling are more important than the LLM itself.

In 8 days of part-time work, I was able to assemble a working system, integrate it with site15.ru, and gain real-world experience with RAG.

Links

https://github.com/site15/rag-system - Project repository
https://site15.ru - My business card website with support chat

My Dashboard: как я превратил старые Android-устройства в кроссплатформенные дашборды с помощью AI и типобезопасного fullstack

Ilshat Khamitov — Sun, 11 Jan 2026 11:17:51 +0000

Введение

У меня дома лежали несколько старых Android-устройств. Рабочие, но без дела. Я задумался: «А что если их использовать как интерактивные дашборды?» — и решил реализовать веб + мобильное приложение, где устройства показывают информацию и позволяют вводить данные.

В разработке активно помогал AI-ассистент Qoder, который написал большую часть кода, а я корректировал ошибки и адаптировал под проект.

Цель проекта

Основная цель: типобезопасный fullstack, где фронт автоматически подтягивает типы с бэка через TypeScript без генерации SDK.

Второстепенная цель: кроссплатформенное приложение, где часть кода и логики используется одновременно на вебе и мобильных устройствах.

Технологический стек

Backend: tRPC + Zod схемы
Frontend: AnalogJS + Formly (SSR, генерация форм с серверной валидацией)
Mobile: Ionic + Capacitor (поддержка старых Android, интеграция с веб-виджетами)
AI: генерация виджетов, форм и части UI (~70% кода)

Архитектура и подход

Все виджеты используют Zod схемы, которые автоматически подтягиваются на фронт для генерации форм.
Формы на фронте получают серверные ошибки валидации прямо в поля формы.
Для SSR пришлось решать несколько нестандартных задач:
- Кэширование между SSR и фронтом иногда срабатывало некорректно → отключил transfer cache.
- Добавил возможность подмены fetch для передачи куки и токенов авторизации.
- Частично решены кейсы авторизованных и неавторизованных запросов при SSR.
На мобильной части с Capacitor/Ionic столкнулся с:
- Поддержкой старых Android SDK
- JS-версией QR-сканеров, так как встроенные не работали
- Шарингом тем и виджетов между вебом и мобильной частью

Что удалось достичь в MVP

Минимальный дашборд с несколькими виджетами, полностью кроссплатформенный (веб + мобильное приложение)
Настроен CI/CD для деплоя веба и мобильного приложения
Частичная поддержка SSR + авторизация
Генерация UI и бизнес-логики с помощью AI
Быстрое прототипирование MVP всего за 1,5 месяца

Выводы и инсайты

AI ускоряет разработку: 70% кода было сгенерировано, а я сосредоточился на архитектуре и интеграции.
Типобезопасный fullstack работает: фронт подтягивает все типы автоматически, без ручной генерации SDK.
Кроссплатформенность возможна, если правильно спроектировать общие виджеты и бизнес-логику.
SSR + авторизация — нюансная тема, но с отключением transfer cache и подменой fetch можно решать кейсы авторизации.

Ресурсы и ссылки

Онлайн версия: https://site15-my-dashboard.vercel.app
Репозиторий: https://github.com/site15/my-dashboard
Статьи о проекте:
- Хабр
- Dev.to

My Dashboard

Ilshat Khamitov — Wed, 07 Jan 2026 14:15:00 +0000

I had several old Android devices lying around at home. They worked, but they hadn't been used for a long time and were just sitting around.

I started thinking about how to use them. I wanted something simple and useful: displaying information and occasionally accepting data. Nothing complicated, just something that would actually be used. That's how the idea of turning them into dashboards came about.

Then I realized I needed a web component and a mobile app. I built a web app using Analog and an Android client using the Ionic Framework. The AI assistant from Qoder actively assisted with the development—it significantly sped up the work and handled many of the tasks automatically.

The project is still in progress, but I decided to write a post about it. Perhaps someone will find my work useful.

Tech Stack

When developing the project, I initially decided to choose technologies I'd never used before—just to try something new. The final choice was:

mobile app — Flutter (I've heard it produces beautiful and fast apps);
web — Vue (I prefer Angular, but I've been wanting to try Vue in a large project for a while);
server — tRPC (I've heard a lot about it: it's fast and allows you to pass typing in a monorepo to the frontend without generating an SDK).

After spending four days setting up the development environment, CI/CD, and deployment, as well as writing simple hello-world apps, I realized that development would drag on because I'd have to learn too many unfamiliar things.

As a result, I switched stacks to more or less familiar technologies:

mobile app — Ionic (I haven't written anything for it in a while);
web — Analog (uses Angular and SSR rendering);
server — Analog + tRPC (since Analog uses tRPC as a server framework in its examples, I decided to keep it).

Initially, I planned to write the bulk of the code manually and without using neural networks, and then incorporate them during the UI design, theming, and layout stages.

In the end, things turned out differently: about 70% of the code was written by the AI. The code was functional, but not perfect. That's fine for a first version—it's now an MVP, and it was more important for me to quickly implement the main features.

Technical Specifications

This can hardly be called a full-fledged technical specification, but I couldn't think of another name. Below is a list of requirements for the first version of the project.

One dashboard can only be linked to one physical device.
A dashboard can contain various widgets for displaying information.
Widgets can not only display information but also transmit data from the dashboard device.
An admin panel is required to create dashboards and link widgets to them.
The admin panel must be able to edit widget options.
Dashboards must support a dark theme.
Login to the admin panel is possible both for an anonymous user and via Telegram authorization.
Examples of widgets with different logic and customization options should be added:
clock — displays three clock faces with three time zones;
calendar — shows how many days have passed since the beginning of the month;
habits — a widget for tracking daily tasks and habits.
The website and mobile app should be deployed automatically via CI/CD with notifications sent to the Telegram channel.

Development Stages

At the beginning of the project, I completed each part separately and in stages: first, I designed the database, then wrote the backend, then the frontend, the mobile app, and then the deployment. Below is a brief overview of each stage.

Database

I usually write database migrations manually and apply them via my migrator:
https://www.npmjs.com/package/pg-flyway

But for this project, I decided to try Prisma's schema-first approach: describe and modify the Prisma schema, and then generate migrations via Prisma Migrate:
https://www.prisma.io/docs/orm/prisma-migrate

Part of the current schema tables:
https://github.com/site15/my-dashboard/blob/main/web/prisma/schema.prisma

model Dashboard {
  id           String    @id(map: "PK_DASHBOARD") @default(uuid()) @db.Uuid
  name         String
  deviceId     String?
  userId       String    @db.Uuid
  isBlackTheme Boolean?
  isActive     Boolean?
  User         User      @relation(fields: [userId], references: [id], onDelete: NoAction, onUpdate: NoAction, map: "FK_DASHBOARD__USER_ID")
  Widget       Widget[]
  createdAt    DateTime  @default(now())
  updatedAt    DateTime  @default(now())
  deletedAt    DateTime?
  qrCodes      QrCode[]  @relation(map: "FK_WIDGET__DASHBOARD_ID")

  @@unique([userId, name], map: "UQ_DASHBOARD__USER_ID_NAME")
  @@unique([deviceId], map: "UQ_DASHBOARD__DEVICE_ID")
  @@index([userId], map: "IDX_DASHBOARD__USER_ID")
}

model Widget {
  id          String @id(map: "PK_WIDGET") @default(uuid()) @db.Uuid
  type        String
  options     Json?
  state       Json?
  columnIndex Int?
  rowIndex    Int?
  columnCount Int?
  rowCount    Int?
  isBlackTheme    Boolean?
  isActive        Boolean?
  backgroundColor String?
  primaryColor    String?
  positiveColor   String?
  negativeColor   String?
  dashboardId String      @db.Uuid
  Dashboard   Dashboard   @relation(fields: [dashboardId], references: [id], onDelete: NoAction, onUpdate: NoAction, map: "FK_WIDGET__DASHBOARD_ID")
  WidgetLog   WidgetLog[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @default(now())
  deletedAt DateTime?

  @@index([dashboardId], map: "IDX_WIDGET__DASHBOARD_ID")
}

Backend

Initially, I planned to use pure tRPC (https://trpc.io), but then I started looking for integration with Angular. That's where I came across the Analog framework (https://analogjs.org), which already has tight SSR integration with tRPC.

As a result, I started writing the backend in the style that Analog demonstrates in its documentation.

Connection example routers:
https://github.com/site15/my-dashboard/blob/main/web/src/server/trpc/routers/index.ts

export const appRouter = router({
  users: userRouter,
  telegram: telegramRouter,
  auth: authRouter,
  dashboards: dashboardsRouter,
  widgets: widgetsRouter,
  userStorage: userStorageRouter,
  device: deviceRouter,
});

// export type definition of API
export type AppRouter = typeof appRouter;

Example controller:
https://github.com/site15/my-dashboard/blob/main/web/src/server/trpc/routers/widgets.ts

export const widgetsRouter = router({
  create: publicProcedure
    .input(CreateWidgetSchema)
    .output(WidgetSchema)
    .mutation(async ({ input, ctx }) => {
      if (!ctx.user) {
        throw new TRPCError({
          code: "FORBIDDEN",
          message: "User not found!",
        });
      }
      return (await prisma.widget.create({
        data: {
          type: input.type,
          options: {
            ...input.options,
            type: input.type,
          } as any,
          columnIndex: input.columnIndex,
          rowIndex: input.rowIndex,
          columnCount: input.columnCount,
          rowCount: input.rowCount,
          isBlackTheme: input.isBlackTheme,
          backgroundColor: input.backgroundColor,
          primaryColor: input.primaryColor,
          positiveColor: input.positiveColor,
          negativeColor: input.negativeColor,
          dashboardId: input.dashboardId,
          createdAt: new Date(),
        },
      })) satisfies WidgetType;
    }),
});

Frontend

Analog components are almost identical to Angular components. I didn't go into the details – at first glance, everything is practically the same.

Unlike typical Angular development, in this project I decided to create both Fewer files were possible to make it easier to "feed" the project to neural networks later. As a result, the components became single-file.

Component example:
https://github.com/site15/my-dashboard/blob/main/web/src/app/pages/dashboards/index.page.ts

export const routeMeta: RouteMeta = {
  canActivate: [ShowNavGuard],
};

@Component({
  selector: "dashboards-list-page",
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [AsyncPipe, LucideAngularModule],
  template: ` <h1 class="text-4xl font-extrabold text-gray-800 mb-2">
      Dashboards
    </h1>
    <p class="text-xl text-gray-500 mb-8">
      Manage your dashboards and widgets.
    </p>

    <div
      class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-5 gap-8"
    >
      @for ( dashboard of dashboards$ | async; track dashboard.id; let last =
      $last ) {
      <a
        href="/dashboards/{{ dashboard.id }}"
        class="bg-white p-6 rounded-2xl long-shadow transition-all duration-300 hover:scale-[1.02] cursor-pointer"
      >
        <div class="flex justify-between items-start mb-4">
          <i-lucide
            name="layout-dashboard"
            class="w-10 h-10 text-pastel-blue bg-pastel-blue/10 rounded-lg"
          ></i-lucide>
          <span
            class="text-sm font-medium text-gray-500 px-3 py-1 bg-gray-100 rounded-full"
            >{{ dashboard.isActive ? "Active" : "Draft" }}</span
          >
        </div>
        <h2 class="text-2xl font-bold text-gray-800 mb-2">
          {{ dashboard.name }}
        </h2>
        <div
          class="flex justify-between items-center text-sm font-medium text-gray-600 pt-2 border-t border-gray-100"
        >
          <span>Widgets: {{ dashboard.widgetsCount }}</span>
          <span
            class="flex items-center text-pastel-blue hover:text-pastel-blue/80"
          >
            Open
            <i-lucide name="arrow-right" class="w-4 h-4 ml-1"></i-lucide>
          </span>
        </div>
      </a>
      @if (last) {
      <a
        class="border-4 border-dashed border-gray-200 rounded-2xl transition-all duration-300 hover:border-pastel-blue/50 hover:bg-pastel-blue/5 cursor-pointer h-40 flex items-center justify-center"
        href="/dashboards/new"
      >
        <i-lucide name="plus" class="w-6 h-6 mr-2"></i-lucide>
        Create New Dashboard
      </a>
      } } @empty {
      <div class="col-span-full text-center py-12 flex flex-col items-center">
        <div class="inline-block p-4 bg-gray-100 rounded-full mb-4">
          <i-lucide
            name="layout-dashboard"
            class="w-12 h-12 text-gray-400"
          ></i-lucide>
        </div>

        <h3 class="text-2xl font-bold text-gray-700 mb-2">No dashboards yet</h3>
        <p class="text-gray-500 max-w-md mx-auto mb-8">
          Get started by creating your first dashboard to organize and visualize
          your data.
        </p>

        <a
          class="border-4 border-dashed border-gray-200 rounded-2xl transition-all duration-300 hover:border-pastel-blue/50 hover:bg-pastel-blue/5 cursor-pointer p-8 flex flex-col items-center justify-center"
          href="/dashboards/new"
        >
          <i-lucide name="plus" class="w-6 h-6 mr-2"></i-lucide>
          Create New Dashboard
        </a>
      </div>
      }
    </div>`,
})
export default class DashboardsListPageComponent {
  private readonly dashboardsService = inject(DashboardsService);

  readonly dashboards$ = this.dashboardsService.list();
}

Service example:
https://github.com/site15/my-dashboard/blob/main/web/src/app/services/dashboards.service.ts

@Injectable({
  providedIn: "root",
})
export class DashboardsService {
  private trpc = injectTrpcClient();

  create(dashboard: CreateDashboardType) {
    return this.trpc.dashboards.create.mutate(
      Object.fromEntries(
        Object.entries(dashboard).filter(([, value]) => value !== "")
      ) as CreateDashboardType
    );
  }

  read(id: string) {
    return this.trpc.dashboards.read.query({ id });
  }

  update(dashboard: UpdateDashboardType) {
    return this.trpc.dashboards.update.mutate(
      Object.fromEntries(
        Object.entries(dashboard).filter(([, value]) => value !== "")
      ) as UpdateDashboardType
    );
  }

  delete(id: string) {
    return this.trpc.dashboards.delete.mutate({ id });
  }

  list() {
    return this.trpc.dashboards.list.query();
  }

  generateQrCode(dashboardId: string) {
    return this.trpc.dashboards.generateQrCode.query({ dashboardId });
  }
}

Mobile App

I've previously written mobile apps using the Ionic Framework, but back then they ran on Cordova / PhoneGap. This time, the app runs on Capacitor.

Currently, development is only for Android, as Android devices are often idle. It's also easier to install apps directly on Android without publishing them to stores.

Deployment

Recently, I've been deploying all my work and personal projects to Kubernetes, but for this project, I decided to try a different approach.

For deployment For the web application, I chose Vercel (https://vercel.com), which allows you to launch small Node.js applications quickly.

Vercel integrates with Supabase (https://supabase.com), where you can create databases and use the built-in authorization system.

Vercel automatically fetches the project from GitHub and deploys it with every code change—I took advantage of this feature.

The mobile application is built using CI/CD inside a Docker container, and the resulting APK file is attached to the release as an artifact.

All scripts for releases, deployment, and sending notifications to Telegram are written using Neural networks:
https://github.com/site15/my-dashboard/blob/main/.github/workflows/release.yml

Authorization

The site supports login via email and password, Telegram, Google, and GitHub, as well as anonymous login.

An anonymous user is a client-side generated 'anonymousId', which is stored in localStorage and used for login.

Authorization via Telegram is implemented using the standard method according to the instructions:
https://edisonchee.com/writing/telegram-login-with-node.js

Login via email, Google, and GitHub is implemented through Vercel integration with Supabase Auth:
https://supabase.com/docs/guides/auth

User Guide

Website

The project is deployed on free hosting and is accessible at the domain:
https://site15-my-dashboard.vercel.app/

Website Registration

When you first log in to the website, you'll be taken to the registration/authorization page.

Click the "Sign Up" link, which will display the fields you need to fill out during registration and a green "Sign Up" button.

Fill in the "Email" and "Password" fields, then click "Sign Up."

Registration Page

Email Confirmation

After successful registration After registering, an email with a confirmation link will be sent to the email address you provided.

Email with email confirmation link

Click the link in the email, and you'll be redirected to the website, where you'll be automatically logged in and your profile will be displayed.Search for our dashboards.

Dashboard Page

Login to the Site

If you've already registered, you'll need to enter your "Email" and "Password," then click "Sign In."

After successful login, you'll be redirected to a page with a list of dashboards.

Dashboard Page

Creating a Dashboard

To create a new dashboard, click "Create New Dashboard," which will open a page with the dashboard's parameters.

Dashboard creation page

Enter a name and click "Create Dashboard", which will open the editing page for the created dashboard.

Dashboard editing page

Adding a clock widget

On the dashboard editing page, there are tabs at the bottom called "Widgets Grid" and "Widgets Preview". Click "Widgets Grid" to display the widget addition panel.

Widget panel

If widgets haven't been added yet, the addition panel with buttons will appear in the middle.

Click the small "clock" button, and you'll be redirected to the widget setup and addition page.

Enter a name for the clock widget and select the 24-hour clock format.

Clock widget add page

Click the "Add clock" button and add all the time zones we need.

Panel with new time zone clocks for the clock widget

After adding all the necessary time zone clocks, click the "Create Widget" button.

Button for adding widget to dashboard

After adding the widget, you are redirected to the dashboard editing page, where the newly added widget is visible.

Dashboard editing page with hourly widget

Adding a habit widget

The process for adding widgets is the same; different widgets may just have different options when creating them.

Habit widget adding page

After adding all the widgets, we can see them on the dashboard editing page.

Dashboard editing page with widget list

Widget Preview

To preview widgets as they will appear on a mobile device, activate the "Widgets Preview" tab on the dashboard editing page.

Widget Preview Panel

Widgets not only display information, but can also be interacted with.

Tapping the clock widget's dial opens a modal window for selecting the active time zone.

Clock widget modal window

The Habits widget also has a modal window where you can add or subtract from a habit counter.

Habits widget modal window

Each change to the habit counter is saved in the history, which can be viewed in this modal window.

Habit counter increase history

Displaying a QR code for linking a mobile device

On the dashboard editing page, there is a "Link Device" button. To link a mobile device, click it.

Dashboard editing page with the link device button

Clicking this button will open a page with a QR code.

Page with QR code for linking a device to the dashboard

Mobile App

The current mobile app is not published in Android stores; you must download the APK file from the website.

Downloading and Installing the Mobile App

On the website, on the login page and in the navigation menu, there is a link to download the latest version of the Android app.

Download link "Download Mobile App" among the links below

Download link "Mobile App" in the left navigation panel

Since the APK file is not from official app stores, not all Android security systems allow its installation.

Application icon after installation

Launch the app—it is not yet linked to the dashboard, so the widgets are not yet displayed.

Empty pageWidget Page

Linking a Mobile Device to the Dashboard

Click the "QR Code" tab at the bottom and you'll be taken to the QR code scanning page, where you click the "SCAN QR" button.

Point the camera at the QR code you received on the website and link your phone to the dashboard.

Scan QR Code

After successful linking, you'll be redirected to the "Dashboard" page, where your widgets are displayed.

Widget Page

Changing the Main Clock in the Clock Widget

Clicking the clock face will open a modal window for setting the main clock, similar to the web version of the clock widget preview.

Clock modal

Completed check mark in the habit widget

The habit modal allows you to increase or decrease the habit counter.

Habit modal

Switching to dark theme

Dashboards support dark theme. You can enable it both on the website through the dashboard settings and in the mobile app on the settings page (the "Settings" button).

Settings page

After switching to dark mode ("Dark Theme"), tap "Save settings" and the app theme will change to dark.

Dark Settings Page

The widget page has also switched to dark mode, and the widgets themselves, along with modal windows, are displayed in dark mode.

Dark Widget Page

Display in Landscape Mode

If you rotate the phone horizontally, the bottom tab bar with app page switches is hidden, as are the native Android top and bottom bars.

Horizontal dark panel with widgets

Real photo of device with dashboard

Unlinking a mobile device

When a device is linked to a dashboard, the previously linked device loses connection with that dashboard.

You can also unlink a device directly from the mobile app: on the settings page, click the "Unlink device" button.

Settings page with a button to unlink a device from a dashboard

Automation

In this project, I decided to abandon ready-made monorepositories (nx, turborepo) and their ecosystem.

For CI/CD convenience, numerous automations generated using a neural network have been added.

The repository contains several projects: a Docker image for building the mobile app, the mobile app itself, and a website. There are both general CI/CD tasks and specific ones for each project.

Releases

Builds and releases are performed independently for each project and are triggered when there are changes in the code.

TODO Tasks

A separate task has been created that collects TODO comments from the website and mobile app code and automatically creates issues in GitHub.

Notifications

Successful and unsuccessful deployment notifications have been added to the Telegram chat.

Roadmap

This is not a full-fledged roadmap for a large product, but a list of goals I wanted to achieve within the project.

Done:

Create a minimal MVP with a few widgets.
Create interface stubs for future business tasks.
Write an article about the work done on Habr.
Record any bugs found while writing the article.

To do:

Describe stubs as tasks and gradually implement them.
Conduct a complete refactoring of the frontend and backend, as most of the code is written using a neural network.
Write a desktop version in Electron for Windows and Linux.
Add offline support.
Add real-time server interaction.
Add the ability to connect widgets as YAML files.
Add all widgets available on the website https://github.com/glanceapp/glance; perhaps it would be worthwhile to support their formats.
Create and publish a Docker image for self-hosted installation.
Add the ability to support new widget types at runtime without re-releasing the mobile app.
Publish the shared mobile app in various app stores.
Add support for Apple devices.

Links

Current online version:
https://site15-my-dashboard.vercel.app

Project repository:
https://github.com/site15/my-dashboard

Telegram chat:
https://t.me/site15_community/187

How I Deployed a Full-Stack Application with "NestJS" with "Angular" on "Supabase" and "Vercel"

Ilshat Khamitov — Fri, 14 Feb 2025 18:49:20 +0000

I developed a small full-stack application as an example of a REST + WebSockets boilerplate using NestJS and Angular. The application uses PostgreSQL for data storage, Redis for caching, and Minio for file handling. Initially, the target deployment environment was Kubernetes, but to speed up development and MVP testing, I decided to use free cloud services: Supabase for infrastructure and Vercel for deploying the backend and frontend.

1. Problems

Development Infrastructure: For local development, it was necessary to set up PostgreSQL, Redis, Minio, and an authorization server (Authorizer.dev). This was time-consuming and resource-intensive.
Complexity of Deployment in Kubernetes: Configuring Docker image builds and deploying to Kubernetes took a lot of time, especially if the Docker images were large.
Limited Budget: For small projects or MVP testing, there was no budget for dedicated servers or a full-fledged Kubernetes infrastructure.

2. Solution

I decided to add the ability to deploy the application not only to Kubernetes but also to free cloud services like Supabase (for databases, storage, and authentication) and Vercel (for backend and frontend deployment). This allowed me to speed up the development and testing process while reducing infrastructure costs.

3. Initial State

Backend: NestJS with REST API and WebSockets for broadcasting events (e.g., current server time).
Frontend: Angular for interacting with the backend via REST and WebSockets.
Infrastructure:
- Locally running services: Authorizer.dev for authentication, PostgreSQL for the database, Redis for caching, and Minio for file storage.
- Deployment to Kubernetes using Docker images for the backend and frontend.
- PostgreSQL and migrations were run via Docker Compose.
- E2E tests were also run via Docker Compose.

4. Current State

Backend and Frontend: Work locally, but the infrastructure has been fully migrated to Supabase.
Cloud Services Used:
- Supabase Auth: Replaced the local Authorizer.dev.
- Supabase Database: Replaced the local PostgreSQL and Redis.
- Supabase Storage: Replaced the local Minio.
Deployment: The backend and frontend are deployed to Vercel. Due to Vercel's serverless architecture, WebSockets do not work, so related tests have been disabled.
CI/CD: Build and deployment are done via GitHub Actions, including applying migrations and running E2E tests.

5. Implementation Steps

5.1. Transition to `Supabase Database`

Local PostgreSQL was replaced with Supabase Database.
For migrations, pg-flyway (a mini-version of Flyway without Java) was used. I didn’t want to lose the functionality of Flyway but also didn’t want to install Java during deployment. As a result, I created a mini-version of flyway — pg-flyway.
In Supabase, you cannot create multiple databases, so migrations are run in a single database using different tables to track migrations. To solve this issue, the migration table name can be passed when running the migrator.
A single user is used for all databases since Supabase does not allow creating new users with database creation rights. This limitation required rethinking the database logic.

5.2. Transition to `Supabase` Instead of `Redis`

Redis was replaced with Keyv with PostgreSQL support. Since the current project did not have any Redis-specific tasks, I decided to replace Redis with an alternative implementation.
During my research, I noticed that the CacheModule for NestJS was transitioning to using Keyv, so I created my own wrapper, nestjs-mod/keyv, which supports both Redis and PostgreSQL.
This is not a full replacement; it only works for simple applications where we cache some data.

5.3. Transition to `Supabase Storage`

Minio was replaced with Supabase Storage.
The main changes involved the logic for generating file upload links. Unlike Minio, in Supabase, buckets and policies are created via the GUI, which complicates automation (this was the only method I could find).
One issue in the code was that the FilesModule was tightly coupled with Minio. I had to decouple it and create a configuration to override methods at the application level through integration configuration.

5.4. Transition to `Supabase Auth`

The local Authorizer.dev was replaced with Supabase Auth.
Problems arose immediately since the AuthModule was previously based entirely on the logic and code for working with Authorizer.
A new NestJS module for working with Supabase Auth was written, compatible with the previous implementation. This module was not written from scratch but by copying code from the existing nestjs-mod/authorizer.
Currently, this new module resides in this project, but it will eventually be moved to nestjs-mod/nestjs-mod-contrib. I’ve had too many issues with existing authorization servers, so I need to write my own custom implementation. Once it’s written and tested for backward compatibility with Supabase and Authorizer, the Supabase implementation will be published as a public npm package.

5.5. Deployment to `Vercel`

This step consumed a lot of time. I won’t describe all the issues I encountered, but there were many. Here’s a link to example configurations I found useful: Vercel configuration examples, and here’s my config for vercel.json.
After setting up deployment to Vercel, if you have e2e tests, some of them will fail because Vercel spins up the application for each request. If the application is not optimized for serverless, like mine, the tests will fail due to slow response times. I solved this by increasing the timeout in the tests.

5.6. Environment Variables

This isn’t a major issue, but it exists. When deploying to your own virtual server, the server is impersonal and can be destroyed at any time, and it doesn’t store environment variables. They are all stored in CI/CD.
When using Vercel and Supabase, there are two additional places where environment variables can be stored. Designing the deployment and launch to account for these variations took a lot of time.

5.7. Registration and Authorization in the Cloud

I won’t describe the registration process for Supabase and Vercel. Instead, I’ll share a short video on how to create applications on Supabase and set environment variables in Vercel.

6. Instructions for Running Local Code with External Infrastructure on `Supabase`

6.1. Initialization

git clone git@github.com:nestjs-mod/nestjs-mod-fullstack.git
cd nestjs-mod-fullstack
npm i
cp ./example-supabase.env ./.env

6.2. Preparation

Create an organization and project on Supabase.
Create a bucket named "images" in the storage (example link: https://supabase.com/dashboard/project/XXX/storage/buckets).
Create new "S3 Access Keys" with "Access key ID" and "Secret access key" (example link: https://supabase.com/dashboard/project/gustcjgbrmmipkizqzso/settings/storage).
Open .env and fill in the empty values.

   # https://supabase.com/dashboard/project/XXX/settings/api - API Settings - Project URL - URL
   SUPABASE_URL=empty_value
   # https://supabase.com/dashboard/project/XXX/settings/database?showConnect=true - Connection String - Direct connection
   POSTGRES_URL=empty_value
   # https://supabase.com/dashboard/project/XXX/settings/api - API Settings - Project API Keys - anon public
   SUPABASE_ANON_KEY=empty_value
   # https://supabase.com/dashboard/project/gustcjgbrmmipkizqzso/settings/storage - S3 Access Keys - New access key - Access key ID
   SERVER_MINIO_ACCESS_KEY=empty_value
   # https://supabase.com/dashboard/project/gustcjgbrmmipkizqzso/settings/storage - S3 Access Keys - New access key - Secret access key
   SERVER_MINIO_SECRET_KEY=empty_value

Create and fill in all necessary new environment keys.

   npx --yes tsx update-files-for-vercel.ts

6.3. Running

npm run pm2-supabase-full:dev:start

6.4. Open the Browser

http://localhost:4200

6.5. Testing

npm run pm2-supabase-full:dev:test:e2e

6.6. Stopping

npm run pm2-supabase-full:dev:stop

Conclusion

Designing and developing the code for this article took me almost two months of part-time work. This makes you think about the necessity of supporting multiple environments for running an application.

I won’t provide code examples here because there were too many changes.

Backward compatibility is achieved by substituting the necessary implementation of configurations and different service implementations, both in the backend and the frontend.

The free version of the cloud infrastructure from Supabase is limited in resources and responds slowly. Deployment to such an environment can only be used during the development of the MVP version.

Since the version deployed to Vercel works as serverless, we don’t have the ability to use internal EventEmitters or RxJS Subjects that we could emit using background global setIntervals in the code. Such logic needs to be solved differently, using Supabase Cron, Supabase Queues, or Supabase Realtime.

Implementing support for multiple deployment and launch options is very labor-intensive, and it’s always better to choose a single deployment path for your application.

Plans

Since I need to write a custom authorization service for work that can be extended as needed, in the next post, I will describe the creation of a basic, simple version...

Update typegraphql-prisma-nestjs v0.2800.5

Ilshat Khamitov — Thu, 23 Jan 2025 21:21:59 +0000

Update typegraphql-prisma-nestjs v0.2800.5

Add option to enable using Dataloader when retrieving nested objects

useDataloaderForResolveFields: 'true' // use dataloader for entities
useDataloaderForAllResolveFields: 'true' // use dataloader for array of entities

Updates to generated code in example:
https://github.com/EndyKaufman/typegraphql-prisma-nestjs-example/commit/265141b23f451baac83b73d2c3273ca0e5b78165

Online example:
https://typegraphql-prisma-nestjs-example.vercel.app/graphql

Package:
https://www.npmjs.com/package/typegraphql-prisma-nestjs

Lite version of Flyway migrator for PostgreSQL in TypeScript

Ilshat Khamitov — Thu, 16 Jan 2025 07:12:38 +0000

Description

In my projects, I always use Flyway to manage database migrations, including some important components of its ecosystem:

Versioned migrations are standard migrations that are applied sequentially one after another.
Repeatable migrations are repeatable migrations, such as scripts for creating procedures. They allow you to track the history of changes using Git.
Callbacks are various hooks that are triggered at a specific time. For example, you can create a script beforeMigrate__init_types.sql, which describes all the custom types used in the database. The migrator first executes this script, and then the rest of the operations.

Since my projects are mostly based on Node.js, I use a Node.js wrapper for Flyway — node-flywaydb. This tool is very easy to use: when launched, it downloads the original Java utility and runs it, so it requires a JVM on the machine to work.

Problem

When we build Docker images intended for running database migrations, we have to include JVM in them, which significantly increases the image size and slows down the whole CI/CD process.

Possible solutions

Use Node.js-migrants (for example: db-migrate, umzug, pg-migrate).
Use migrators built into the ORM used in the project (for example: prisma, typeorm).
Write a lightweight clone of Flyway in Node.js for one database type (PostgreSQL).

The decision made

Since I actively use the features of Flyway, such as repeatable migrations and callbacks, and do not want to give them up, and there are no analogues of these functions in other migration systems, I decided to write my own lightweight clone of Flyway in Node.js for PostgreSQL, which was done.

Development stages

Versioned migrations — done.
Repeatable migrations — done.
Callbacks — partially done, for versioned only.
Flyway schema history table - partially completed, only for versioned and repeatable.
Migration Command Dry Runs - completed.
Baseline migrations - not completed.
Undo migrations - not completed.
Script migrations — not implemented.
Migration transaction handling — not implemented.

There they really have a lot of interesting features, I listed only those that were most useful in my practice.

Example of use

Starting the database

To start the database, run the following command:

curl -fsSL https://raw.githubusercontent.com/EndyKaufman/pg-tools/refs/heads/master/docker-compose.yml -o docker-compose.yml
docker compose up -d

The result will be a successful launch of the PostgreSQL container:

[+] Running 3/3
 ✔ Network pg-tools_default              Created                         0.1s
 ✔ Volume "pg-tools-postgre-sql-volume"  Created                         0.0s
 ✔ Container pg-tools-postgre-sql        Started                         0.2s

Create a migration

To create your first migration, run the following command:

npx pg-flyway create --name=Init --version=1
echo "CREATE TABLE \"User\"(id uuid NOT NULL DEFAULT uuid_generate_v4() constraint PK_USER primary key,email varchar(20));" > migrations/V1__Init.sql

The result will be a successful creation of an empty migration:

[2025-01-15T23:23:53.903] [INFO] CreateEmptyMigrationService - Name: Init
[2025-01-15T23:23:53.904] [INFO] CreateEmptyMigrationService - Locations: migrations
[2025-01-15T23:23:53.914] [INFO] CreateEmptyMigrationService - Migration "migrations/V1__Init.sql" was created successfully!

Applying the migration

To apply the created migration, run the following command:

npx pg-flyway migrate --database-url=postgres://pgtoolsusername:pgtoolspassword@localhost:5432/pgtoolsdatabase?schema=public

The result will be a successful migration:

[2025-01-16T00:08:39.052] [INFO] MigrateService - Locations: migrations
[2025-01-16T00:08:39.053] [INFO] MigrateService - HistoryTable: __migrations
[2025-01-16T00:08:39.053] [INFO] MigrateService - DatabaseUrl: postgres://pgtoolsusername:pgtoolspassword@localhost:5432/pgtoolsdatabase?schema=public
[2025-01-16T00:08:39.074] [INFO] MigrateService - Migrations: 1

Viewing a list of completed migrations

To view a list of completed migrations, run the following command:

npx pg-flyway info --database-url=postgres://pgtoolsusername:pgtoolspassword@localhost:5432/pgtoolsdatabase?schema=public

The result will be a table with information about the completed migrations:

[2025-01-16T09:15:34.007] [INFO] info - HistoryTable: __migrations
[2025-01-16T09:15:34.008] [INFO] info - DatabaseUrl: postgres://pgtoolsusername:pgtoolspassword@localhost:5432/pgtoolsdatabase?schema=public
[2025-01-16T09:15:34.057] [INFO] info - Migrations: 1
┌───────────┬─────────┬─────────────┬──────┬─────────────────────┬─────────┬──────────┐
│  Category │ Version │ Description │ Type │        Installed On │   State │ Undoable │
├───────────┼─────────┼─────────────┼──────┼─────────────────────┼─────────┼──────────┤
│ Versioned │       1 │        Init │  SQL │ 2025-01-15 20:08:39 │ Success │       No │
└───────────┴─────────┴─────────────┴──────┴─────────────────────┴─────────┴──────────┘

Stopping the database

To stop the database, run the following command:

docker compose down

Plans

The main functions of Flyway have already been ported to Typescript code, which provides the necessary functionality for most scenarios when working with migrations.

I plan to port the remaining unported functions as soon as I have free time.

I will be glad to pull requests with new functions and bug fixes.

Converting date by user time zone in "NestJS", and entering and displaying date in "Angular"

Ilshat Khamitov — Sun, 29 Dec 2024 19:47:26 +0000

In this article, I will talk about adding a new field workUntilDate with the type timestamp(6) to the Webhook table of the Webhook database.

On the frontend side (in the Angular application), a convenient calendar with the ability to select a time will be implemented for this field.

Users will be able to set the date and time in their time zone, while the backend (NestJS application) will save the entered data in the database in the UTC+0 format.

In addition, the calendar interface and other elements displaying dates will be adapted to the user's language and time zone.

1. Installing the required libraries

First, let's install the required packages:

Commands

npm install --save @jsverse/transloco-locale @jsverse/transloco-messageformat --prefer-offline --no-audit --progress=false

2. Creating a migration

My migrations are written in a way that they can be re-run.

This is useful in cases where you need to undo the migration and re-run it.

Commands

npm run flyway:create:webhook --args=AddFieldWorkUntilDateToAuthUser

Updating the file libs/feature/webhook/src/migrations/V202412200905__AddFieldWorkUntilDateToAuthUser.sql

DO $$
BEGIN
    ALTER TABLE "Webhook"
        ADD "workUntilDate" timestamp(6);
EXCEPTION
    WHEN duplicate_column THEN
        NULL;
END
$$;

3. Applying migration and updating "Prisma" schemas

Now let's apply the created migration, recreate the Prisma schemas and run the Prisma generators.

Commands

npm run docker-compose:start-prod:server
npm run db:create-and-fill
npm run prisma:pull
npm run generate

After completing these steps, all relevant DTOs will have a new field workUntilDate.

Example of updating DTO file libs/feature/webhook/src/lib/generated/rest/dto/webhook.dto.ts

import { Prisma } from '../../../../../../../../node_modules/@prisma/webhook-client';
import { ApiProperty } from '@nestjs/swagger';

export class WebhookDto {
  // ...
  // updates
  @ApiProperty({
    type: 'string',
    format: 'date-time',
    nullable: true,
  })
  workUntilDate!: Date | null;
}

Example of updating a Prisma schema libs/feature/webhook/src/prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
  engineType = "binary"
  output   = "../../../../../node_modules/@prisma/webhook-client"
  binaryTargets = ["native","linux-musl","debian-openssl-1.1.x","linux-musl-openssl-3.0.x"]
}

// ...

model Webhook {
  id                                         String       @id(map: "PK_WEBHOOK") @default(dbgenerated("uuid_generate_v4()")) @db.Uuid
  // ...
  workUntilDate                              DateTime?    @db.Timestamp(6) /// <-- updates
}

4. Using "AsyncLocalStorage" to store the user's current timezone

Previously, we used AuthTimezoneInterceptor to convert the output of dates in UTC-0 format to a format that respects the user's timezone.

The conversion of the incoming date from the user's timezone to the UTC-0 date in which it is stored in the database is done in AuthTimezonePipe.

However, in this context, we do not have access to the request data, so it is not possible to determine the user and their timezone.

To solve this problem, we wrap each incoming request in AsyncLocalStorage, which will allow us to obtain the user's timezone information.

Updating the file libs/core/auth/src/lib/interceptors/auth-timezone.interceptor.ts

// ...
import { AsyncLocalStorage } from 'node:async_hooks';
import { AuthAsyncLocalStorageData } from '../types/auth-async-local-storage-data';

@Injectable()
export class AuthTimezoneInterceptor implements NestInterceptor<TData, TData> {
  constructor(
    // ...
    private readonly asyncLocalStorage: AsyncLocalStorage<AuthAsyncLocalStorageData>
  ) {}

  intercept(context: ExecutionContext, next: CallHandler) {
    const req: AuthRequest = getRequestFromExecutionContext(context);
    const userId = req.authUser?.externalUserId;

    if (!this.authEnvironments.useInterceptors) {
      return next.handle();
    }

    if (!userId) {
      return next.handle();
    }

    const run = () => {
      const result = next.handle();

      if (isObservable(result)) {
        return result.pipe(
          concatMap(async (data) => {
            const user = await this.authCacheService.getCachedUserByExternalUserId(userId);
            return this.authTimezoneService.convertObject(data, user?.timezone);
          })
        );
      }
      if (result instanceof Promise && typeof result?.then === 'function') {
        return result.then(async (data) => {
          if (isObservable(data)) {
            return data.pipe(
              concatMap(async (data) => {
                const user = await this.authCacheService.getCachedUserByExternalUserId(userId);
                return this.authTimezoneService.convertObject(data, user?.timezone);
              })
            );
          } else {
            const user = await this.authCacheService.getCachedUserByExternalUserId(userId);
            // need for correct map types with base method of NestInterceptor
            return this.authTimezoneService.convertObject(data, user?.timezone) as Observable<TData>;
          }
        });
      }
      // need for correct map types with base method of NestInterceptor
      return this.authTimezoneService.convertObject(result, req.authUser?.timezone) as Observable<TData>;
    };

    if (!this.authEnvironments.usePipes) {
      return run();
    }

    return this.asyncLocalStorage.run({ authTimezone: req.authUser?.timezone || 0 }, () => run());
  }
}

5. Creating a "Pipe" to transform the input object

We implement a Pipe that will subtract the user's time zone from all fields of the input object that contain date strings.

If the time zone of the backend server itself is different from UTC-0, then we subtract the difference.

Updating the file libs/core/auth/src/lib/pipes/auth-timezone.pipe.ts

import { SERVER_TIMEZONE_OFFSET } from '@nestjs-mod-fullstack/common';
import { Injectable, PipeTransform } from '@nestjs/common';
import { AsyncLocalStorage } from 'node:async_hooks';
import { AuthEnvironments } from '../auth.environments';
import { AuthTimezoneService } from '../services/auth-timezone.service';
import { AuthAsyncLocalStorageData } from '../types/auth-async-local-storage-data';

@Injectable()
export class AuthTimezonePipe implements PipeTransform {
  constructor(private readonly asyncLocalStorage: AsyncLocalStorage<AuthAsyncLocalStorageData>, private readonly authTimezoneService: AuthTimezoneService, private readonly authEnvironments: AuthEnvironments) {}

  transform(value: unknown) {
    if (!this.authEnvironments.usePipes) {
      return value;
    }
    const result = this.authTimezoneService.convertObject(value, -1 * (this.asyncLocalStorage.getStore()?.authTimezone || 0) - SERVER_TIMEZONE_OFFSET);
    return result;
  }
}

6. Registering an interceptor and a service for storing asynchronous state in the authorization module

Now let's add the created interceptor and a service for storing asynchronous state to the authorization module.

Updating the file libs/core/auth/src/lib/auth.module.ts

// ...
import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from '@nestjs/core';
// ...
import { AsyncLocalStorage } from 'node:async_hooks';
import { AuthTimezonePipe } from './pipes/auth-timezone.pipe';

export const { AuthModule } = createNestModule({
  // ...
  sharedProviders: [
    {
      provide: AsyncLocalStorage,
      useValue: new AsyncLocalStorage(),
    },
    AuthTimezoneService,
    AuthCacheService,
  ],
  providers: [
    // ...
    { provide: APP_PIPE, useClass: AuthTimezonePipe },
    AuthAuthorizerService,
    AuthAuthorizerBootstrapService,
  ],
  // ...
});

7. Adding a new field type "date-input" for "Formly"

Although the standard HTML input field supports entering and displaying data with the Date type, its appearance differs from the components provided by ng.ant.design.

To keep the interface consistent, we will create a new date-input control for Formly.

Create a file libs/common-angular/src/lib/formly/date-input.component.ts

import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { ReactiveFormsModule } from '@angular/forms';
import { TranslocoService } from '@jsverse/transloco';
import { FieldType, FieldTypeConfig, FormlyModule } from '@ngx-formly/core';
import { NzDatePickerModule } from 'ng-zorro-antd/date-picker';
import { map, Observable } from 'rxjs';
import { DATE_INPUT_FORMATS } from '../constants/date-input-formats';
import { ActiveLangService } from '../services/active-lang.service';

@Component({
  selector: 'date-input',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [ReactiveFormsModule, FormlyModule, NzDatePickerModule, AsyncPipe],
  template: ` <nz-date-picker [formControl]="formControl" [formlyAttributes]="field" [nzShowTime]="true" [nzFormat]="(format$ | async)!"></nz-date-picker> `,
})
export class DateInputComponent extends FieldType<FieldTypeConfig> {
  format$: Observable<string>;

  constructor(private readonly translocoService: TranslocoService, private readonly activeLangService: ActiveLangService) {
    super();
    this.format$ = translocoService.langChanges$.pipe(
      map((lang) => {
        const { locale } = this.activeLangService.normalizeLangKey(lang);
        return DATE_INPUT_FORMATS[locale] ? DATE_INPUT_FORMATS[locale] : DATE_INPUT_FORMATS['en-US'];
      })
    );
  }
}

The calendar now correctly displays buttons in the selected locale, but the content of the input field itself remains unchanged.

To solve this problem, let's create a list of main locales and output formats and set the format to be set as the date output in input.

Create a file libs/common-angular/src/lib/constants/date-input-formats.ts

export const DATE_INPUT_FORMATS = {
  'en-US': 'MM/dd/yyyy HH:mm:ss',
  'en-GB': 'dd/MM/yyyy HH:mm:ss',
  'ar-SA': 'dd/MM/yyyy هه:sس',
  'bg-BG': 'd.M.yyyy H:m:s ч.',
  'ca-ES': 'dd/MM/yyyy H:mm:ss',
  'cs-CZ': 'd.M.yyyy H:mm:ss',
  'da-DK': 'dd-MM-yyyy HH:mm:ss',
  'de-DE': 'dd.MM.yyyy HH:mm:ss',
  'el-GR': 'd/M/yyyy h:mm:ss πμ|μμ',
  'es-MX': 'dd/MM/yyyy H:mm:ss',
  'fi-FI': 'd.M.yyyy klo H.mm.ss',
  'fr-FR': 'dd/MM/yyyy HH:mm:ss',
  'he-IL': 'dd/MM/yyyy HH:mm:ss',
  'hi-IN': 'dd-MM-yyyy hh:mm:ss बजे',
  'hr-HR': 'd.M.yyyy. H:mm:ss',
  'hu-HU': 'yyyy.MM.dd. H:mm:ss',
  'id-ID': 'dd/MM/yyyy HH:mm:ss',
  'is-IS': 'd.M.yyyy kl. HH:mm:ss',
  'it-IT': 'dd/MM/yyyy HH:mm:ss',
  'ja-JP': 'yyyy/MM/dd HH:mm:ss',
  'ko-KR': 'yyyy년 MM월 dd일 HH시 mm분 ss초',
  'lt-LT': 'yyyy.MM.dd. HH:mm:ss',
  'lv-LV': 'yyyy.gada MM.mēnesis dd.diena HH:mm:ss',
  'ms-MY': 'dd/MM/yyyy HH:mm:ss',
  'nl-NL': 'dd-MM-yyyy HH:mm:ss',
  'no-NO': 'dd.MM.yyyy HH:mm:ss',
  'pl-PL': 'dd.MM.yyyy HH:mm:ss',
  'pt-BR': 'dd/MM/yyyy HH:mm:ss',
  'ro-RO': 'dd.MM.yyyy HH:mm:ss',
  'ru-RU': 'dd.MM.yyyy HH:mm:ss',
  'sk-SK': 'd. M. yyyy H:mm:ss',
  'sl-SI': 'd.M.yyyy H:mm:ss',
  'sr-RS': 'dd.MM.yyyy. HH:mm:ss',
  'sv-SE': 'yyyy-MM-dd HH:mm:ss',
  'th-TH': 'วันที่ d เดือน M ปี yyyy เวลา H:mm:ss',
  'tr-TR': 'dd.MM.yyyy HH:mm:ss',
  'uk-UA': 'dd.MM.yyyy HH:mm:ss',
  'vi-VN': 'dd/MM/yyyy HH:mm:ss',
  'zh-CN': 'yyyy年MM月dd日 HH时mm分ss秒',
  'zh-TW': 'yyyy年MM月dd日 HH時mm分ss秒',
};

Let's define new types in a variable, which we will later include in the application configuration.

Create a file libs/common-angular/src/lib/formly/formly-fields.ts

import { TypeOption } from '@ngx-formly/core/lib/models';
import { DateInputComponent } from './date-input.component';

export const COMMON_FORMLY_FIELDS: TypeOption[] = [
  {
    name: 'date-input',
    component: DateInputComponent,
    extends: 'input',
  },
];

8. Developing a service for changing locale in different components of a frontend application

Since different components use their own unique mechanisms for changing the language, we will combine them into a single service and method.

Create a file libs/common-angular/src/lib/services/active-lang.service.ts

import { Inject, Injectable } from '@angular/core';
import { toCamelCase, TranslocoService } from '@jsverse/transloco';
import { LangToLocaleMapping, TRANSLOCO_LOCALE_LANG_MAPPING, TranslocoLocaleService } from '@jsverse/transloco-locale';
import * as dateFnsLocales from 'date-fns/locale';
import * as ngZorroLocales from 'ng-zorro-antd/i18n';
import { NzI18nService } from 'ng-zorro-antd/i18n';

@Injectable({ providedIn: 'root' })
export class ActiveLangService {
  constructor(
    private readonly translocoService: TranslocoService,
    private readonly translocoLocaleService: TranslocoLocaleService,
    private readonly nzI18nService: NzI18nService,
    @Inject(TRANSLOCO_LOCALE_LANG_MAPPING)
    readonly langToLocaleMapping: LangToLocaleMapping
  ) {}

  applyActiveLang(lang: string) {
    const { locale, localeInSnakeCase, localeInCamelCase } = this.normalizeLangKey(lang);

    this.translocoService.setActiveLang(lang);
    this.translocoLocaleService.setLocale(locale);

    if (ngZorroLocales[localeInSnakeCase]) {
      this.nzI18nService.setLocale(ngZorroLocales[localeInSnakeCase]);
    }

    if (dateFnsLocales[lang]) {
      this.nzI18nService.setDateLocale(dateFnsLocales[lang]);
    }
    if (dateFnsLocales[localeInCamelCase]) {
      this.nzI18nService.setDateLocale(dateFnsLocales[localeInCamelCase]);
    }
  }

  normalizeLangKey(lang: string) {
    const locale = this.langToLocaleMapping[lang];
    const localeInCamelCase = toCamelCase(locale);
    const localeInSnakeCase = locale.split('-').join('_');
    return { locale, localeInSnakeCase, localeInCamelCase };
  }
}

9. Connecting the necessary elements to the application configuration for switching the locale in components working with dates

Now we will connect everything necessary to the configuration of our application to ensure correct switching of the locale in components for working with dates.

Updating the file apps/client/src/app/app.config.ts

import { provideTranslocoMessageformat } from '@jsverse/transloco-messageformat';

// ...

import { COMMON_FORMLY_FIELDS } from '@nestjs-mod-fullstack/common-angular';
import { FILES_FORMLY_FIELDS } from '@nestjs-mod-fullstack/files-angular';

// ...

export const appConfig = ({ authorizerURL, minioURL }: { authorizerURL: string; minioURL: string }): ApplicationConfig => {
  return {
    providers: [
      // ...
      importProvidersFrom(
        // ...
        FormlyModule.forRoot({
          // <--updates
          types: [...FILES_FORMLY_FIELDS, ...COMMON_FORMLY_FIELDS],
        })
      ),
      // ...
      provideTranslocoLocale({
        // <--updates
        defaultLocale: 'en-US',
        langToLocaleMapping: {
          en: 'en-US',
          ru: 'ru-RU',
        },
      }),
      provideTranslocoMessageformat({
        // <--updates
        locales: ['en-US', 'ru-RU'],
      }),
      // ...
    ],
  };
};

10. Adding a new input field on the front end in the "Webhook" module

The new form field can function as a standard type=input element with the props.type=datetime-local type, or as a custom type=date-input field.

Updating the file libs/feature/webhook-angular/src/lib/services/webhook-form.service.ts

import { Injectable } from '@angular/core';
import { TranslocoService } from '@jsverse/transloco';
import { UpdateWebhookDtoInterface, ValidationErrorMetadataInterface, WebhookEventInterface, WebhookScalarFieldEnumInterface } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { ValidationService } from '@nestjs-mod-fullstack/common-angular';
import { UntilDestroy } from '@ngneat/until-destroy';
import { FormlyFieldConfig } from '@ngx-formly/core';
import { tap } from 'rxjs';
import { WebhookEventsService } from './webhook-events.service';

@UntilDestroy()
@Injectable({ providedIn: 'root' })
export class WebhookFormService {
  protected events: WebhookEventInterface[] = [];

  constructor(protected readonly webhookEventsService: WebhookEventsService, protected readonly translocoService: TranslocoService, protected readonly validationService: ValidationService) {}

  init() {
    return this.webhookEventsService.findMany().pipe(
      tap((events) => {
        this.events = events;
      })
    );
  }

  getFormlyFields(options?: {
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    data?: UpdateWebhookDtoInterface;
    errors?: ValidationErrorMetadataInterface[];
  }): FormlyFieldConfig[] {
    return this.validationService.appendServerErrorsAsValidatorsToFields(
      [
        {
          key: WebhookScalarFieldEnumInterface.enabled,
          type: 'checkbox',
          validation: {
            show: true,
          },
          props: {
            label: this.translocoService.translate(`webhook.form.fields.enabled`),
            placeholder: 'enabled',
            required: true,
          },
        },
        {
          key: WebhookScalarFieldEnumInterface.endpoint,
          type: 'input',
          validation: {
            show: true,
          },
          props: {
            label: this.translocoService.translate(`webhook.form.fields.endpoint`),
            placeholder: 'endpoint',
            required: true,
          },
        },
        {
          key: WebhookScalarFieldEnumInterface.eventName,
          type: 'select',
          validation: {
            show: true,
          },
          props: {
            label: this.translocoService.translate(`webhook.form.fields.event-name`),
            placeholder: 'eventName',
            required: true,
            options: (this.events || []).map((e) => ({
              value: e.eventName,
              label: `${e.eventName} - ${e.description}`,
            })),
          },
        },
        {
          key: WebhookScalarFieldEnumInterface.headers,
          type: 'textarea',
          validation: {
            show: true,
          },
          props: {
            label: this.translocoService.translate(`webhook.form.fields.headers`),
            placeholder: 'headers',
          },
        },
        {
          key: WebhookScalarFieldEnumInterface.requestTimeout,
          type: 'input',
          validation: {
            show: true,
          },
          props: {
            type: 'number',
            label: this.translocoService.translate(`webhook.form.fields.request-timeout`),
            placeholder: 'requestTimeout',
            required: false,
          },
        },
        {
          key: WebhookScalarFieldEnumInterface.workUntilDate, // <-- updates
          type: 'date-input',
          validation: {
            show: true,
          },
          props: {
            type: 'datetime-local',
            label: this.translocoService.translate(`webhook.form.fields.work-until-date`),
            placeholder: 'workUntilDate',
            required: false,
          },
        },
      ],
      options?.errors || []
    );
  }
}

To convert incoming and outgoing data on the client side, you will need to create mappers, which we will describe in a specialized service.

Considering the possible offset of the user's browser time zone, when converting a string with a date received from the server into a browser date object, it is necessary to take into account the offset of the browser time zone.

Create a file libs/feature/webhook-angular/src/lib/services/webhook-mapper.service.ts

import { Injectable } from '@angular/core';
import { WebhookInterface } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { BROWSER_TIMEZONE_OFFSET, safeParseJson } from '@nestjs-mod-fullstack/common-angular';
import { addHours, format } from 'date-fns';

export interface WebhookModel extends Partial<Omit<WebhookInterface, 'workUntilDate' | 'createdAt' | 'updatedAt' | 'headers'>> {
  headers?: string | null;
  createdAt?: Date | null;
  updatedAt?: Date | null;
  workUntilDate?: Date | null;
}

@Injectable({ providedIn: 'root' })
export class WebhookMapperService {
  toModel(item?: WebhookInterface): WebhookModel {
    return {
      ...item,
      headers: item?.headers ? JSON.stringify(item.headers) : '',
      requestTimeout: item?.requestTimeout ? +item.requestTimeout : null,
      workUntilDate: item?.workUntilDate ? addHours(new Date(item.workUntilDate), BROWSER_TIMEZONE_OFFSET) : null,
      createdAt: item?.createdAt ? addHours(new Date(item.createdAt), BROWSER_TIMEZONE_OFFSET) : null,
      updatedAt: item?.updatedAt ? addHours(new Date(item.updatedAt), BROWSER_TIMEZONE_OFFSET) : null,
    };
  }

  toForm(model: WebhookModel) {
    return {
      ...model,
      requestTimeout: model.requestTimeout ? model.requestTimeout : '',
      workUntilDate: model.workUntilDate ? format(model.workUntilDate, 'yyyy-MM-dd HH:mm:ss') : null,
    };
  }

  toJson(data: WebhookModel) {
    return {
      enabled: data.enabled === true,
      endpoint: data.endpoint || '',
      eventName: data.eventName || '',
      headers: data.headers ? safeParseJson(data.headers) : null,
      requestTimeout: data.requestTimeout ? +data.requestTimeout : null,
      workUntilDate: data.workUntilDate ? format(new Date(data.workUntilDate), 'yyyy-MM-dd HH:mm:ss') : undefined,
    };
  }
}

11. Connecting a localization pipe to display dates on the front

In all places where we display the date, we should add processing via a pipe.

Example of adding a pipe apps/client/src/app/app.component.html

<nz-layout class="layout">
  <!-- ... -->
  <nz-footer class="flex justify-between">
    <!-- ... -->
    <div id="serverTime">{{ (serverTime$ | async)! | translocoDate : { dateStyle: 'medium', timeStyle: 'medium' } }}</div>
  </nz-footer>
</nz-layout>

12. Adaptation of tests related to interface localization

Until now, in the interface, we displayed dates in the format received from the backend.

Now, thanks to the implementation of real-time localization, all data with dates is automatically adapted to the user's settings.

Accordingly, all our tests that check the output data containing dates stopped working correctly.

The number of necessary changes is large, but the principle of adaptation is the same everywhere.

Example of updating the test apps/client-e2e/src/ru-example.spec.ts

import { expect, Page, test } from '@playwright/test';
import { join } from 'path';
import { setTimeout } from 'timers/promises';

test.describe('basic usage (ru)', () => {
  // ...

  // <-- updates
  test('has serverTime format should be equal to "21 дек. 2024 г., 13:56:00" without "13:56:00"', async () => {
    await page.goto('/', {
      timeout: 7000,
    });

    await setTimeout(4000);

    const serverTime = await page.locator('#serverTime').innerText();
    expect(
      serverTime
        .split(' ')
        .filter((p, i) => i !== 4)
        .join(' ')
    ).toEqual(
      new Intl.DateTimeFormat('ru-RU', {
        dateStyle: 'medium',
        timeStyle: 'medium',
      })
        .format(new Date())
        .split(' ')
        .filter((p, i) => i !== 4)
        .join(' ')
    );
  });
});

13. Generating additional files, updating dictionaries and launching the infrastructure in development mode

Now we will start generating additional files, update dictionaries and activate the application infrastructure in development mode.

After that, we will perform a final functionality check through E2E tests.

Commands

npm run manual:prepare
npm run translates
npm run pm2-full:dev:start
npm run pm2-full:dev:test:e2e

Conclusion

Although my goal was to change the code as little as possible, it turned out to be quite a large update again, despite adding only one field with the Date type.

New field types rarely need to be added, because before starting a project, a thorough analysis of future tasks is usually carried out and the main types of objects are determined, for which the corresponding input and output components are developed.

At the moment, the project provides examples of working with various data types: string values, numbers, dictionaries, switches, files and date-time.

These types are quite sufficient for creating a small CRM system.

If additional customization is needed, you can look at the implementation of custom components for file and date-time.

Plans

The main aspects of writing typical REST code have already been covered in previous articles.

I intentionally did not touch upon the issues of queue integration and working with microservices, as they deserve separate series of articles not related to the current REST boilerplate.

To date, the production part of the project is tightly linked to the creation of Docker images and deployment to Kubernetes, which can be excessively complex for many frontend and backend developers.

In the next article, I will try to describe a simplified approach to DevOps, focused on free or shareware cloud solutions.

P.S.

Happy New Year 2025! I wish you all health, love and good luck! 🥳🥳🥳

Integrating and storing the selected user language into the database in a full-stack application on "Angular" and "NestJS"

Ilshat Khamitov — Mon, 16 Dec 2024 07:35:45 +0000

This post does not pretend to be large-scale, but since I consistently document all stages of boilerplate development in the article format, I decided to describe this task as well.

Here I will give an example of a database migration for adding a new field, and also show how to implement the corresponding functionality on the backend and frontend to change this value.

The user language, like the time zone, will be stored in the Auth database.

1. Creating a migration to add a new field

At this stage, we will migrate the database, adding a new field to store the selected information.

Commands

# Create empty migration
npm run flyway:create:auth --args=AddFieldLangToAuthUser

Fill the migration file with SQL script needed to create new column.

Update the file libs/core/auth/src/migrations/V202412141339__AddFieldLangToAuthUser.sql

DO $$
BEGIN
    ALTER TABLE "AuthUser"
        ADD "lang" varchar(2);
EXCEPTION
    WHEN duplicate_column THEN
        NULL;
END
$$;

2. Applying the generated migrations and updating the Prisma schemas

After you have finished creating the migrations, you need to apply them, update the Prisma schemas for all databases and restart the Prisma generators.

Commands

npm run db:create-and-fill
npm run prisma:pull
npm run generate

Schema file for the new database libs/core/auth/src/prisma/schema.prisma

generator client {
  provider      = "prisma-client-js"
  output        = "../../../../../node_modules/@prisma/auth-client"
  binaryTargets = ["native", "linux-musl", "debian-openssl-1.1.x", "linux-musl-openssl-3.0.x"]
  engineType    = "binary"
}

generator prismaClassGenerator {
  provider                        = "prisma-generator-nestjs-dto"
  output                          = "../lib/generated/rest/dto"
  flatResourceStructure           = "false"
  dtoSuffix                       = "Dto"
  entityPrefix                    = ""
  prettier                        = "true"
  annotateAllDtoProperties        = "true"
  fileNamingStyle                 = "kebab"
  noDependencies                  = "false"
  updateDtoPrefix                 = "Update"
  exportRelationModifierClasses   = "true"
  entitySuffix                    = ""
  outputToNestJsResourceStructure = "false"
  reExport                        = "false"
  definiteAssignmentAssertion     = "true"
  createDtoPrefix                 = "Create"
  classValidation                 = "true"
}

datasource db {
  provider = "postgres"
  url      = env("SERVER_AUTH_DATABASE_URL")
}

model AuthUser {
  id             String   @id(map: "PK_AUTH_USER") @default(dbgenerated("uuid_generate_v4()")) @db.Uuid
  externalUserId String   @unique(map: "UQ_AUTH_USER") @db.Uuid
  userRole       AuthRole
  timezone       Float?
  /// @DtoCreateHidden
  /// @DtoUpdateHidden
  createdAt      DateTime @default(now()) @db.Timestamp(6)
  /// @DtoCreateHidden
  /// @DtoUpdateHidden
  updatedAt      DateTime @default(now()) @db.Timestamp(6)
  lang           String?  @db.VarChar(2)  // <--updates

  @@index([userRole], map: "IDX_AUTH_USER__USER_ROLE")
}

model migrations {
  installed_rank Int      @id(map: "__migrations_pk")
  version        String?  @db.VarChar(50)
  description    String   @db.VarChar(200)
  type           String   @db.VarChar(20)
  script         String   @db.VarChar(1000)
  checksum       Int?
  installed_by   String   @db.VarChar(100)
  installed_on   DateTime @default(now()) @db.Timestamp(6)
  execution_time Int
  success        Boolean

  @@index([success], map: "__migrations_s_idx")
  @@map("__migrations")
}

enum AuthRole {
  Admin
  User
}

After a successful restart of the generators, all DTOs associated with the AuthUser table will have a new lang field.

Updated file libs/core/auth/src/lib/generated/rest/dto/auth-user.entity.ts

import { AuthRole } from '../../../../../../../../node_modules/@prisma/auth-client';
import { ApiProperty } from '@nestjs/swagger';

export class AuthUser {
  @ApiProperty({
    type: 'string',
  })
  id!: string;
  @ApiProperty({
    type: 'string',
  })
  externalUserId!: string;
  @ApiProperty({
    enum: AuthRole,
    enumName: 'AuthRole',
  })
  userRole!: AuthRole;
  @ApiProperty({
    type: 'number',
    format: 'float',
    nullable: true,
  })
  timezone!: number | null;
  @ApiProperty({
    type: 'string',
    format: 'date-time',
  })
  createdAt!: Date;
  @ApiProperty({
    type: 'string',
    format: 'date-time',
  })
  updatedAt!: Date;
  @ApiProperty({
    type: 'string',
    nullable: true,
  })
  lang!: string | null; // <--updates
}

3. Changes in DTO and methods for getting and updating the user profile

To update the new lang field, you can create a separate method or adapt the existing methods for getting and updating the profile. In this article, we will choose the second option - modifying the existing methods.

Updating the DTO file libs/core/auth/src/lib/types/auth-profile.dto.ts

import { PickType } from '@nestjs/swagger';
import { CreateAuthUserDto } from '../generated/rest/dto/create-auth-user.dto';

export class AuthProfileDto extends PickType(CreateAuthUserDto, ['timezone', 'lang']) {}

Since the allowed languages are limited to a certain set of values, it is necessary to check the correctness of the incoming data on the server.

There are several approaches to implementing such a check. In this case, I will perform the check inside the method and throw a validation error, similar to how the validation pipe does it. This approach will help to unify the handling of field errors on the client side.

Now let's update the controller libs/core/auth/src/lib/controllers/auth.controller.ts

import { StatusResponse } from '@nestjs-mod-fullstack/common';
import { ValidationError, ValidationErrorEnum } from '@nestjs-mod-fullstack/validation';
import { InjectPrismaClient } from '@nestjs-mod/prisma';
import { Body, Controller, Get, Post } from '@nestjs/common';
import { ApiBadRequestResponse, ApiExtraModels, ApiOkResponse, ApiTags, refs } from '@nestjs/swagger';
import { AuthRole, PrismaClient } from '@prisma/auth-client';
import { InjectTranslateFunction, TranslateFunction, TranslatesService, TranslatesStorage } from 'nestjs-translates';
import { AUTH_FEATURE } from '../auth.constants';
import { CheckAuthRole, CurrentAuthUser } from '../auth.decorators';
import { AuthError } from '../auth.errors';
import { AuthUser } from '../generated/rest/dto/auth-user.entity';
import { AuthEntities } from '../types/auth-entities';
import { AuthProfileDto } from '../types/auth-profile.dto';
import { AuthCacheService } from '../services/auth-cache.service';

@ApiExtraModels(AuthError, AuthEntities, ValidationError)
@ApiBadRequestResponse({
  schema: { allOf: refs(AuthError, ValidationError) },
})
@ApiTags('Auth')
@CheckAuthRole([AuthRole.User, AuthRole.Admin])
@Controller('/auth')
export class AuthController {
  constructor(
    @InjectPrismaClient(AUTH_FEATURE)
    private readonly prismaClient: PrismaClient,
    private readonly authCacheService: AuthCacheService,
    private readonly translatesStorage: TranslatesStorage
  ) {}

  @Get('profile')
  @ApiOkResponse({ type: AuthProfileDto })
  async profile(@CurrentAuthUser() authUser: AuthUser): Promise<AuthProfileDto> {
    return {
      lang: authUser.lang, // <--updates
      timezone: authUser.timezone,
    };
  }

  @Post('update-profile')
  @ApiOkResponse({ type: StatusResponse })
  async updateProfile(@CurrentAuthUser() authUser: AuthUser, @Body() args: AuthProfileDto, @InjectTranslateFunction() getText: TranslateFunction) {
    if (args.lang && !this.translatesStorage.locales.includes(args.lang)) {
      // <--updates
      throw new ValidationError(undefined, ValidationErrorEnum.COMMON, [
        {
          property: 'lang',
          constraints: {
            isNotEmpty: getText('lang must have one of the values: {{values}}', this.translatesStorage.locales.join(', ')),
          },
        },
      ]);
    }
    await this.prismaClient.authUser.update({
      where: { id: authUser.id },
      data: {
        ...(args.lang === undefined // <--updates
          ? {}
          : {
              lang: args.lang,
            }),
        ...(args.timezone === undefined // <--updates
          ? {}
          : {
              timezone: args.timezone,
            }),
        updatedAt: new Date(),
      },
    });
    await this.authCacheService.clearCacheByExternalUserId(authUser.externalUserId);
    return { message: getText('ok') };
  }
}

4. Adapting "AuthGuard" to get the user's language from the database

Now let's change the behavior of AuthGuard so that the user's language value is retrieved not from the frontend request, but from the settings stored in the database.

To do this, update the file libs/core/auth/src/lib/auth.guard.ts

// ...

@Injectable()
export class AuthGuard implements CanActivate {
  private logger = new Logger(AuthGuard.name);

  constructor(
    // ...
    private readonly translatesStorage: TranslatesStorage
  ) {}

  // ...

  private async tryGetOrCreateCurrentUserWithExternalUserId(req: AuthRequest, externalUserId: string) {
    if (!req.authUser && externalUserId) {
      const authUser = await this.authCacheService.getCachedUserByExternalUserId(externalUserId);
      req.authUser =
        authUser ||
        (await this.prismaClient.authUser.upsert({
          create: { externalUserId, userRole: 'User' },
          update: {},
          where: { externalUserId },
        }));

      if (req.authUser.lang) {
        req.headers[ACCEPT_LANGUAGE] = req.authUser.lang;
      }
    }

    if (req.headers[ACCEPT_LANGUAGE] && !this.translatesStorage.locales.includes(req.headers[ACCEPT_LANGUAGE])) {
      req.headers[ACCEPT_LANGUAGE] = this.translatesStorage.defaultLocale;
    }
  }
  // ...
}

5. Updating "SDK" for interaction with the backend

Now we need to recreate all SDKs that provide interaction with our server.

Commands

npm run manual:prepare

6. Developing a new test for the backend for changing and using the language from the database

To check the correctness of the functionality, we will create a special test scenario that will confirm that the change of language and its subsequent extraction from the database occur without errors.

Create the file apps/server-e2e/src/server/store-lang-in-db.spec.ts

import { RestClientHelper } from '@nestjs-mod-fullstack/testing';
import { AxiosError } from 'axios';

describe('Store lang in db', () => {
  jest.setTimeout(60000);

  const user1 = new RestClientHelper();

  beforeAll(async () => {
    await user1.createAndLoginAsUser();
  });

  it('should catch error on try use not exists language code', async () => {
    try {
      await user1.getAuthApi().authControllerUpdateProfile({ lang: 'tt' });
    } catch (err) {
      expect((err as AxiosError).response?.data).toEqual({
        code: 'VALIDATION-000',
        message: 'Validation error',
        metadata: [
          {
            property: 'lang',
            constraints: [
              {
                name: 'isWrongEnumValue',
                description: 'lang must have one of the values: en, ru',
              },
            ],
          },
        ],
      });
    }
  });

  it('should catch error in Russian language on create new webhook as user1', async () => {
    await user1.getAuthApi().authControllerUpdateProfile({ lang: 'ru' });
    try {
      await user1.getWebhookApi().webhookControllerCreateOne({
        enabled: false,
        endpoint: '',
        eventName: '',
      });
    } catch (err) {
      expect((err as AxiosError).response?.data).toEqual({
        code: 'VALIDATION-000',
        message: 'Validation error',
        metadata: [
          {
            property: 'eventName',
            constraints: [
              {
                name: 'isNotEmpty',
                description: 'eventName не может быть пустым',
              },
            ],
          },
          {
            property: 'endpoint',
            constraints: [
              {
                name: 'isNotEmpty',
                description: 'endpoint не может быть пустым',
              },
            ],
          },
        ],
      });
    }
  });
});

7. Running all server "E2E" tests

Let's run all E2E level tests for the server to make sure that all functionality works correctly and without failures.

Commands

npm run nx -- run server-e2e:e2e

8. Creating a service to manage the user's active language in the frontend

In the frontend application, we will create a service that will manage the active language for both authorized and unauthorized users.

The logic for working with the active language for unauthorized users will remain the same: it will use localStorage.

However, after authorization, the active language will be saved in the user profile.

Create the file libs/core/auth-angular/src/lib/services/auth-active-lang.service.ts

import { Injectable } from '@angular/core';
import { TranslocoService } from '@jsverse/transloco';
import { AuthErrorEnumInterface, AuthErrorInterface, AuthRestService } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { catchError, map, of, tap, throwError } from 'rxjs';

const AUTH_ACTIVE_LANG_LOCAL_STORAGE_KEY = 'activeLang';

@Injectable({ providedIn: 'root' })
export class AuthActiveLangService {
  constructor(private readonly authRestService: AuthRestService, private readonly translocoService: TranslocoService) {}

  getActiveLang() {
    return this.authRestService.authControllerProfile().pipe(
      map((profile) => {
        return profile.lang || this.translocoService.getDefaultLang();
      }),
      catchError((err) => {
        if ('error' in err && (err.error as AuthErrorInterface).code === AuthErrorEnumInterface._001) {
          return of(localStorage.getItem(AUTH_ACTIVE_LANG_LOCAL_STORAGE_KEY) || this.translocoService.getDefaultLang());
        }
        return throwError(() => err);
      })
    );
  }

  setActiveLang(lang: string) {
    return this.authRestService.authControllerUpdateProfile({ lang }).pipe(
      tap(() => {
        this.translocoService.setActiveLang(lang);
      }),
      catchError((err) => {
        if ('error' in err && (err.error as AuthErrorInterface).code === AuthErrorEnumInterface._001) {
          localStorage.setItem(AUTH_ACTIVE_LANG_LOCAL_STORAGE_KEY, lang);
          this.translocoService.setActiveLang(lang);
          return of(null);
        }
        return throwError(() => err);
      })
    );
  }
}

Now let's replace all usages of localStorage for storing language with AuthActiveLangService throughout the frontend code.

9. Developing a new frontend test for changing and using language from the database

As part of the test, we will perform the following steps: register, change the language to Russian, then change the language in localStorage from Russian to English and try to create a new webhook with empty fields. The expected result is getting a validation error in Russian.

Create a file apps/client-e2e/src/ru-validation-with-store-lang-in-db.spec.ts

import { faker } from '@faker-js/faker';
import { expect, Page, test } from '@playwright/test';
import { get } from 'env-var';
import { join } from 'path';
import { setTimeout } from 'timers/promises';

test.describe('Validation with store lang in db (ru)', () => {
  test.describe.configure({ mode: 'serial' });

  const user = {
    email: faker.internet.email({
      provider: 'example.fakerjs.dev',
    }),
    password: faker.internet.password({ length: 8 }),
    site: `http://${faker.internet.domainName()}`,
  };
  let page: Page;

  test.beforeAll(async ({ browser }) => {
    page = await browser.newPage({
      viewport: { width: 1920, height: 1080 },
      recordVideo: {
        dir: join(__dirname, 'video'),
        size: { width: 1920, height: 1080 },
      },
    });
    await page.goto('/', {
      timeout: 7000,
    });
    await page.evaluate((authorizerURL) => localStorage.setItem('authorizerURL', authorizerURL), get('SERVER_AUTHORIZER_URL').required().asString());
    await page.evaluate((minioURL) => localStorage.setItem('minioURL', minioURL), get('SERVER_MINIO_URL').required().asString());
  });

  test.afterAll(async () => {
    await setTimeout(1000);
    await page.close();
  });

  test('sign up as user', async () => {
    await page.goto('/sign-up', {
      timeout: 7000,
    });

    await page.locator('auth-sign-up-form').locator('[placeholder=email]').click();
    await page.keyboard.type(user.email.toLowerCase(), {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=email]')).toHaveValue(user.email.toLowerCase());

    await page.locator('auth-sign-up-form').locator('[placeholder=password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=password]')).toHaveValue(user.password);

    await page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]')).toHaveValue(user.password);

    await expect(page.locator('auth-sign-up-form').locator('button[type=submit]')).toHaveText('Sign-up');

    await page.locator('auth-sign-up-form').locator('button[type=submit]').click();

    await setTimeout(5000);

    await expect(page.locator('nz-header').locator('[nz-submenu]').first()).toContainText(`You are logged in as ${user.email.toLowerCase()}`);
  });

  test('should change language to RU', async () => {
    await expect(page.locator('nz-header').locator('[nz-submenu]').last()).toContainText(`EN`);
    await page.locator('nz-header').locator('[nz-submenu]').last().click();

    await expect(page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').last()).toContainText(`Russian`);

    await page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').last().click();

    await setTimeout(4000);
    //

    await expect(page.locator('nz-header').locator('[nz-submenu]').last()).toContainText(`RU`);
  });

  test('change lang to en in localStorage', async () => {
    await page.evaluate(() => localStorage.setItem('activeLang', 'en'));

    const activeLang = await page.evaluate(() => localStorage.getItem('activeLang'));

    expect(activeLang).toEqual('en');
  });

  test('should catch error on create new webhook', async () => {
    await page.locator('webhook-grid').locator('button').first().click();

    await setTimeout(7000);

    await page.locator('[nz-modal-footer]').locator('button').last().click();

    await setTimeout(4000);

    await expect(page.locator('webhook-form').locator('formly-validation-message').first()).toContainText('поле "адрес" не может быть пустым');
    await expect(page.locator('webhook-form').locator('formly-validation-message').last()).toContainText('поле "событие" не может быть пустым');
  });
});

10. Run all "E2E" level tests for both server and client

Let's run all E2E level tests for both server and client to make sure all functionality works correctly and without errors.

Commands

npm run pm2-full:dev:test:e2e

Conclusion

Despite the apparent simplicity of the task, its solution required a significant amount of time and writing a considerable amount of code.

However, even for such minimal changes it is extremely important to ensure E2E test coverage, which was demonstrated in this post.

Plans

In the previous article, I implemented the function of automatic conversion of output data containing fields of type Date or strings in ISOString format. However, I have not yet implemented automatic conversion of input data. In the next post, I will deal with this issue.

Timezone support in a full-stack application based on NestJS and Angular: working with REST and WebSockets

Ilshat Khamitov — Thu, 12 Dec 2024 20:39:18 +0000

In this article, I would like to share my experience in implementing timezone support in a full stack application built on NestJS and Angular. We will learn how to save user time zone settings in the database and use them correctly when interacting with the server via REST and web sockets.

1. Install all necessary libraries

Install the date-fns library, which is necessary for working with dates and time zones.

Commands

npm install --save date-fns

2. Adding support for Prisma and Flyway migrations to the authorization module

Let's include the Prisma and Flyway modules in the main.ts file to set up interaction with the new Auth database.

Update the file apps/server/src/main.ts

import { AUTH_FEATURE, AUTH_FOLDER, AuthModule } from '@nestjs-mod-fullstack/auth';
// ...

bootstrapNestApplication({
  modules: {
    // ...
    core: [
      // ...
      PrismaModule.forRoot({
        contextName: AUTH_FEATURE,
        staticConfiguration: {
          featureName: AUTH_FEATURE,
          schemaFile: join(rootFolder, AUTH_FOLDER, 'src', 'prisma', PRISMA_SCHEMA_FILE),
          prismaModule: isInfrastructureMode() ? import(`@nestjs-mod/prisma`) : import(`@nestjs-mod/prisma`),
          addMigrationScripts: false,
          nxProjectJsonFile: join(rootFolder, AUTH_FOLDER, PROJECT_JSON_FILE),
        },
      }),
    ],
    infrastructure: [
      // ...
      DockerComposePostgreSQL.forFeatureAsync({
        featureModuleName: AUTH_FEATURE,
        featureConfiguration: {
          nxProjectJsonFile: join(rootFolder, AUTH_FOLDER, PROJECT_JSON_FILE),
        },
      }),
      Flyway.forRoot({
        staticConfiguration: {
          featureName: AUTH_FEATURE,
          migrationsFolder: join(rootFolder, AUTH_FOLDER, 'src', 'migrations'),
          configFile: join(rootFolder, FLYWAY_JS_CONFIG_FILE),
          nxProjectJsonFile: join(rootFolder, AUTH_FOLDER, PROJECT_JSON_FILE),
        },
      }),
    ],
  },
});

We generate additional code for the infrastructure.

Commands

npm run docs:infrastructure

Add a new environment variable with login and password to connect to the new database.

Update the .env and example.env files

SERVER_AUTH_DATABASE_URL=postgres://auth:auth_password@localhost:5432/auth?schema=public

3. Creating a table to store the user's time zone

I chose to use the Auth authorization module to store data about user time zones, due to the architectural features of our project. In other situations, we could consider creating a separate field in the Accounts database or even a special TimezoneModule module to manage time zone-related tasks.

Now let's create a migration to generate all the necessary tables in the Auth database.

Commands

# Create migrations folder
mkdir -p ./libs/core/auth/src/migrations

# Create empty migration
npm run flyway:create:auth --args=Init

We fill the migration file with SQL scripts to create the necessary tables and indexes.

Update the file libs/core/auth/src/migrations/V202412071217__Init.sql

DO $$
BEGIN
    CREATE TYPE "AuthRole" AS enum(
        'Admin',
        'User'
);
EXCEPTION
    WHEN duplicate_object THEN
        NULL;
END
$$;

CREATE TABLE IF NOT EXISTS "AuthUser"(
    "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
    "externalUserId" uuid NOT NULL,
    "userRole" "AuthRole" NOT NULL,
    "timezone" double precision,
    "createdAt" timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" timestamp(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT "PK_AUTH_USER" PRIMARY KEY ("id")
);

CREATE UNIQUE INDEX IF NOT EXISTS "UQ_AUTH_USER" ON "AuthUser"("externalUserId");

CREATE INDEX IF NOT EXISTS "IDX_AUTH_USER__USER_ROLE" ON "AuthUser"("userRole");

Now the Auth database will contain the AuthUser table, which will store information about the time zone of each user.

Apply the created migrations and recreate the Prisma schemas for all databases.

Commands

npm run docker-compose:start-prod:server
npm run db:create-and-fill
npm run prisma:pull

Schema file for the new database libs/core/auth/src/prisma/schema.prisma

generator client {
  provider   = "prisma-client-js"
  output     = "../../../../../node_modules/@prisma/auth-client"
  engineType = "binary"
}

datasource db {
  provider = "postgresql"
  url      = env("SERVER_AUTH_DATABASE_URL")
}

model AuthUser {
  id             String   @id(map: "PK_AUTH_USER") @default(dbgenerated("uuid_generate_v4()")) @db.Uuid
  externalUserId String   @unique(map: "UQ_AUTH_USER") @db.Uuid
  userRole       AuthRole
  timezone       Float?
  createdAt      DateTime @default(now()) @db.Timestamp(6)
  updatedAt      DateTime @default(now()) @db.Timestamp(6)

  @@index([userRole], map: "IDX_AUTH_USER__USER_ROLE")
}

model migrations {
  installed_rank Int      @id(map: "__migrations_pk")
  version        String?  @db.VarChar(50)
  description    String   @db.VarChar(200)
  type           String   @db.VarChar(20)
  script         String   @db.VarChar(1000)
  checksum       Int?
  installed_by   String   @db.VarChar(100)
  installed_on   DateTime @default(now()) @db.Timestamp(6)
  execution_time Int
  success        Boolean

  @@index([success], map: "__migrations_s_idx")
  @@map("__migrations")
}

enum AuthRole {
  Admin
  User
}

4. Generating "DTO" for the new "Auth" database

Connecting the DTO generator to the Prisma schema and excluding some fields from the generation process.

Update the file libs/core/auth/src/prisma/schema.prisma

// ...

generator prismaClassGenerator {
  provider                        = "prisma-generator-nestjs-dto"
  output                          = "../lib/generated/rest/dto"
  updateDtoPrefix                 = "Update"
  entityPrefix                    = ""
  entitySuffix                    = ""
  definiteAssignmentAssertion     = "true"
  flatResourceStructure           = "false"
  exportRelationModifierClasses   = "true"
  fileNamingStyle                 = "kebab"
  createDtoPrefix                 = "Create"
  classValidation                 = "true"
  noDependencies                  = "false"
  outputToNestJsResourceStructure = "false"
  annotateAllDtoProperties        = "true"
  dtoSuffix                       = "Dto"
  reExport                        = "false"
  prettier                        = "true"
}
// ...

model AuthUser {
  id             String   @id(map: "PK_AUTH_USER") @default(dbgenerated("uuid_generate_v4()")) @db.Uuid
  externalUserId String   @unique(map: "UQ_AUTH_USER") @db.Uuid
  userRole       AuthRole
  timezone       Float?
  /// @DtoCreateHidden
  /// @DtoUpdateHidden
  createdAt      DateTime @default(now()) @db.Timestamp(6)
  /// @DtoCreateHidden
  /// @DtoUpdateHidden
  updatedAt      DateTime @default(now()) @db.Timestamp(6)

  @@index([userRole], map: "IDX_AUTH_USER__USER_ROLE")
}
// ...

We restart generators for all databases.

Commands

npm run prisma:generate

After the command has successfully completed, we get new files in the libs/core/auth/src/lib/generated/rest/dto folder:

auth-user.dto.ts
connect-auth-user.dto.ts
create-auth-user.dto.ts
migrations.dto.ts
update-auth-user.dto.ts
auth-user.entity.ts
connect-migrations.dto.ts
create-migrations.dto.ts
migrations.entity.ts
update-migrations.dto.ts

Since the generated files may contain formatting errors that eslint detects, we exclude these files from eslint checking.

Updating .eslintignore files

...
libs/core/auth/src/lib/generated/rest/dto

5. Updating the "PrismaModule" module import parameters for the "Auth" database

Changing the PrismaModule module import configuration for the Auth database to accommodate new requirements for interacting with the database.

Update the file apps/server/src/main.ts

// ...

bootstrapNestApplication({
  modules: {
    // ...
    core: [
      // ...
      PrismaModule.forRoot({
        contextName: AUTH_FEATURE,
        staticConfiguration: {
          featureName: AUTH_FEATURE,
          schemaFile: join(rootFolder, AUTH_FOLDER, 'src', 'prisma', PRISMA_SCHEMA_FILE),
          prismaModule: isInfrastructureMode() ? import(`@nestjs-mod/prisma`) : import(`@prisma/auth-client`),
          addMigrationScripts: false,
          nxProjectJsonFile: join(rootFolder, AUTH_FOLDER, PROJECT_JSON_FILE),
        },
      }),
    ],
    // ...
  },
});

6. Create a caching service for "Auth" database users

Create a service for caching Auth database users to speed up access to data from the AuthGuard and AuthTimezoneInterceptor services.

Create a file libs\core\auth\src\lib\services\auth-cache.service.ts

import { CacheManagerService } from '@nestjs-mod/cache-manager';
import { InjectPrismaClient } from '@nestjs-mod/prisma';
import { Injectable } from '@nestjs/common';
import { AuthUser, PrismaClient } from '@prisma/auth-client';
import { AUTH_FEATURE } from '../auth.constants';
import { AuthEnvironments } from '../auth.environments';

@Injectable()
export class AuthCacheService {
  constructor(
    @InjectPrismaClient(AUTH_FEATURE)
    private readonly prismaClient: PrismaClient,
    private readonly cacheManagerService: CacheManagerService,
    private readonly authEnvironments: AuthEnvironments
  ) {}

  async clearCacheByExternalUserId(externalUserId: string) {
    const authUsers = await this.prismaClient.authUser.findMany({
      where: { externalUserId },
    });
    for (const authUser of authUsers) {
      await this.cacheManagerService.del(this.getUserCacheKey(authUser));
    }
  }

  async getCachedUserByExternalUserId(externalUserId: string) {
    const cached = await this.cacheManagerService.get<AuthUser | null>(
      this.getUserCacheKey({
        externalUserId,
      })
    );
    if (cached) {
      return cached;
    }
    const user = await this.prismaClient.authUser.findFirst({
      where: {
        externalUserId,
      },
    });
    if (user) {
      await this.cacheManagerService.set(this.getUserCacheKey({ externalUserId }), user, this.authEnvironments.cacheTTL);
      return user;
    }
    return null;
  }

  private getUserCacheKey({ externalUserId }: { externalUserId: string }): string {
    return `authUser.${externalUserId}`;
  }
}

7. Developing a controller for working with user time zone information

Let's create a controller that will be responsible for receiving the user's current time zone settings and updating these parameters when necessary.

Create a file libs/core/auth/src/lib/controllers/auth.controller.ts

import { StatusResponse } from '@nestjs-mod-fullstack/common';
import { ValidationError } from '@nestjs-mod-fullstack/validation';
import { InjectPrismaClient } from '@nestjs-mod/prisma';
import { Body, Controller, Get, Post } from '@nestjs/common';
import { ApiBadRequestResponse, ApiExtraModels, ApiOkResponse, ApiTags, refs } from '@nestjs/swagger';
import { AuthRole, PrismaClient } from '@prisma/auth-client';
import { InjectTranslateFunction, TranslateFunction } from 'nestjs-translates';
import { AUTH_FEATURE } from '../auth.constants';
import { CheckAuthRole, CurrentAuthUser } from '../auth.decorators';
import { AuthError } from '../auth.errors';
import { AuthUser } from '../generated/rest/dto/auth-user.entity';
import { AuthEntities } from '../types/auth-entities';
import { AuthProfileDto } from '../types/auth-profile.dto';
import { AuthCacheService } from '../services/auth-cache.service';

@ApiExtraModels(AuthError, AuthEntities, ValidationError)
@ApiBadRequestResponse({
  schema: { allOf: refs(AuthError, ValidationError) },
})
@ApiTags('Auth')
@CheckAuthRole([AuthRole.User, AuthRole.Admin])
@Controller('/auth')
export class AuthController {
  constructor(
    @InjectPrismaClient(AUTH_FEATURE)
    private readonly prismaClient: PrismaClient,
    private readonly authCacheService: AuthCacheService
  ) {}

  @Get('profile')
  @ApiOkResponse({ type: AuthProfileDto })
  async profile(@CurrentAuthUser() authUser: AuthUser): Promise<AuthProfileDto> {
    return { timezone: authUser.timezone };
  }

  @Post('update-profile')
  @ApiOkResponse({ type: StatusResponse })
  async updateProfile(@CurrentAuthUser() authUser: AuthUser, @Body() args: AuthProfileDto, @InjectTranslateFunction() getText: TranslateFunction) {
    await this.prismaClient.authUser.update({
      where: { id: authUser.id },
      data: {
        timezone: args.timezone,
        updatedAt: new Date(),
      },
    });
    await this.authCacheService.clearCacheByExternalUserId(authUser.externalUserId);
    return { message: getText('ok') };
  }
}

8. Create a service for recursive conversion of "Date" type fields to a specified time zone

We will develop a service that will perform a recursive conversion of "Date" type fields to a specified time zone.

Create a file libs/core/auth/src/lib/services/auth-timezone.service.ts

import { Injectable, Logger } from '@nestjs/common';
import { addHours } from 'date-fns';

export type TObject = Record<string, unknown>;

export type TData = unknown | unknown[] | TObject | TObject[];

@Injectable()
export class AuthTimezoneService {
  private logger = new Logger(AuthTimezoneService.name);

  convertObject(data: TData, timezone: number | null | undefined, depth = 10): TData {
    if (depth === 0) {
      return data;
    }
    if (Array.isArray(data)) {
      const newArray: unknown[] = [];
      for (const item of data) {
        newArray.push(this.convertObject(item, timezone, depth - 1));
      }
      return newArray;
    }
    if ((typeof data === 'string' || typeof data === 'number' || typeof data === 'function') && !this.isValidStringDate(data) && !this.isValidDate(data)) {
      return data;
    }
    try {
      if (data && timezone) {
        if (this.isValidStringDate(data) || this.isValidDate(data)) {
          if (this.isValidStringDate(data) && typeof data === 'string') {
            data = new Date(data);
          }
          data = addHours(data as Date, timezone);
        } else {
          const keys = Object.keys(data);
          for (const key of keys) {
            (data as TObject)[key] = this.convertObject((data as TObject)[key], timezone, depth - 1);
          }
        }
      }
    } catch (err: unknown) {
      if (err instanceof Error) {
        this.logger.error(err, err.stack);
      }
    }
    return data;
  }

  private isValidStringDate(data: string | number | unknown) {
    return typeof data === 'string' && data.length === '0000-00-00T00:00:00.000Z'.length && !isNaN(+new Date(data));
  }

  private isValidDate(data: string | number | Date | object | unknown) {
    if (data && typeof data === 'object') {
      return !isNaN(+data);
    }
    return typeof data === 'string' && !isNaN(+new Date(data));
  }
}

9. Adding an interceptor for automatic time correction in data

Let's create an interceptor that will automatically convert time values in data according to the time zone selected by the user. This will ensure that dates and times are displayed correctly in the user interface.

Create a file libs/core/auth/src/lib/interceptors/auth-timezone.interceptor.ts

import { getRequestFromExecutionContext } from '@nestjs-mod/common';
import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { isObservable, Observable } from 'rxjs';
import { concatMap } from 'rxjs/operators';
import { AuthCacheService } from '../services/auth-cache.service';
import { AuthTimezoneService, TData } from '../services/auth-timezone.service';
import { AuthRequest } from '../types/auth-request';
import { AuthEnvironments } from '../auth.environments';

@Injectable()
export class AuthTimezoneInterceptor implements NestInterceptor<TData, TData> {
  constructor(private readonly authTimezoneService: AuthTimezoneService, private readonly authCacheService: AuthCacheService, private readonly authEnvironments: AuthEnvironments) {}

  intercept(context: ExecutionContext, next: CallHandler) {
    const result = next.handle();

    if (!this.authEnvironments.useInterceptors) {
      return result;
    }

    const req: AuthRequest = getRequestFromExecutionContext(context);
    const userId = req.authUser?.externalUserId;

    if (!userId) {
      return result;
    }

    if (isObservable(result)) {
      return result.pipe(
        concatMap(async (data) => {
          const user = await this.authCacheService.getCachedUserByExternalUserId(userId);
          return this.authTimezoneService.convertObject(data, user?.timezone);
        })
      );
    }
    if (result instanceof Promise && typeof result?.then === 'function') {
      return result.then(async (data) => {
        if (isObservable(result)) {
          return result.pipe(
            concatMap(async (data) => {
              const user = await this.authCacheService.getCachedUserByExternalUserId(userId);
              return this.authTimezoneService.convertObject(data, user?.timezone);
            })
          );
        } else {
          const user = await this.authCacheService.getCachedUserByExternalUserId(userId);
          // need for correct map types with base method of NestInterceptor
          return this.authTimezoneService.convertObject(data, user?.timezone) as Observable<TData>;
        }
      });
    }
    // need for correct map types with base method of NestInterceptor
    return this.authTimezoneService.convertObject(result, req.authUser?.timezone) as Observable<TData>;
  }
}

10. Adding "AuthGuard" to automatically create users in the "Auth" database

Integrating AuthGuard so that users can automatically register in the Auth database when working with the system.

Create a file libs/core/auth/src/lib/auth.module.ts

import { AllowEmptyUser } from '@nestjs-mod/authorizer';
import { getRequestFromExecutionContext } from '@nestjs-mod/common';
import { InjectPrismaClient } from '@nestjs-mod/prisma';
import { CanActivate, ExecutionContext, Injectable, Logger } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { AuthRole, PrismaClient } from '@prisma/auth-client';
import { AUTH_FEATURE } from './auth.constants';
import { CheckAuthRole, SkipAuthGuard } from './auth.decorators';
import { AuthError, AuthErrorEnum } from './auth.errors';
import { AuthCacheService } from './services/auth-cache.service';
import { AuthRequest } from './types/auth-request';
import { AuthEnvironments } from './auth.environments';

@Injectable()
export class AuthGuard implements CanActivate {
  private logger = new Logger(AuthGuard.name);

  constructor(
    @InjectPrismaClient(AUTH_FEATURE)
    private readonly prismaClient: PrismaClient,
    private readonly reflector: Reflector,
    private readonly authCacheService: AuthCacheService,
    private readonly authEnvironments: AuthEnvironments
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    if (!this.authEnvironments.useGuards) {
      return true;
    }

    try {
      const { skipAuthGuard, checkAuthRole, allowEmptyUserMetadata } = this.getHandlersReflectMetadata(context);

      if (skipAuthGuard) {
        return true;
      }

      const req: AuthRequest = this.getRequestFromExecutionContext(context);

      if (req.authorizerUser?.id) {
        await this.tryGetOrCreateCurrentUserWithExternalUserId(req, req.authorizerUser.id);
      }

      this.throwErrorIfCurrentUserNotSet(req, allowEmptyUserMetadata);

      this.throwErrorIfCurrentUserNotHaveNeededRoles(checkAuthRole, req);
    } catch (err) {
      this.logger.error(err, (err as Error).stack);
      throw err;
    }
    return true;
  }

  private throwErrorIfCurrentUserNotHaveNeededRoles(checkAuthRole: AuthRole[] | undefined, req: AuthRequest) {
    if (checkAuthRole && req.authUser && !checkAuthRole?.includes(req.authUser.userRole)) {
      throw new AuthError(AuthErrorEnum.FORBIDDEN);
    }
  }

  private throwErrorIfCurrentUserNotSet(req: AuthRequest, allowEmptyUserMetadata?: boolean) {
    if (!req.skippedByAuthorizer && !req.authUser && !allowEmptyUserMetadata) {
      throw new AuthError(AuthErrorEnum.USER_NOT_FOUND);
    }
  }

  private async tryGetOrCreateCurrentUserWithExternalUserId(req: AuthRequest, externalUserId: string) {
    if (!req.authUser && externalUserId) {
      const authUser = await this.authCacheService.getCachedUserByExternalUserId(externalUserId);
      req.authUser =
        authUser ||
        (await this.prismaClient.authUser.upsert({
          create: { externalUserId, userRole: 'User' },
          update: {},
          where: { externalUserId },
        }));
    }
  }

  private getRequestFromExecutionContext(context: ExecutionContext) {
    const req = getRequestFromExecutionContext(context) as AuthRequest;
    req.headers = req.headers || {};
    return req;
  }

  private getHandlersReflectMetadata(context: ExecutionContext) {
    const allowEmptyUserMetadata = Boolean((typeof context.getHandler === 'function' && this.reflector.get(AllowEmptyUser, context.getHandler())) || (typeof context.getClass === 'function' && this.reflector.get(AllowEmptyUser, context.getClass())) || undefined);

    const skipAuthGuard = (typeof context.getHandler === 'function' && this.reflector.get(SkipAuthGuard, context.getHandler())) || (typeof context.getClass === 'function' && this.reflector.get(SkipAuthGuard, context.getClass())) || undefined;

    const checkAuthRole = (typeof context.getHandler === 'function' && this.reflector.get(CheckAuthRole, context.getHandler())) || (typeof context.getClass === 'function' && this.reflector.get(CheckAuthRole, context.getClass())) || undefined;
    return { allowEmptyUserMetadata, skipAuthGuard, checkAuthRole };
  }
}

11. Registering the created classes in "AuthModule"

Let's register all the created classes in the AuthModule module so that they become available for use in our application.

Update the file libs/core/auth/src/lib/auth.module.ts

import { AuthorizerGuard, AuthorizerModule } from '@nestjs-mod/authorizer';
import { createNestModule, getFeatureDotEnvPropertyNameFormatter, NestModuleCategory } from '@nestjs-mod/common';
import { PrismaModule } from '@nestjs-mod/prisma';
import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
import { AUTH_FEATURE, AUTH_MODULE } from './auth.constants';
import { AuthEnvironments } from './auth.environments';
import { AuthExceptionsFilter } from './auth.filter';
import { AuthGuard } from './auth.guard';
import { AuthController } from './controllers/auth.controller';
import { AuthorizerController } from './controllers/authorizer.controller';
import { AuthTimezoneInterceptor } from './interceptors/auth-timezone.interceptor';
import { AuthAuthorizerBootstrapService } from './services/auth-authorizer-bootstrap.service';
import { AuthAuthorizerService } from './services/auth-authorizer.service';
import { AuthTimezoneService } from './services/auth-timezone.service';
import { CacheManagerModule } from '@nestjs-mod/cache-manager';
import { AuthCacheService } from './services/auth-cache.service';

export const { AuthModule } = createNestModule({
  moduleName: AUTH_MODULE,
  moduleCategory: NestModuleCategory.feature,
  staticEnvironmentsModel: AuthEnvironments,
  imports: [
    AuthorizerModule.forFeature({
      featureModuleName: AUTH_FEATURE,
    }),
    PrismaModule.forFeature({
      contextName: AUTH_FEATURE,
      featureModuleName: AUTH_FEATURE,
    }),
    CacheManagerModule.forFeature({
      featureModuleName: AUTH_FEATURE,
    }),
  ],
  controllers: [AuthorizerController, AuthController],
  sharedImports: [
    PrismaModule.forFeature({
      contextName: AUTH_FEATURE,
      featureModuleName: AUTH_FEATURE,
    }),
    CacheManagerModule.forFeature({
      featureModuleName: AUTH_FEATURE,
    }),
  ],
  sharedProviders: [AuthTimezoneService, AuthCacheService],
  providers: [{ provide: APP_GUARD, useClass: AuthorizerGuard }, { provide: APP_GUARD, useClass: AuthGuard }, { provide: APP_FILTER, useClass: AuthExceptionsFilter }, { provide: APP_INTERCEPTOR, useClass: AuthTimezoneInterceptor }, AuthAuthorizerService, AuthAuthorizerBootstrapService],
  wrapForRootAsync: (asyncModuleOptions) => {
    if (!asyncModuleOptions) {
      asyncModuleOptions = {};
    }
    const FomatterClass = getFeatureDotEnvPropertyNameFormatter(AUTH_FEATURE);
    Object.assign(asyncModuleOptions, {
      environmentsOptions: {
        propertyNameFormatters: [new FomatterClass()],
        name: AUTH_FEATURE,
      },
    });

    return { asyncModuleOptions };
  },
});

12. Setting up request processing via the "WebSocket" gateway

Although we declared global guard and interceptor in the AuthModule module, they will not be automatically applied to request processing via the "WebSocket" gateway. Therefore, to process requests via the gateway, we will create a special decorator and apply it to the TimeController controller.

Create a file libs/core/auth/src/lib/auth.decorators.ts

import { getRequestFromExecutionContext } from '@nestjs-mod/common';
import { createParamDecorator, ExecutionContext, UseGuards, UseInterceptors } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { AuthRole } from '@prisma/auth-client';
import { AuthRequest } from './types/auth-request';

import { AllowEmptyUser, AuthorizerGuard } from '@nestjs-mod/authorizer';
import { applyDecorators } from '@nestjs/common';
import { AuthGuard } from './auth.guard';
import { AuthTimezoneInterceptor } from './interceptors/auth-timezone.interceptor';

export const SkipAuthGuard = Reflector.createDecorator<true>();
export const CheckAuthRole = Reflector.createDecorator<AuthRole[]>();

export const CurrentAuthRequest = createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
  const req = getRequestFromExecutionContext(ctx) as AuthRequest;
  return req;
});

export const CurrentAuthUser = createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
  const req = getRequestFromExecutionContext(ctx) as AuthRequest;
  return req.authUser;
});

function AddHandleConnection() {
  // eslint-disable-next-line @typescript-eslint/ban-types
  return function (constructor: Function) {
    constructor.prototype.handleConnection = function (
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      client: any,
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      ...args: any[]
    ) {
      const authorizationHeader = args[0]?.headers.authorization;
      const queryToken = args[0]?.url?.split('token=')?.[1];
      client.headers = {
        authorization: authorizationHeader || queryToken ? `Bearer ${queryToken}` : '',
      };
    };
  };
}

export function UseAuthInterceptorsAndGuards(options?: { allowEmptyUser?: boolean }) {
  return applyDecorators(UseInterceptors(AuthTimezoneInterceptor), UseGuards(AuthorizerGuard, AuthGuard), AddHandleConnection(), ...(options?.allowEmptyUser ? [AllowEmptyUser()] : []));
}

Update the file apps/server/src/app/time.controller.ts

import { UseAuthInterceptorsAndGuards } from '@nestjs-mod-fullstack/auth';
import { Controller, Get } from '@nestjs/common';

import { ApiOkResponse } from '@nestjs/swagger';
import { SubscribeMessage, WebSocketGateway, WsResponse } from '@nestjs/websockets';
import { interval, map, Observable } from 'rxjs';

export const ChangeTimeStream = 'ChangeTimeStream';

@UseAuthInterceptorsAndGuards({ allowEmptyUser: true })
@WebSocketGateway({
  cors: {
    origin: '*',
  },
  path: '/ws/time',
  transports: ['websocket'],
})
@Controller()
export class TimeController {
  @Get('/time')
  @ApiOkResponse({ type: Date })
  time() {
    return new Date();
  }

  @SubscribeMessage(ChangeTimeStream)
  onChangeTimeStream(): Observable<WsResponse<Date>> {
    return interval(1000).pipe(
      map(() => ({
        data: new Date(),
        event: ChangeTimeStream,
      }))
    );
  }
}

13. Create a new "e2e" test to check the correctness of the conversion of fields of the "Date" type.

Let's create a new e2e test that checks the correctness of the conversion of fields of the Date type to different time zones.

Update the file apps/server-e2e/src/server/timezone-time.spec.ts

import { RestClientHelper } from '@nestjs-mod-fullstack/testing';
import { isDateString } from 'class-validator';
import { get } from 'env-var';
import { lastValueFrom, take, toArray } from 'rxjs';

describe('Get server time from rest api and ws (timezone)', () => {
  jest.setTimeout(60000);

  const correctStringDateLength = '0000-00-00T00:00:00.000Z'.length;
  const restClientHelper = new RestClientHelper({
    serverUrl: process.env.IS_DOCKER_COMPOSE ? get('CLIENT_URL').asString() : undefined,
  });

  beforeAll(async () => {
    await restClientHelper.createAndLoginAsUser();
  });

  it('should return time from rest api in two different time zones', async () => {
    const time = await restClientHelper.getTimeApi().timeControllerTime();

    expect(time.status).toBe(200);
    expect(time.data).toHaveLength(correctStringDateLength);
    expect(isDateString(time.data)).toBeTruthy();

    await restClientHelper.getAuthApi().authControllerUpdateProfile({ timezone: -3 });

    const time2 = await restClientHelper.getTimeApi().timeControllerTime();

    expect(time2.status).toBe(200);
    expect(time2.data).toHaveLength(correctStringDateLength);
    expect(isDateString(time2.data)).toBeTruthy();

    expect(+new Date(time.data as unknown as string) - +new Date(time2.data as unknown as string)).toBeGreaterThanOrEqual(3 * 60 * 1000);
  });

  it('should return time from ws in two different time zones', async () => {
    await restClientHelper.getAuthApi().authControllerUpdateProfile({ timezone: null });

    const last3ChangeTimeEvents = await lastValueFrom(
      restClientHelper
        .webSocket<string>({
          path: `/ws/time?token=${restClientHelper.authorizationTokens?.access_token}`,
          eventName: 'ChangeTimeStream',
        })
        .pipe(take(3), toArray())
    );

    expect(last3ChangeTimeEvents).toHaveLength(3);

    await restClientHelper.getAuthApi().authControllerUpdateProfile({ timezone: -3 });

    const newLast3ChangeTimeEvents = await lastValueFrom(
      restClientHelper
        .webSocket<string>({
          path: `/ws/time?token=${restClientHelper.authorizationTokens?.access_token}`,
          eventName: 'ChangeTimeStream',
        })
        .pipe(take(3), toArray())
    );

    expect(newLast3ChangeTimeEvents).toHaveLength(3);

    expect(+new Date(last3ChangeTimeEvents[0].data as unknown as string) - +new Date(newLast3ChangeTimeEvents[0].data as unknown as string)).toBeGreaterThanOrEqual(3 * 60 * 1000);
    expect(+new Date(last3ChangeTimeEvents[1].data as unknown as string) - +new Date(newLast3ChangeTimeEvents[1].data as unknown as string)).toBeGreaterThanOrEqual(3 * 60 * 1000);
    expect(+new Date(last3ChangeTimeEvents[2].data as unknown as string) - +new Date(newLast3ChangeTimeEvents[2].data as unknown as string)).toBeGreaterThanOrEqual(3 * 60 * 1000);
  });
});

14. We restart the infrastructure and all applications, check the correctness of the execution of e2e tests

Commands

npm run pm2-full:dev:stop
npm run pm2-full:dev:start
npm run pm2-full:dev:test:e2e

15. Passing an authorization token for websockets via a "query" line

We pass the authorization token for websockets through the request parameter to provide user authentication when using websockets.

Update the file apps/client/src/app/app.component.ts

// ...
import { AuthService, TokensService } from '@nestjs-mod-fullstack/auth-angular';

@UntilDestroy()
@Component({
  standalone: true,
  imports: [RouterModule, NzMenuModule, NzLayoutModule, NzTypographyModule, AsyncPipe, NgForOf, NgFor, TranslocoPipe, TranslocoDirective],
  selector: 'app-root',
  templateUrl: './app.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AppComponent implements OnInit {
  // ...

  constructor(
    // ...
    private readonly tokensService: TokensService
  ) {}

  // ...

  private fillServerTime() {
    return merge(
      this.timeRestService.timeControllerTime(),
      merge(of(this.tokensService.tokens$.value), this.tokensService.tokens$.asObservable())
        .pipe(
          switchMap((token) =>
            webSocket<string>({
              address: this.timeRestService.configuration.basePath + (token?.access_token ? `/ws/time?token=${token?.access_token}` : '/ws/time'),
              eventName: 'ChangeTimeStream',
            })
          )
        )
        .pipe(map((result) => result.data))
    ).pipe(tap((result) => this.serverTime$.next(result as string)));
  }
}

16.Replacing the original profile form fields and changing the profile update method

A lot of the changes on the frontend were made in this post, and while I won't cover every detail, it's important to note that working with forms has been simplified by using the Dependency Injection mechanism.

Now, to add a new field to the profile form or change existing fields, you don't need to edit the source directly in the module. Instead, a new class with the necessary implementation is created, which replaces the original class via the DI mechanism.

The new Timezone field will be an enumeration value (Enum), which is stored in the corresponding class.

Create a file apps/client/src/app/integrations/custom-auth-profile-form.service.ts

import { Injectable } from '@angular/core';
import { LoginInput, UpdateProfileInput } from '@authorizerdev/authorizer-js';
import { TranslocoService } from '@jsverse/transloco';
import { ValidationErrorMetadataInterface } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { AuthProfileFormService } from '@nestjs-mod-fullstack/auth-angular';
import { marker } from '@ngneat/transloco-keys-manager/marker';
import { UntilDestroy } from '@ngneat/until-destroy';
import { FormlyFieldConfig } from '@ngx-formly/core';

@UntilDestroy()
@Injectable({ providedIn: 'root' })
export class CustomAuthProfileFormService extends AuthProfileFormService {
  private utcTimeZones = [
    {
      label: marker('UTC−12:00: Date Line (west)'),
      value: -12,
    },
    // ...
    {
      label: marker('UTC+14:00: Date Line (east)'),
      value: 14,
    },
  ];

  constructor(protected override readonly translocoService: TranslocoService) {
    super(translocoService);
  }

  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  override getFormlyFields(options?: { data?: LoginInput; errors?: ValidationErrorMetadataInterface[] }): FormlyFieldConfig[] {
    return super.appendServerErrorsAsValidatorsToFields(
      [
        ...super.getFormlyFields(),
        {
          key: 'timezone',
          type: 'select',
          validation: {
            show: true,
          },
          props: {
            label: this.translocoService.translate(`auth.sign-in-form.fields.timezone`),
            placeholder: 'timezone',
            required: false,
            options: this.utcTimeZones.map((z) => ({
              ...z,
              label: this.translocoService.translate(z.label),
            })),
          },
        },
      ],
      options?.errors || []
    );
  }

  override toModel(data: UpdateProfileInput) {
    return {
      old_password: data['old_password'],
      new_password: data['new_password'],
      confirm_new_password: data['confirm_new_password'],
      picture: data['picture'],
      timezone: data['timezone'],
    };
  }

  override toJson(data: UpdateProfileInput) {
    return {
      old_password: data['old_password'],
      new_password: data['new_password'],
      confirm_new_password: data['confirm_new_password'],
      picture: data['picture'],
      timezone: data['timezone'],
    };
  }
}

In addition to working with form fields, we also need to implement loading and saving the user's time zone to and from the form. To do this, we will create a new implementation of the service that will work with the user profile in the Auth database.

Create a file apps/client/src/app/integrations/custom-auth.service.ts

import { Inject, Injectable, Optional } from '@angular/core';
import { UpdateProfileInput, User } from '@authorizerdev/authorizer-js';
import { AuthRestService } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { AUTH_CONFIGURATION_TOKEN, AuthConfiguration, AuthorizerService, AuthService, TokensService } from '@nestjs-mod-fullstack/auth-angular';
import { UntilDestroy } from '@ngneat/until-destroy';
import { catchError, map, mergeMap, of } from 'rxjs';

@UntilDestroy()
@Injectable({ providedIn: 'root' })
export class CustomAuthService extends AuthService {
  constructor(
    protected readonly authRestService: AuthRestService,
    protected override readonly authorizerService: AuthorizerService,
    protected override readonly tokensService: TokensService,
    @Optional()
    @Inject(AUTH_CONFIGURATION_TOKEN)
    protected override readonly authConfiguration?: AuthConfiguration
  ) {
    super(authorizerService, tokensService, authConfiguration);
  }

  override setProfile(result: User | undefined) {
    return this.authRestService.authControllerProfile().pipe(
      catchError(() => of(null)),
      mergeMap((profile) => {
        if (result && profile) {
          Object.assign(result, profile);
        }
        return super.setProfile(result);
      })
    );
  }

  override updateProfile(data: UpdateProfileInput & { timezone: number }) {
    const { timezone, ...profile } = data;
    return super.updateProfile(profile).pipe(
      mergeMap((result) =>
        this.authRestService.authControllerUpdateProfile({ timezone }).pipe(
          map(() => {
            if (result) {
              Object.assign(result, { timezone });
            }
            return result;
          })
        )
      )
    );
  }
}

To make the new field appear in the profile form, you need to add class override rules to the frontend application configuration.

Update the file apps/client/src/app/integrations/custom-auth.service.ts

import { AUTHORIZER_URL, AuthProfileFormService, AuthService } from '@nestjs-mod-fullstack/auth-angular';
import { CustomAuthProfileFormService } from './integrations/custom-auth-profile-form.service';
import { CustomAuthService } from './integrations/custom-auth.service';
// ...

export const appConfig = ({ authorizerURL, minioURL }: { authorizerURL: string; minioURL: string }): ApplicationConfig => {
  return {
    providers: [
      // ...
      {
        provide: AuthProfileFormService,
        useClass: CustomAuthProfileFormService,
      },
      {
        provide: AuthService,
        useClass: CustomAuthService,
      },
    ],
  };
};

17. Creating an E2E test for an Angular application to check time zone switching

To test the application's behavior in the context of changing the user's time zone, we will create an End-to-End test for an Angular application that will check the correctness of time zone switching in the interface.

Create a file apps/client-e2e/src/timezone-profile-as-user.spec.ts

import { faker } from '@faker-js/faker';
import { expect, Page, test } from '@playwright/test';
import { isDateString } from 'class-validator';
import { differenceInHours } from 'date-fns';
import { get } from 'env-var';
import { join } from 'path';
import { setTimeout } from 'timers/promises';

test.describe('Work with profile as "User" role (timezone', () => {
  test.describe.configure({ mode: 'serial' });

  const correctStringDateLength = '0000-00-00T00:00:00.000Z'.length;

  const user = {
    email: faker.internet.email({
      provider: 'example.fakerjs.dev',
    }),
    password: faker.internet.password({ length: 8 }),
    site: `http://${faker.internet.domainName()}`,
  };
  let page: Page;

  test.beforeAll(async ({ browser }) => {
    page = await browser.newPage({
      viewport: { width: 1920, height: 1080 },
      recordVideo: {
        dir: join(__dirname, 'video'),
        size: { width: 1920, height: 1080 },
      },
    });
    await page.goto('/', {
      timeout: 7000,
    });
    await page.evaluate((authorizerURL) => localStorage.setItem('authorizerURL', authorizerURL), get('SERVER_AUTHORIZER_URL').required().asString());
    await page.evaluate((minioURL) => localStorage.setItem('minioURL', minioURL), get('SERVER_MINIO_URL').required().asString());
  });

  test.afterAll(async () => {
    await setTimeout(1000);
    await page.close();
  });

  test('sign up as user', async () => {
    await page.goto('/sign-up', {
      timeout: 7000,
    });

    await page.locator('auth-sign-up-form').locator('[placeholder=email]').click();
    await page.keyboard.type(user.email.toLowerCase(), {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=email]')).toHaveValue(user.email.toLowerCase());

    await page.locator('auth-sign-up-form').locator('[placeholder=password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=password]')).toHaveValue(user.password);

    await page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]')).toHaveValue(user.password);

    await expect(page.locator('auth-sign-up-form').locator('button[type=submit]')).toHaveText('Sign-up');

    await page.locator('auth-sign-up-form').locator('button[type=submit]').click();

    await setTimeout(3000);

    await expect(page.locator('nz-header').locator('[nz-submenu]').first()).toContainText(`You are logged in as ${user.email.toLowerCase()}`);
  });

  test('sign out after sign-up', async () => {
    await expect(page.locator('nz-header').locator('[nz-submenu]').first()).toContainText(`You are logged in as ${user.email.toLowerCase()}`);
    await page.locator('nz-header').locator('[nz-submenu]').first().click();

    await expect(page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').last()).toContainText(`Sign-out`);

    await page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').last().click();

    await setTimeout(4000);

    await expect(page.locator('nz-header').locator('[nz-menu-item]').last()).toContainText(`Sign-in`);
  });

  test('sign in as user', async () => {
    await page.goto('/sign-in', {
      timeout: 7000,
    });

    await page.locator('auth-sign-in-form').locator('[placeholder=email]').click();
    await page.keyboard.type(user.email.toLowerCase(), {
      delay: 50,
    });
    await expect(page.locator('auth-sign-in-form').locator('[placeholder=email]')).toHaveValue(user.email.toLowerCase());

    await page.locator('auth-sign-in-form').locator('[placeholder=password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-in-form').locator('[placeholder=password]')).toHaveValue(user.password);

    await expect(page.locator('auth-sign-in-form').locator('button[type=submit]')).toHaveText('Sign-in');

    await page.locator('auth-sign-in-form').locator('button[type=submit]').click();

    await setTimeout(3000);

    await expect(page.locator('nz-header').locator('[nz-submenu]').first()).toContainText(`You are logged in as ${user.email.toLowerCase()}`);
  });

  test('should change timezone in profile', async () => {
    const oldServerTime = await page.locator('#serverTime').innerText();
    expect(oldServerTime).toHaveLength(correctStringDateLength);
    expect(isDateString(oldServerTime)).toBeTruthy();

    await expect(page.locator('nz-header').locator('[nz-submenu]').first()).toContainText(`You are logged in as ${user.email.toLowerCase()}`);
    await page.locator('nz-header').locator('[nz-submenu]').first().click();

    await expect(page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').first()).toContainText(`Profile`);

    await page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').first().click();

    await setTimeout(4000);
    //
    await page.locator('auth-profile-form').locator('[placeholder=timezone]').click();
    await page.keyboard.press('Enter', { delay: 100 });
    await expect(page.locator('auth-profile-form').locator('[placeholder=timezone]')).toContainText('UTC−12:00: Date Line (west)');

    await expect(page.locator('auth-profile-form').locator('button[type=submit]')).toHaveText('Update');

    await page.locator('auth-profile-form').locator('button[type=submit]').click();

    await setTimeout(5000);

    const newServerTime = await page.locator('#serverTime').innerText();
    expect(newServerTime).toHaveLength(correctStringDateLength);
    expect(isDateString(newServerTime)).toBeTruthy();

    expect(differenceInHours(new Date(oldServerTime), new Date(newServerTime))).toBeGreaterThanOrEqual(11);
  });
});

Let's run the test and see if it passes.

Commands

npm run nx -- run client-e2e:e2e timezone

If the test is successful, then the time zone switching in the application works correctly.

Conclusion

Within the framework of this article, support for user time zones was implemented, and the information about the zone is stored in the database.

We placed the main logic for processing time zones on the server side of the application. On the client side, the time zone property is added using the dependency injection mechanism (Dependency Injection).

The functionality was thoroughly tested using E2E testing.

Plans

In the next post I will talk about how to add the ability to save the user's selected language to the database. This is important, since the language can now differ on different devices of the same user.

Adding multi-language support to NestJS and Angular applications

Ilshat Khamitov — Tue, 03 Dec 2024 19:34:16 +0000

In this article I will add support for multiple languages in NestJS and Angular applications, for error messages, notifications and data retrieved from the database.

1. We install all the necessary libraries

Commands

npm install --save @jsverse/transloco nestjs-translates class-validator-multi-lang class-transformer-global-storage @jsverse/transloco-keys-manager

Since we use external generators, we do not have access to the generated code, but to be able to translate validation errors, we need to use the class-validator-multi-lang library instead of class-validator, which the generator adds.

To replace imports in typescript files, we will install and connect the webpack plugin for replacing strings.

Commands

npm install --save string-replace-loader

We register replacement rules in our webpack config.

Updating the file apps/server/webpack.config.js

const { composePlugins, withNx } = require('@nx/webpack');

// Nx plugins for webpack.
module.exports = composePlugins(
  withNx({
    sourceMap: true,
    target: 'node',
  }),
  (config) => {
    // Update the webpack config as needed here.
    // e.g. `config.plugins.push(new MyPlugin())`

    config.module.rules = [
      ...config.module.rules,
      {
        test: /\.(ts)$/,
        loader: 'string-replace-loader',
        options: {
          search: `class-validator`,
          replace: `class-validator-multi-lang`,
          flags: 'g',
        },
      },
      {
        test: /\.(ts)$/,
        loader: 'string-replace-loader',
        options: {
          search: 'class-transformer',
          replace: 'class-transformer-global-storage',
          flags: 'g',
        },
      },
    ];
    return config;
  }
);

2. Adding translation support to an Angular application

Adding a new module to the frontend config.

Updating the file apps/client/src/app/app.config.ts

import { provideTransloco } from '@jsverse/transloco';
import { marker } from '@jsverse/transloco-keys-manager/marker';
import { AUTHORIZER_URL } from '@nestjs-mod-fullstack/auth-angular';
import { TranslocoHttpLoader } from './integrations/transloco-http.loader';

export const appConfig = ({ authorizerURL, minioURL }: { authorizerURL: string; minioURL: string }): ApplicationConfig => {
  return {
    providers: [
      // ...
      provideTransloco({
        config: {
          availableLangs: [
            {
              id: marker('en'),
              label: marker('app.locale.name.english'),
            },
            {
              id: marker('ru'),
              label: marker('app.locale.name.russian'),
            },
          ],
          defaultLang: 'en',
          fallbackLang: 'en',
          reRenderOnLangChange: true,
          prodMode: true,
          missingHandler: {
            logMissingKey: true,
            useFallbackTranslation: true,
            allowEmpty: true,
          },
        },
        loader: TranslocoHttpLoader,
      }),
    ],
  };
};

To download translations from the Internet, you need to create a special downloader.

Create a file apps/client/src/app/integrations/transloco-http.loader.ts

import { HttpClient } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { Translation, TranslocoLoader } from '@jsverse/transloco';
import { catchError, forkJoin, map, of } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class TranslocoHttpLoader implements TranslocoLoader {
  constructor(private readonly httpClient: HttpClient) {}

  getTranslation(lang: string) {
    return forkJoin({
      translation: this.httpClient.get<Translation>(`./assets/i18n/${lang}.json`).pipe(
        catchError(() => {
          return of({});
        })
      ),
      vendor: this.httpClient.get(`./assets/i18n/${lang}.vendor.json`).pipe(
        catchError(() => {
          return of({});
        })
      ),
    }).pipe(
      map(({ translation, vendor }) => {
        const dictionaries = {
          ...translation,
          ...Object.keys(vendor).reduce((all, key) => ({ ...all, ...vendor[key] }), {}),
        };

        for (const key in dictionaries) {
          if (Object.prototype.hasOwnProperty.call(dictionaries, key)) {
            const value = dictionaries[key];
            if (!value && value !== 'empty') {
              delete dictionaries[key];
            }
          }
        }
        return dictionaries;
      })
    );
  }
}

Translations will be loaded when the application is launched.

Updating the file apps/client/src/app/app-initializer.ts

import { HttpHeaders } from '@angular/common/http';
import { Injectable } from '@angular/core';
import { TranslocoService } from '@jsverse/transloco';
import { AppRestService, AuthorizerRestService, FilesRestService, TimeRestService, WebhookRestService } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { AuthService, TokensService } from '@nestjs-mod-fullstack/auth-angular';
import { catchError, map, merge, mergeMap, of, Subscription, tap, throwError } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class AppInitializer {
  private subscribeToTokenUpdatesSubscription?: Subscription;

  constructor(
    // ..
    private readonly translocoService: TranslocoService,
    private readonly tokensService: TokensService
  ) {}

  resolve() {
    this.subscribeToTokenUpdates();
    return (
      this.authService.getAuthorizerClientID()
        ? of(null)
        : this.authorizerRestService.authorizerControllerGetAuthorizerClientID().pipe(
            map(({ clientID }) => {
              this.authService.setAuthorizerClientID(clientID);
              return null;
            })
          )
    ).pipe(
      // ..
      mergeMap(() => {
        const lang = localStorage.getItem('activeLang') || this.translocoService.getDefaultLang();

        this.translocoService.setActiveLang(lang);
        localStorage.setItem('activeLang', lang);

        return this.translocoService.load(lang);
      })
      // ..
    );
  }

  private subscribeToTokenUpdates() {
    if (this.subscribeToTokenUpdatesSubscription) {
      this.subscribeToTokenUpdatesSubscription.unsubscribe();
      this.subscribeToTokenUpdatesSubscription = undefined;
    }
    this.subscribeToTokenUpdatesSubscription = merge(this.tokensService.tokens$, this.translocoService.langChanges$)
      .pipe(
        tap(() => {
          // ..
        })
      )
      .subscribe();
  }
}

The default language will be English. To switch the language in the navigation menu, we will add a drop-down list with the languages available for switching.

Updating the file apps/client/src/app/app.component.ts

import { LangDefinition, TranslocoDirective, TranslocoPipe, TranslocoService } from '@jsverse/transloco';
import { marker } from '@jsverse/transloco-keys-manager/marker';
import { AppRestService, TimeRestService } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
// ...

@UntilDestroy()
@Component({
  standalone: true,
  imports: [RouterModule, NzMenuModule, NzLayoutModule, NzTypographyModule, AsyncPipe, NgForOf, NgFor, TranslocoPipe, TranslocoDirective],
  selector: 'app-root',
  templateUrl: './app.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AppComponent implements OnInit {
  title = marker('client');
  serverMessage$ = new BehaviorSubject('');
  serverTime$ = new BehaviorSubject('');
  authUser$?: Observable<User | undefined>;
  lang$ = new BehaviorSubject<string>('');
  availableLangs$ = new BehaviorSubject<LangDefinition[]>([]);

  constructor(
    // ...
    private readonly appRestService: AppRestService,
    private readonly translocoService: TranslocoService
  ) {}

  ngOnInit() {
    this.loadAvailableLangs();
    this.subscribeToLangChanges();

    this.fillServerMessage().pipe(untilDestroyed(this)).subscribe();
    // ...
  }

  setActiveLang(lang: string) {
    this.translocoService.setActiveLang(lang);
    localStorage.setItem('activeLang', lang);
  }

  private loadAvailableLangs() {
    this.availableLangs$.next(this.translocoService.getAvailableLangs() as LangDefinition[]);
  }

  private subscribeToLangChanges() {
    this.translocoService.langChanges$
      .pipe(
        tap((lang) => this.lang$.next(lang)),
        mergeMap(() => this.fillServerMessage()),
        untilDestroyed(this)
      )
      .subscribe();
  }

  // ...

  private fillServerMessage() {
    return this.appRestService.appControllerGetData().pipe(tap((result) => this.serverMessage$.next(result.message)));
  }
}

3. We update the existing code and templates for the subsequent launch of parsing words and sentences for translating the Angular application

There are a lot of changes in the files, here I will list the main principles of implementing translation support in the Angular application files.

Using the translation directive (transloco=)

Sample file libs/core/auth-angular/src/lib/forms/auth-profile-form/auth-profile-form.component.ts

import { TranslocoDirective } from '@jsverse/transloco';

@Component({
  standalone: true,
  imports: [
    // ...
    TranslocoDirective,
  ],
  selector: 'auth-profile-form',
  template: `@if (formlyFields$ | async; as formlyFields) {
    <form nz-form [formGroup]="form" (ngSubmit)="submitForm()">
      <formly-form [model]="formlyModel$ | async" [fields]="formlyFields" [form]="form"> </formly-form>
      @if (!hideButtons) {
      <nz-form-control>
        <div class="flex justify-between">
          <div></div>
          <button nz-button nzType="primary" type="submit" [disabled]="!form.valid" transloco="Update"></button>
        </div>
      </nz-form-control>
      }
    </form>
    } `,
})
export class AuthProfileFormComponent implements OnInit {}

Using the translation pipe (| transloco)

Sample file apps/client/src/app/pages/demo/forms/demo-form/demo-form.component.html

@if (formlyFields$ | async; as formlyFields) {
<form nz-form [formGroup]="form" (ngSubmit)="submitForm()">
  <formly-form [model]="formlyModel$ | async" [fields]="formlyFields" [form]="form"> </formly-form>
  @if (!hideButtons) {
  <nz-form-control>
    <button nzBlock nz-button nzType="primary" type="submit" [disabled]="!form.valid">{{ id ? ('Save' | transloco) : ('Create' | transloco) }}</button>
  </nz-form-control>
  }
</form>
}

Using the translation service (translocoService: TranslocoService)

Sample file apps/client/src/app/pages/demo/forms/demo-form/demo-form.component.html

// ...
import { TranslocoService } from '@jsverse/transloco';

@Component({
  // ...
})
export class AuthSignInFormComponent implements OnInit {
  // ...

  constructor(
    @Optional()
    @Inject(NZ_MODAL_DATA)
    private readonly nzModalData: AuthSignInFormComponent,
    private readonly authService: AuthService,
    private readonly nzMessageService: NzMessageService,
    private readonly translocoService: TranslocoService
  ) {}

  ngOnInit(): void {
    Object.assign(this, this.nzModalData);
    this.setFieldsAndModel({ password: '' });
  }

  setFieldsAndModel(data: LoginInput = { password: '' }) {
    this.formlyFields$.next([
      {
        key: 'email',
        type: 'input',
        validation: {
          show: true,
        },
        props: {
          label: this.translocoService.translate(`auth.sign-in-form.fields.email`),
          placeholder: 'email',
          required: true,
        },
      },
      // ...
    ]);
    // ...
  }
  // ...
}

Using a marker

The output of the translation via a directive, pipe and service is used not only for translation, but also as a marker for compiling dictionaries with sentences for translation. The project contains files without directives, pipes and services that contain sentences for translation, such sentences must be wrapped in the marker function.

Sample file apps/client/src/app/app.config.ts

// ...
import { marker } from '@jsverse/transloco-keys-manager/marker';
// ...

export const appConfig = ({ authorizerURL, minioURL }: { authorizerURL: string; minioURL: string }): ApplicationConfig => {
  return {
    providers: [
      // ...
      provideTransloco({
        config: {
          availableLangs: [
            {
              id: marker('en'),
              label: marker('app.locale.name.english'),
            },
            {
              id: marker('ru'),
              label: marker('app.locale.name.russian'),
            },
          ],
          defaultLang: 'en',
          fallbackLang: 'en',
          reRenderOnLangChange: true,
          prodMode: true,
          missingHandler: {
            logMissingKey: true,
            useFallbackTranslation: true,
            allowEmpty: true,
          },
        },
        loader: TranslocoHttpLoader,
      }),
    ],
  };
};

4. Adding translation support to the NestJS application

Adding a new module to AppModule.

Updating the file apps/server/src/app/app.module.ts

import { TranslatesModule } from 'nestjs-translates';
// ...

export const { AppModule } = createNestModule({
  moduleName: 'AppModule',
  moduleCategory: NestModuleCategory.feature,
  imports: [
    // ...
    TranslatesModule.forRootDefault({
      localePaths: [join(__dirname, 'assets', 'i18n'), join(__dirname, 'assets', 'i18n', 'getText'), join(__dirname, 'assets', 'i18n', 'class-validator-messages')],
      vendorLocalePaths: [join(__dirname, 'assets', 'i18n')],
      locales: ['en', 'ru'],
      validationPipeOptions: {
        validatorPackage: require('class-validator'),
        transformerPackage: require('class-transformer'),
        transform: true,
        whitelist: true,
        validationError: {
          target: false,
          value: false,
        },
        exceptionFactory: (errors) => new ValidationError(ValidationErrorEnum.COMMON, undefined, errors),
      },
      usePipes: true,
      useInterceptors: true,
    }),
    // ...
  ],
  // ...
});

In order for validation errors to be sent to the frontend in the language that was specified in the request to the backend, it is necessary to connect the corresponding dictionaries with translations to the NX project.

Updating the file apps/server/project.json

{
  "name": "server",
  // ...
  "targets": {
    "build": {
      "executor": "@nx/webpack:webpack",
      // ...
      "options": {
        // ...
        "assets": [
          "apps/server/src/assets",
          {
            "glob": "**/*.json",
            "input": "./node_modules/class-validator-multi-lang/i18n/",
            "output": "./assets/i18n/class-validator-multi-lang-messages/"
          }
        ],
        "webpackConfig": "apps/server/webpack.config.js"
      }
    }
    // ...
  }
}

5. Updating the existing code for subsequent launch of parsing of words and sentences for translation of the NestJS application

There are a lot of changes in the files, here I will list the main principles of implementing support for translations in the files of the NestJS application.

Using a decorator with a translation function (@InjectTranslateFunction() getText: TranslateFunction)

Sample file apps/server/src/app/app.controller.ts

import { InjectTranslateFunction, TranslateFunction } from 'nestjs-translates';
// ...
@AllowEmptyUser()
@Controller()
export class AppController {
  @Get('/get-data')
  @ApiOkResponse({ type: AppData })
  getData(@InjectTranslateFunction() getText: TranslateFunction) {
    return this.appService.getData(getText);
  }
}

Using the translation service (translatesService: TranslatesService)

Sample file libs/feature/webhook/src/lib/controllers/webhook.controller.ts

// ...
import { CurrentLocale, TranslatesService } from 'nestjs-translates';

// ...
@Controller('/webhook')
export class WebhookController {
  constructor(
    // ...
    private readonly translatesService: TranslatesService
  ) {}

  // ...

  @Delete(':id')
  @ApiOkResponse({ type: StatusResponse })
  async deleteOne(
    // ...
    @CurrentLocale() locale: string
  ) {
    // ...
    return { message: this.translatesService.translate('ok', locale) };
  }
}

Using a marker (getText)

The output of the translation via a decorator with a function and a service is used not only for translation, but also as a marker for compiling dictionaries with sentences for translation.

If you want to mark a sentence so that it gets into a dictionary with translations, then you need to wrap the sentence in the getText function.

Sample file libs/core/auth/src/lib/auth.errors.ts

// ...
import { getText } from 'nestjs-translates';

// ...

export const AUTH_ERROR_ENUM_TITLES: Record<AuthErrorEnum, string> = {
  [AuthErrorEnum.COMMON]: getText('Auth error'),
  // ...
};

// ...

6. Automatic generation of dictionaries for translations

The markup of sentences and words for backend and frontend translations differs. A long time ago I made a utility for myself that collects dictionaries for such projects, and I will use it in this project.

If the utility was not previously installed or the version was old, then you need to reinstall it.

Commands

npm install --save-dev rucken@latest

Launch the utility

Commands

./node_modules/.bin/rucken prepare --locales=en,ru --update-package-version=false

After running this command, the project will have many files with extensions: po, pot, json.

Example files

The file with the extension XXX.pot contains the keys of the sentences for translation.

Sample file apps/client/src/assets/i18n/template.pot

msgid ""
msgstr ""
"Project-Id-Version: i18next-conv\n"
"mime-version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"

msgid "Create new"
msgstr "Create new"

msgid "app.locale.name.english"
msgstr "app.locale.name.english"

msgid "app.locale.name.russian"
msgstr "app.locale.name.russian"

Files with the extension <lang>.po contain translations into the required language.

Sample file apps/client/src/assets/i18n/en.po

msgid ""
msgstr ""
"Project-Id-Version: i18next-conv\n"
"mime-version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"

msgid "Create new"
msgstr "Create new"

msgid "app.locale.name.english"
msgstr "app.locale.name.english"

msgid "app.locale.name.russian"
msgstr "app.locale.name.russian"

Sample file apps/client/src/assets/i18n/ru.po

msgid ""
msgstr ""
"Project-Id-Version: i18next-conv\n"
"mime-version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"

msgid "Create new"
msgstr ""

msgid "app.locale.name.english"
msgstr ""

msgid "app.locale.name.russian"
msgstr ""

Files with the extension <lang>.json contain translations into the required language in json format.

Sample file apps/client/src/assets/i18n/ru.json

{
  "Create new": "",
  "app.locale.name.english": "",
  "app.locale.name.russian": ""
}

Sample file apps/client/src/assets/i18n/en.json

{
  "Create new": "Create new",
  "app.locale.name.english": "app.locale.name.english",
  "app.locale.name.russian": "app.locale.name.russian"
}

7. Adding translations for all dictionaries

For bulk translation of dictionaries, I usually use the cross-platform program poedit.net.

I already wrote a post with an example of using this program - https://dev.to/endykaufman/add-new-dictionaries-with-translations-to-nestjs-application-using-poeditnet-3ei2.

Now I will simply give an example of manual translation of dictionaries.

Sample file apps/client/src/assets/i18n/ru.po

msgid ""
msgstr ""
"Project-Id-Version: i18next-conv\n"
"mime-version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"

msgid "Create new"
msgstr "Создать"

msgid "app.locale.name.english"
msgstr "Английский"

msgid "app.locale.name.russian"
msgstr "Русский"

Sample file apps/client/src/assets/i18n/en.po

msgid ""
msgstr ""
"Project-Id-Version: i18next-conv\n"
"mime-version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1)\n"

msgid "app.locale.name.english"
msgstr "English"

msgid "app.locale.name.russian"
msgstr "Russian"

Translations can be added for both po files and json.

After adding all the necessary translations, you need to run a command that will combine all the translations and create dictionaries at the application level.

Commands

./node_modules/.bin/rucken prepare --locales=en,ru --update-package-version=false

Translation workflow:

Collect translation dictionaries ./node_modules/.bin/rucken prepare --locales=en,ru --update-package-version=false;
Add translations to all *.po files;
Generate json version of translations ./node_modules/.bin/rucken prepare --locales=en,ru --update-package-version=false;
Launch applications and they load json files with translations.

8. Add a test to check translated responses from the backend

Create a file apps/server-e2e/src/server/ru-validation.spec.ts

import { RestClientHelper } from '@nestjs-mod-fullstack/testing';
import { AxiosError } from 'axios';

describe('Validation (ru)', () => {
  jest.setTimeout(60000);

  const user1 = new RestClientHelper({ activeLang: 'ru' });

  beforeAll(async () => {
    await user1.createAndLoginAsUser();
  });

  it('should catch error on create new webhook as user1', async () => {
    try {
      await user1.getWebhookApi().webhookControllerCreateOne({
        enabled: false,
        endpoint: '',
        eventName: '',
      });
    } catch (err) {
      expect((err as AxiosError).response?.data).toEqual({
        code: 'VALIDATION-000',
        message: 'Validation error',
        metadata: [
          {
            property: 'eventName',
            constraints: [
              {
                name: 'isNotEmpty',
                description: 'eventName не может быть пустым',
              },
            ],
          },
          {
            property: 'endpoint',
            constraints: [
              {
                name: 'isNotEmpty',
                description: 'endpoint не может быть пустым',
              },
            ],
          },
        ],
      });
    }
  });
});

9. Add a test to check the correct switching of translations in the frontend application

Create a file apps/client-e2e/src/ru-validation.spec.ts

import { faker } from '@faker-js/faker';
import { expect, Page, test } from '@playwright/test';
import { get } from 'env-var';
import { join } from 'path';
import { setTimeout } from 'timers/promises';

test.describe('Validation (ru)', () => {
  test.describe.configure({ mode: 'serial' });

  const user = {
    email: faker.internet.email({
      provider: 'example.fakerjs.dev',
    }),
    password: faker.internet.password({ length: 8 }),
    site: `http://${faker.internet.domainName()}`,
  };
  let page: Page;

  test.beforeAll(async ({ browser }) => {
    page = await browser.newPage({
      viewport: { width: 1920, height: 1080 },
      recordVideo: {
        dir: join(__dirname, 'video'),
        size: { width: 1920, height: 1080 },
      },
    });
    await page.goto('/', {
      timeout: 7000,
    });
    await page.evaluate((authorizerURL) => localStorage.setItem('authorizerURL', authorizerURL), get('SERVER_AUTHORIZER_URL').required().asString());
    await page.evaluate((minioURL) => localStorage.setItem('minioURL', minioURL), get('SERVER_MINIO_URL').required().asString());
  });

  test.afterAll(async () => {
    await setTimeout(1000);
    await page.close();
  });

  test('should change language to RU', async () => {
    await expect(page.locator('nz-header').locator('[nz-submenu]')).toContainText(`EN`);
    await page.locator('nz-header').locator('[nz-submenu]').last().click();

    await expect(page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').last()).toContainText(`Russian`);

    await page.locator('[nz-submenu-none-inline-child]').locator('[nz-menu-item]').last().click();

    await setTimeout(4000);
    //

    await expect(page.locator('nz-header').locator('[nz-submenu]')).toContainText(`RU`);
  });

  test('sign up as user', async () => {
    await page.goto('/sign-up', {
      timeout: 7000,
    });

    await page.locator('auth-sign-up-form').locator('[placeholder=email]').click();
    await page.keyboard.type(user.email.toLowerCase(), {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=email]')).toHaveValue(user.email.toLowerCase());

    await page.locator('auth-sign-up-form').locator('[placeholder=password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=password]')).toHaveValue(user.password);

    await page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]')).toHaveValue(user.password);

    await expect(page.locator('auth-sign-up-form').locator('button[type=submit]')).toHaveText('Зарегистрироваться');

    await page.locator('auth-sign-up-form').locator('button[type=submit]').click();

    await setTimeout(5000);

    await expect(page.locator('nz-header').locator('[nz-submenu]').first()).toContainText(`Вы вошли в систему как ${user.email.toLowerCase()}`);
  });

  test('should catch error on create new webhook', async () => {
    await page.locator('webhook-grid').locator('button').first().click();

    await setTimeout(7000);

    await page.locator('[nz-modal-footer]').locator('button').last().click();

    await setTimeout(4000);

    await expect(page.locator('webhook-form').locator('formly-validation-message').first()).toContainText('поле "адрес" не может быть пустым');
    await expect(page.locator('webhook-form').locator('formly-validation-message').last()).toContainText('поле "событие" не может быть пустым');
  });
});

10. We launch the infrastructure with applications in development mode and check the operation through E2E tests

Commands

npm run pm2-full:dev:start
npm run pm2-full:dev:test:e2e

Conclusion

In this post I added support for working with multiple languages in NestJS and Angular applications, as well as switching them in real time.

I created dictionaries for all sentences that need to be translated and added translations into English and Russian.

The user's selected language is saved in localstorage and is used as the active one when the page is fully reloaded, in future posts it will be saved to the database.

Plans

In the next post I will add support for working with time zones, as well as saving the user-selected time zone to the database...

Validating REST requests in a NestJS application and displaying errors in Angular application forms

Ilshat Khamitov — Sun, 24 Nov 2024 19:36:40 +0000

In this post I will add validation of REST requests in NestJS application and their display in forms of Angular application.

1. Install a new code generator

Install a new DTO generator from the Prisma schema and remove the old one, since the old one does not add validation decorators using class-validator.

Commands

npm install --save-dev @brakebein/prisma-generator-nestjs-dto@1.24.0-beta5
npm uninstall --save-dev prisma-class-generator

We delete the old generated code and create a new one.

Commands

rm -rf libs/feature/webhook/src/lib/generated
rm -rf apps/server/src/app/generated
npm run prisma:generate

2. Create a NestJS module to store the code needed for validation

Commands

./node_modules/.bin/nx g @nestjs-mod/schematics:library validation --buildable --publishable --directory=libs/core/validation --simpleName=true --projectNameAndRootFormat=as-provided --strict=true

Console output

$ ./node_modules/.bin/nx g @nestjs-mod/schematics:library validation --buildable --publishable --directory=libs/core/validation --simpleName=true --projectNameAndRootFormat=as-provided --strict=true

 NX  Generating @nestjs-mod/schematics:library

CREATE libs/core/validation/tsconfig.json
CREATE libs/core/validation/src/index.ts
CREATE libs/core/validation/tsconfig.lib.json
CREATE libs/core/validation/README.md
CREATE libs/core/validation/package.json
CREATE libs/core/validation/project.json
CREATE libs/core/validation/.eslintrc.json
CREATE libs/core/validation/jest.config.ts
CREATE libs/core/validation/tsconfig.spec.json
UPDATE tsconfig.base.json
CREATE libs/core/validation/src/lib/validation.configuration.ts
CREATE libs/core/validation/src/lib/validation.constants.ts
CREATE libs/core/validation/src/lib/validation.environments.ts
CREATE libs/core/validation/src/lib/validation.module.ts

Module environment variables

Add an environment variable to enable and disable global input data validation.

Since the fields in the database have their own validation and if we want to check the correctness of the validation at the database level, then checking the input data in the backend will not allow us to do this, for such a check during the development and testing of functionality, you need to be able to temporarily disable validation at the entrance to the backend.

The module comes with a built-in filter for correct display of errors, if you need to customize it, you can create your own version and at the same time disable the filter built into the module.

Updating the file libs/core/validation/src/lib/validation.environments.ts

import { BooleanTransformer, EnvModel, EnvModelProperty } from '@nestjs-mod/common';

@EnvModel()
export class ValidationEnvironments {
  @EnvModelProperty({
    description: 'Use pipes.',
    transform: new BooleanTransformer(),
    default: true,
    hidden: true,
  })
  usePipes?: boolean;

  @EnvModelProperty({
    description: 'Use filters.',
    transform: new BooleanTransformer(),
    default: true,
    hidden: true,
  })
  useFilters?: boolean;
}

Example of environment variables:

Key	Description	Sources	Constraints	Default	Value
`usePipes`	Use pipes.	`obj['usePipes']`, `process.env['SERVER_VALIDATION_USE_PIPES']`	optional	`true`	`true`
`useFilters`	Use filters.	`obj['useFilters']`, `process.env['SERVER_VALIDATION_USE_FILTERS']`	optional	`true`	`true`

Module Configuration

Currently there is only one parameter here, this is the configuration for creating ValidationPipe.

Updating the file libs/core/validation/src/lib/validation.configuration.ts

import { ConfigModel, ConfigModelProperty } from '@nestjs-mod/common';
import { ValidationPipeOptions } from '@nestjs/common';

@ConfigModel()
export class ValidationConfiguration {
  @ConfigModelProperty({
    description: 'Validation pipe options',
  })
  pipeOptions?: ValidationPipeOptions;
}

Class with module errors

Since at this stage the project is being developed as a REST backend, which is available on the frontend as an OpenApi library, the class with errors is also published in the Swagger schema.

In order to make the error description more detailed, it uses decorators that add meta information that will be output to the Swagger schema.

Create a file libs/core/validation/src/lib/validation.errors.ts

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { ValidationError as CvValidationError } from 'class-validator';

export enum ValidationErrorEnum {
  COMMON = 'VALIDATION-000',
}

export const VALIDATION_ERROR_ENUM_TITLES: Record<ValidationErrorEnum, string> = {
  [ValidationErrorEnum.COMMON]: 'Validation error',
};

export class ValidationErrorMetadataConstraint {
  @ApiProperty({
    type: String,
  })
  name!: string;

  @ApiProperty({
    type: String,
  })
  description!: string;

  constructor(options?: ValidationErrorMetadataConstraint) {
    Object.assign(this, options);
  }
}

export class ValidationErrorMetadata {
  @ApiProperty({
    type: String,
  })
  property!: string;

  @ApiProperty({
    type: () => ValidationErrorMetadataConstraint,
    isArray: true,
  })
  constraints!: ValidationErrorMetadataConstraint[];

  @ApiPropertyOptional({
    type: () => ValidationErrorMetadata,
    isArray: true,
  })
  children?: ValidationErrorMetadata[];

  constructor(options?: ValidationErrorMetadata) {
    Object.assign(this, options);
  }

  static fromClassValidatorValidationErrors(errors?: CvValidationError[]): ValidationErrorMetadata[] | undefined {
    return errors?.map(
      (error) =>
        new ValidationErrorMetadata({
          property: error.property,
          constraints: Object.entries(error.constraints || {}).map(
            ([key, value]) =>
              new ValidationErrorMetadataConstraint({
                name: key,
                description: value,
              })
          ),
          ...(error.children?.length
            ? {
                children: this.fromClassValidatorValidationErrors(error.children),
              }
            : {}),
        })
    );
  }
}

export class ValidationError extends Error {
  @ApiProperty({
    type: String,
    description: Object.entries(VALIDATION_ERROR_ENUM_TITLES)
      .map(([key, value]) => `${value} (${key})`)
      .join(', '),
    example: VALIDATION_ERROR_ENUM_TITLES[ValidationErrorEnum.COMMON],
  })
  override message: string;

  @ApiProperty({
    enum: ValidationErrorEnum,
    enumName: 'ValidationErrorEnum',
    example: ValidationErrorEnum.COMMON,
  })
  code = ValidationErrorEnum.COMMON;

  @ApiPropertyOptional({ type: ValidationErrorMetadata, isArray: true })
  metadata?: ValidationErrorMetadata[];

  constructor(message?: string | ValidationErrorEnum, code?: ValidationErrorEnum, metadata?: CvValidationError[]) {
    const messageAsCode = Boolean(message && Object.values(ValidationErrorEnum).includes(message as ValidationErrorEnum));
    const preparedCode = messageAsCode ? (message as ValidationErrorEnum) : code;
    const preparedMessage = preparedCode ? VALIDATION_ERROR_ENUM_TITLES[preparedCode] : message;

    code = preparedCode || ValidationErrorEnum.COMMON;
    message = preparedMessage || VALIDATION_ERROR_ENUM_TITLES[code];

    super(message);

    this.code = code;
    this.message = message;
    this.metadata = ValidationErrorMetadata.fromClassValidatorValidationErrors(metadata);
  }
}

Filter for module errors

To convert module errors to Http error, create ValidationExceptionsFilter.

Create a file libs/core/validation/src/lib/validation.filter.ts

import { ArgumentsHost, Catch, HttpException, HttpStatus, Logger } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';
import { ValidationError } from './validation.errors';

@Catch(ValidationError)
export class ValidationExceptionsFilter extends BaseExceptionFilter {
  private logger = new Logger(ValidationExceptionsFilter.name);

  override catch(exception: ValidationError, host: ArgumentsHost) {
    if (exception instanceof ValidationError) {
      this.logger.error(exception, exception.stack);
      super.catch(
        new HttpException(
          {
            code: exception.code,
            message: exception.message,
            metadata: exception.metadata,
          },
          HttpStatus.BAD_REQUEST
        ),
        host
      );
    } else {
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
      this.logger.error(exception, (exception as any)?.stack);
      super.catch(exception, host);
    }
  }
}

NestJS-mod module

Create a file libs/core/validation/src/lib/validation.module.ts

import { createNestModule, getFeatureDotEnvPropertyNameFormatter, NestModuleCategory } from '@nestjs-mod/common';
import { Provider, ValidationPipe } from '@nestjs/common';
import { APP_FILTER, APP_PIPE } from '@nestjs/core';
import { ValidationConfiguration } from './validation.configuration';
import { VALIDATION_FEATURE, VALIDATION_MODULE } from './validation.constants';
import { ValidationEnvironments } from './validation.environments';
import { ValidationExceptionsFilter } from './validation.filter';
import { ValidationError, ValidationErrorEnum } from './validation.errors';

export const { ValidationModule } = createNestModule({
  moduleName: VALIDATION_MODULE,
  moduleCategory: NestModuleCategory.feature,
  configurationModel: ValidationConfiguration,
  staticEnvironmentsModel: ValidationEnvironments,
  providers: ({ staticEnvironments }) => {
    const providers: Provider[] = [];
    if (staticEnvironments.usePipes) {
      providers.push({
        provide: APP_PIPE,
        useValue: new ValidationPipe({
          transform: true,
          whitelist: true,
          validationError: {
            target: false,
            value: false,
          },
          exceptionFactory: (errors) => new ValidationError(ValidationErrorEnum.COMMON, undefined, errors),
        }),
      });
    }
    if (staticEnvironments.useFilters) {
      providers.push({
        provide: APP_FILTER,
        useClass: ValidationExceptionsFilter,
      });
    }
    return providers;
  },
  wrapForRootAsync: (asyncModuleOptions) => {
    if (!asyncModuleOptions) {
      asyncModuleOptions = {};
    }
    const FomatterClass = getFeatureDotEnvPropertyNameFormatter(VALIDATION_FEATURE);
    Object.assign(asyncModuleOptions, {
      environmentsOptions: {
        propertyNameFormatters: [new FomatterClass()],
        name: VALIDATION_FEATURE,
      },
    });

    return { asyncModuleOptions };
  },
});

3. We correct types throughout the project, since the new generator creates types with different names and contents

We start regeneration of all SDK and other additional code, during generation type errors will be displayed, it is necessary to correct everything and re-run regeneration and so on until all errors are corrected.

Commands

npm run manual:prepare

4. In the web hook creation and editing form, we display server errors

To display errors in the Formly form, we use dynamic creation of validators that always return an error and put in the error text what we received from the backend.

An example of a server response with errors:

{
  "code": "VALIDATION-000",
  "message": "Validation error",
  "metadata": [
    {
      "property": "eventName",
      "constraints": [
        {
          "name": "isNotEmpty",
          "description": "eventName should not be empty"
        }
      ]
    },
    {
      "property": "endpoint",
      "constraints": [
        {
          "name": "isNotEmpty",
          "description": "endpoint should not be empty"
        }
      ]
    }
  ]
}

Updating the file libs/feature/webhook-angular/src/lib/forms/webhook-form/webhook-form.component.ts

import {
  //...
  ValidationErrorEnumInterface,
  ValidationErrorInterface,
  ValidationErrorMetadataInterface,
} from '@nestjs-mod-fullstack/app-angular-rest-sdk';

//...

@UntilDestroy()
@Component({
  standalone: true,
  imports: [FormlyModule, NzFormModule, NzInputModule, NzButtonModule, FormsModule, ReactiveFormsModule, AsyncPipe],
  selector: 'webhook-form',
  templateUrl: './webhook-form.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class WebhookFormComponent implements OnInit {
  //...

  constructor(
    @Optional()
    @Inject(NZ_MODAL_DATA)
    private readonly nzModalData: WebhookFormComponent,
    private readonly webhookService: WebhookService,
    private readonly webhookEventsService: WebhookEventsService,
    private readonly nzMessageService: NzMessageService
  ) {}

  //...

  createOne() {
    return this.webhookService.createOne(this.toJson(this.form.value)).pipe(catchError((err) => this.catchAndProcessServerError(err)));
  }

  updateOne() {
    if (!this.id) {
      throw new Error('id not set');
    }
    return this.webhookService.updateOne(this.id, this.toJson(this.form.value)).pipe(catchError((err) => this.catchAndProcessServerError(err)));
  }

  private setFormlyFields(errors?: ValidationErrorMetadataInterface[]) {
    this.formlyFields$.next(
      this.appendServerErrorsAsValidatorsToFields(
        [
          //...
          {
            key: 'requestTimeout',
            type: 'input',
            validation: {
              show: true,
            },
            props: {
              type: 'number',
              label: `webhook.form.requestTimeout`,
              placeholder: 'requestTimeout',
              required: false,
            },
          },
        ],
        errors
      )
    );
  }

  private appendServerErrorsAsValidatorsToFields(fields: FormlyFieldConfig[], errors?: ValidationErrorMetadataInterface[]) {
    return (fields || []).map((f: FormlyFieldConfig) => {
      const error = errors?.find((e) => e.property === f.key);
      if (error) {
        f.validators = Object.fromEntries(
          error.constraints.map((c) => {
            return [
              c.name === 'isNotEmpty' ? 'required' : c.name,
              {
                expression: () => false,
                message: () => c.description,
              },
            ];
          })
        );
      }
      return f;
    });
  }

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  private catchAndProcessServerError(err: any) {
    const error = err.error as ValidationErrorInterface;
    if (error.code.includes(ValidationErrorEnumInterface.VALIDATION_000)) {
      this.setFormlyFields(error.metadata);
      return of(null);
    }
    return throwError(() => err);
  }

  //...
}

5. Create a server E2E test to check the validation

Create a file apps/server-e2e/src/server/validation.spec.ts

import { RestClientHelper } from '@nestjs-mod-fullstack/testing';
import { AxiosError } from 'axios';

describe('Validation', () => {
  jest.setTimeout(60000);

  const user1 = new RestClientHelper();

  beforeAll(async () => {
    await user1.createAndLoginAsUser();
  });

  it('should catch error on create new webhook as user1', async () => {
    try {
      await user1.getWebhookApi().webhookControllerCreateOne({
        enabled: false,
        endpoint: '',
        eventName: '',
      });
    } catch (err) {
      expect((err as AxiosError).response?.data).toEqual({
        code: 'VALIDATION-000',
        message: 'Validation error',
        metadata: [
          {
            property: 'eventName',
            constraints: [
              {
                name: 'isNotEmpty',
                description: 'eventName should not be empty',
              },
            ],
          },
          {
            property: 'endpoint',
            constraints: [
              {
                name: 'isNotEmpty',
                description: 'endpoint should not be empty',
              },
            ],
          },
        ],
      });
    }
  });
});

6. Create a client E2E test to check the validation

Create a file apps/client-e2e/src/validation.spec.ts

import { faker } from '@faker-js/faker';
import { expect, Page, test } from '@playwright/test';
import { get } from 'env-var';
import { join } from 'path';
import { setTimeout } from 'timers/promises';

test.describe('Validation', () => {
  test.describe.configure({ mode: 'serial' });

  const user = {
    email: faker.internet.email({
      provider: 'example.fakerjs.dev',
    }),
    password: faker.internet.password({ length: 8 }),
    site: `http://${faker.internet.domainName()}`,
  };
  let page: Page;

  test.beforeAll(async ({ browser }) => {
    page = await browser.newPage({
      viewport: { width: 1920, height: 1080 },
      recordVideo: {
        dir: join(__dirname, 'video'),
        size: { width: 1920, height: 1080 },
      },
    });
    await page.goto('/', {
      timeout: 7000,
    });
    await page.evaluate((authorizerURL) => localStorage.setItem('authorizerURL', authorizerURL), get('SERVER_AUTHORIZER_URL').required().asString());
    await page.evaluate((minioURL) => localStorage.setItem('minioURL', minioURL), get('SERVER_MINIO_URL').required().asString());
  });

  test.afterAll(async () => {
    await setTimeout(1000);
    await page.close();
  });

  test('sign up as user', async () => {
    await page.goto('/sign-up', {
      timeout: 7000,
    });

    await page.locator('auth-sign-up-form').locator('[placeholder=email]').click();
    await page.keyboard.type(user.email.toLowerCase(), {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=email]')).toHaveValue(user.email.toLowerCase());

    await page.locator('auth-sign-up-form').locator('[placeholder=password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=password]')).toHaveValue(user.password);

    await page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]').click();
    await page.keyboard.type(user.password, {
      delay: 50,
    });
    await expect(page.locator('auth-sign-up-form').locator('[placeholder=confirm_password]')).toHaveValue(user.password);

    await expect(page.locator('auth-sign-up-form').locator('button[type=submit]')).toHaveText('Sign-up');

    await page.locator('auth-sign-up-form').locator('button[type=submit]').click();

    await setTimeout(5000);

    await expect(page.locator('nz-header').locator('[nz-submenu]')).toContainText(`You are logged in as ${user.email.toLowerCase()}`);
  });

  test('should catch error on create new webhook', async () => {
    await page.locator('webhook-grid').locator('button').first().click();

    await setTimeout(7000);

    await page.locator('[nz-modal-footer]').locator('button').last().click();

    await setTimeout(4000);

    await expect(page.locator('webhook-form').locator('formly-validation-message').first()).toContainText('endpoint should not be empty');
    await expect(page.locator('webhook-form').locator('formly-validation-message').last()).toContainText('eventName should not be empty');
  });
});

7. We launch the infrastructure with applications in development mode and check the operation through E2E tests

Commands

npm run pm2-full:dev:start
npm run pm2-full:dev:test:e2e

Conclusion

In the current post, I added a module to the backend to enable serialization and validation of input REST data.

The code on the frontend is not unified and is implemented specifically in one form, with a large number of forms with such processing, it will be necessary to move the common code to a separate file.

The method I chose to create dynamic errors for Formly forms based on responses from the backend may not seem like a very beautiful solution, but I could not come up with a simpler and more working solution, perhaps as the project develops, another method will appear.

Plans

In the next post I will add support for multiple languages for backend and frontend applications...

Getting server time via WebSockets and displaying It in Angular application

Ilshat Khamitov — Wed, 20 Nov 2024 18:25:56 +0000

In this post I will describe how to create a web socket stream in the backend on NestJS and subscribe to it from the frontend application on Angular.

1. Install additional libraries

Install NestJS modules to work with websockets.

Commands

npm install --save @nestjs/websockets @nestjs/platform-socket.io @nestjs/platform-ws

Console output

$ npm install --save @nestjs/websockets @nestjs/platform-socket.io @nestjs/platform-ws

added 4 packages, removed 2 packages, and audited 2938 packages in 1m

360 packages are looking for funding
  run `npm fund` for details

42 vulnerabilities (21 low, 3 moderate, 18 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues possible (including breaking changes), run:
  npm audit fix --force

Some issues need review, and may require choosing
a different dependency.

Run `npm audit` for details.

2. Create a controller that returns server time

The controller has a method for issuing the current time and a web socket that returns the current backend time every second.

Create a file apps/server/src/app/time.controller.ts

import { Controller, Get } from '@nestjs/common';

import { AllowEmptyUser } from '@nestjs-mod/authorizer';
import { ApiOkResponse } from '@nestjs/swagger';
import { OnGatewayConnection, SubscribeMessage, WebSocketGateway, WsResponse } from '@nestjs/websockets';
import { interval, map, Observable } from 'rxjs';

export const ChangeTimeStream = 'ChangeTimeStream';

@AllowEmptyUser()
@WebSocketGateway({
  cors: {
    origin: '*',
  },
  path: '/ws/time',
  transports: ['websocket'],
})
@Controller()
export class TimeController implements OnGatewayConnection {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  handleConnection(client: any, ...args: any[]) {
    client.headers = args[0].headers;
  }

  @Get('/time')
  @ApiOkResponse({ type: Date })
  time() {
    return new Date();
  }

  @SubscribeMessage(ChangeTimeStream)
  onChangeTimeStream(): Observable<WsResponse<Date>> {
    return interval(1000).pipe(
      map(() => ({
        data: new Date(),
        event: ChangeTimeStream,
      }))
    );
  }
}

3. Adding a controller to AppModule

Since the controller also includes the gateway logic, we provide the controller in the controllers and providers sections.

Updating the file apps/server/src/app/app.module.ts

import { createNestModule, NestModuleCategory } from '@nestjs-mod/common';

import { WebhookModule } from '@nestjs-mod-fullstack/webhook';
import { PrismaModule } from '@nestjs-mod/prisma';
import { ServeStaticModule } from '@nestjs/serve-static';
import { join } from 'path';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { TimeController } from './time.controller';

export const { AppModule } = createNestModule({
  moduleName: 'AppModule',
  moduleCategory: NestModuleCategory.feature,
  imports: [
    WebhookModule.forFeature({
      featureModuleName: 'app',
    }),
    PrismaModule.forFeature({
      contextName: 'app',
      featureModuleName: 'app',
    }),
    ...(process.env.DISABLE_SERVE_STATIC
      ? []
      : [
          ServeStaticModule.forRoot({
            rootPath: join(__dirname, '..', 'client', 'browser'),
          }),
        ]),
  ],
  controllers: [AppController, TimeController],
  providers: [AppService, TimeController],
});

4. Rebuilding SDK for frontend and tests

Commands

npm run generate

5. Adding a utility for convenient work with web sockets from an Angular application

Create a file libs/common-angular/src/lib/utils/web-socket.ts

import { Observable, finalize } from 'rxjs';

export function webSocket<T>({
  address,
  eventName,
  options,
}: {
  address: string;
  eventName: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  options?: any;
}) {
  const wss = new WebSocket(address.replace('/api', '').replace('http', 'ws'), options);
  return new Observable<{ data: T; event: string }>((observer) => {
    wss.addEventListener('open', () => {
      wss.addEventListener('message', ({ data }) => {
        observer.next(JSON.parse(data.toString()));
      });
      wss.addEventListener('error', (err) => {
        observer.error(err);
        if (wss?.readyState == WebSocket.OPEN) {
          wss.close();
        }
      });
      wss.send(
        JSON.stringify({
          event: eventName,
          data: true,
        })
      );
    });
  }).pipe(
    finalize(() => {
      if (wss?.readyState == WebSocket.OPEN) {
        wss.close();
      }
    })
  );
}

6. Adding retrieval and display of the current server time in the page footer

Updating the file apps/client/src/app/app.component.ts

import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core';
import { Router, RouterModule } from '@angular/router';
import { User } from '@authorizerdev/authorizer-js';
import { AppRestService, TimeRestService } from '@nestjs-mod-fullstack/app-angular-rest-sdk';
import { AuthService } from '@nestjs-mod-fullstack/auth-angular';
import { webSocket } from '@nestjs-mod-fullstack/common-angular';
import { UntilDestroy, untilDestroyed } from '@ngneat/until-destroy';
import { NzLayoutModule } from 'ng-zorro-antd/layout';

import { NzMenuModule } from 'ng-zorro-antd/menu';
import { NzTypographyModule } from 'ng-zorro-antd/typography';
import { BehaviorSubject, map, merge, Observable, tap } from 'rxjs';

@UntilDestroy()
@Component({
  standalone: true,
  imports: [RouterModule, NzMenuModule, NzLayoutModule, NzTypographyModule, AsyncPipe],
  selector: 'app-root',
  templateUrl: './app.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class AppComponent implements OnInit {
  title = 'client';
  serverMessage$ = new BehaviorSubject('');
  serverTime$ = new BehaviorSubject('');
  authUser$: Observable<User | undefined>;

  constructor(private readonly timeRestService: TimeRestService, private readonly appRestService: AppRestService, private readonly authService: AuthService, private readonly router: Router) {
    this.authUser$ = this.authService.profile$.asObservable();
  }

  ngOnInit() {
    this.appRestService
      .appControllerGetData()
      .pipe(
        tap((result) => this.serverMessage$.next(result.message)),
        untilDestroyed(this)
      )
      .subscribe();

    merge(
      this.timeRestService.timeControllerTime(),
      webSocket<string>({
        address: this.timeRestService.configuration.basePath + '/ws/time',
        eventName: 'ChangeTimeStream',
      }).pipe(map((result) => result.data))
    )
      .pipe(
        tap((result) => this.serverTime$.next(result as string)),
        untilDestroyed(this)
      )
      .subscribe();
  }

  signOut() {
    this.authService
      .signOut()
      .pipe(
        tap(() => this.router.navigate(['/home'])),
        untilDestroyed(this)
      )
      .subscribe();
  }
}

Updating the file apps/client/src/app/app.component.html

<nz-layout class="layout">
  <nz-header>
    <div class="logo flex items-center justify-center">{{ title }}</div>
    <ul nz-menu nzTheme="dark" nzMode="horizontal">
      <li nz-menu-item routerLink="/home">Home</li>
      <li nz-menu-item routerLink="/demo">Demo</li>
      @if (authUser$|async; as authUser) {
      <li nz-menu-item routerLink="/webhook">Webhook</li>
      <li nz-submenu [nzTitle]="'You are logged in as ' + authUser.email" [style]="{ float: 'right' }">
        <ul>
          <li nz-menu-item routerLink="/profile">Profile</li>
          <li nz-menu-item (click)="signOut()">Sign-out</li>
        </ul>
      </li>
      } @else {
      <li nz-menu-item routerLink="/sign-up" [style]="{ float: 'right' }">Sign-up</li>
      <li nz-menu-item routerLink="/sign-in" [style]="{ float: 'right' }">Sign-in</li>
      }
    </ul>
  </nz-header>
  <nz-content>
    <router-outlet></router-outlet>
  </nz-content>
  <nz-footer class="flex justify-between">
    <div id="serverMessage">{{ serverMessage$ | async }}</div>
    <div id="serverTime">{{ serverTime$ | async }}</div>
  </nz-footer>
</nz-layout>

7. Create an E2E test to check the operation of time-related logics

Create a file apps/server-e2e/src/server/time.spec.ts

import { RestClientHelper } from '@nestjs-mod-fullstack/testing';
import { isDateString } from 'class-validator';
import { lastValueFrom, take, toArray } from 'rxjs';

describe('Get server time from rest api and ws', () => {
  jest.setTimeout(60000);

  const correctStringDateLength = '2024-11-20T11:58:03.338Z'.length;
  const restClientHelper = new RestClientHelper();
  const timeApi = restClientHelper.getTimeApi();

  it('should return time from rest api', async () => {
    const time = await timeApi.timeControllerTime();

    expect(time.status).toBe(200);
    expect(time.data).toHaveLength(correctStringDateLength);
    expect(isDateString(time.data)).toBeTruthy();
  });

  it('should return time from ws', async () => {
    const last3ChangeTimeEvents = await lastValueFrom(
      restClientHelper
        .webSocket<string>({
          path: '/ws/time',
          eventName: 'ChangeTimeStream',
        })
        .pipe(take(3), toArray())
    );

    expect(last3ChangeTimeEvents).toHaveLength(3);
    expect(last3ChangeTimeEvents[0].data).toHaveLength(correctStringDateLength);
    expect(last3ChangeTimeEvents[1].data).toHaveLength(correctStringDateLength);
    expect(last3ChangeTimeEvents[2].data).toHaveLength(correctStringDateLength);
    expect(isDateString(last3ChangeTimeEvents[0].data)).toBeTruthy();
    expect(isDateString(last3ChangeTimeEvents[1].data)).toBeTruthy();
    expect(isDateString(last3ChangeTimeEvents[2].data)).toBeTruthy();
  });
});

8. We launch the infrastructure with applications in development mode and check the operation through E2E tests

Commands

npm run pm2-full:dev:start
npm run pm2-full:dev:test:e2e

Conclusion

In the current post and project, when sending time via a web socket, there is no user authorization check and the web socket stream is available to any user, in a real application there are usually many web socket streams that check the authorization token.

Perhaps in the next posts there will be an example with authorizations, but the preparatory code is also in the current version (search for: handleConnection).

Plans

In the next post I will add handling of server validation errors on the frontend...

DEV Community: Ilshat Khamitov

My RAG System: How I Built a RAG for My Business Card Website in 8 Days

Why I did this

Why RAG turned out to be more complicated than it seemed

System Architecture

Choosing a Stack

Key Architectural Decision: Hierarchical Filtering

The biggest technical challenge

Why the first version was slow

Prompts and Errors

Using AI in Development

Security

Deployment

Current status

Future Plans

Conclusions

Links

My Dashboard: как я превратил старые Android-устройства в кроссплатформенные дашборды с помощью AI и типобезопасного fullstack

Введение

Цель проекта

Технологический стек

Архитектура и подход

Что удалось достичь в MVP

Выводы и инсайты

Ресурсы и ссылки

My Dashboard

Tech Stack

Technical Specifications

Development Stages

Database

Backend

Frontend

Mobile App

Deployment

Authorization

User Guide

Website

Website Registration

Email Confirmation

Login to the Site

Creating a Dashboard

Adding a clock widget

Adding a habit widget

Widget Preview

Displaying a QR code for linking a mobile device

Mobile App

Downloading and Installing the Mobile App

Linking a Mobile Device to the Dashboard

Changing the Main Clock in the Clock Widget

Completed check mark in the habit widget

Switching to dark theme

Display in Landscape Mode

Unlinking a mobile device

Automation

Releases

TODO Tasks

Notifications

Roadmap

Links

How I Deployed a Full-Stack Application with "NestJS" with "Angular" on "Supabase" and "Vercel"

1. Problems

2. Solution

3. Initial State

4. Current State

5. Implementation Steps

5.1. Transition to Supabase Database

5.2. Transition to Supabase Instead of Redis

5.3. Transition to Supabase Storage

5.4. Transition to Supabase Auth

5.5. Deployment to Vercel

5.6. Environment Variables

5.7. Registration and Authorization in the Cloud

6. Instructions for Running Local Code with External Infrastructure on Supabase

6.1. Initialization

6.2. Preparation

6.3. Running

6.4. Open the Browser

6.5. Testing

6.6. Stopping

Conclusion

5.1. Transition to `Supabase Database`

5.2. Transition to `Supabase` Instead of `Redis`

5.3. Transition to `Supabase Storage`

5.4. Transition to `Supabase Auth`

5.5. Deployment to `Vercel`

6. Instructions for Running Local Code with External Infrastructure on `Supabase`