NestJS 12-də Nələr Yenidir?

NestJS 12 avqustun sonunda çıxdı. Bu, son illərin ən böyük buraxılışlarından biridir: framework ESM-ə keçir, validasiya üçün Standard Schema gəlir, CLI yenidən qurulub və rəsmi observability SDK əlavə olunub.

Yaxşı xəbər: mövcud CommonJS layihələriniz yenidən yazılmadan işləməyə davam edir.

Gəlin əsas yeniliklərə baxaq.

Tələblər

Node.js v20.19+ və ya v22.12+
Node.js v21.x dəstəklənmir

1. ESM-first Paketlər

Bütün əsas Nest paketləri artıq ECMAScript modulları kimi yayımlanır.

CommonJS layihələri Node.js-in require(esm) dəstəyi sayəsində dəyişiklik olmadan işləyir. Öz kodunuzu ESM-ə köçürmək məcburi deyil.

ESM layihəsində main.ts belə görünür:

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module.js";

const app = await NestFactory.create(AppModule);
await app.listen(3000);

Diqqət: nisbi importlarda .js uzantısı yazılır və top-level await işləyir.

2. Standard Schema ilə Validasiya

Ən maraqlı yeniliklərdən biri. @Body(), @Query(), @Param() və @RawBody() dekoratorları indi schema parametri qəbul edir. Zod, Valibot, ArkType — Standard Schema-nı dəstəkləyən istənilən kitabxana işləyir.

import { z } from "zod";

const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

@Post()
create(@Body({ schema: createUserSchema }) body: CreateUserDto) {
  return this.usersService.create(body);
}

Validasiya üçün StandardSchemaValidationPipe-ı qeydiyyatdan keçirmək kifayətdir.

class-validator hələ də işləyir. Sadəcə artıq yeganə seçim deyil.

3. Cavabların Serializasiyası

Eyni yanaşma çıxan cavablar üçün də var — StandardSchemaSerializerInterceptor:

@UseInterceptors(StandardSchemaSerializerInterceptor)
@SerializeOptions({ schema: userResponseSchema })
@Get(":id")
findOne(@Param("id") id: string) {
  return this.usersService.findOne(id);
}

Beləliklə, şifrə kimi həssas sahələrin cavaba düşməsinin qarşısını sxem səviyyəsində alırsınız.

4. ConfigModule də Standard Schema-ya Keçdi

@nestjs/config artıq yalnız Joi ilə bağlı deyil:

ConfigModule.forRoot({
  validationSchema: z.object({
    NODE_ENV: z
      .enum(["development", "production", "test"])
      .default("development"),
    PORT: z.coerce.number().default(3000),
  }),
});

Joi istifadə edirsinizsə: Joi v18+-a yeniləyin və ayarları validationOptions.libraryOptions altına köçürün.

5. Maşın Oxuya Bilən Error Kodları

Frontend-də error mesajının mətni ilə if yazmaq tanışdır? Artıq lazım deyil:

throw new BadRequestException("Password is too weak", {
  errorCode: "WEAK_PASSWORD",
});

Mesaj dəyişə və ya tərcümə oluna bilər, errorCode isə sabit qalır.

6. Strukturlaşdırılmış Logging

ConsoleLogger adi obyektləri strukturlaşdırılmış parametr kimi qəbul edir:

this.logger.log("User signed in", { userId: 1, method: "oauth" });

JSON rejimində parametrlər default olaraq params açarı altına düşür. Kök səviyyədə görmək üçün flattenParams aktiv edin.

Köhnə davranışı qaytarmaq üçün: structuredParams: false.

7. Route Konfliktlərinin Aşkarlanması

Bir route-un digərini "gizlətməsi" çətin tapılan baglardandır. v12-də bunu açıq şəkildə yoxlaya bilərsiniz:

const app = await NestFactory.create(AppModule, {
  routeConflictPolicy: { duplicate: "error", shadow: "warn" },
  routeResolutionStrategy: "specificity",
});

8. Native Observability: @nestjs/observe

Rəsmi SDK request lifecycle-a birbaşa qoşulur. HTTP serveri patch etmir:

export const { ObserveModule, ObserveInstrument } = createObserveModule();

const app = await NestFactory.create(AppModule, {
  instrument: ObserveInstrument,
});

Avtomatik əhatə edir:

HTTP, GraphQL, gRPC
Microservice transportları
Queue consumer-lər və cron job-lar

9. Yeni CLI və Toolchain

Nə	v11	v12 (ESM layihə)
Test	Jest	Vitest
Linter	ESLint	oxlint
Monorepo bundler	Webpack	Rspack
Package manager-lər	npm/yarn/pnpm	+ bun

CommonJS layihələri Jest və ESLint ilə qalır. Webpack deprecated oldu — --builder rspack istifadə edin.

Yeni əmrlər:

nest upgrade — v11 layihəsini v12-yə avtomatik köçürür
nest deploy — tətbiqi deploy edir

Yeni build parametrləri: --rspackPath, --emit-declarations, --no-type-check, --silent, --parallel.

10. Microservices, GraphQL və WebSocket

NATS v3 — @nats-io/transport-node paketi ilə
Kafka — @MessagePattern() və @EventPattern() RegExp qəbul edir
Pre-request hook — message handler-dən əvvəl işləyir
gRPC — status kodlarına uyğun exception filter-lər
GraphQL — default IDE artıq GraphiQL-dir
WebSocket — request-scoped gateway-lər və handleDisconnect-də ayrılma səbəbi
Express — graceful shutdown: işləyən request-lər bitənə qədər gözləyir

Breaking Changes

Yeniləmədən əvvəl bunları yoxlayın:

Node.js versiyası — v20.19+ və ya v22.12+
Lifecycle hook-lar — artıq modul iyerarxiyası səviyyəsinə görə çağırılır. Init/teardown ardıcıllığına baxın
GraphQL — subscriptions-transport-ws silindi, graphql-ws-ə keçin. playground → graphiql
NATS — packet-lər JSON string kimi serializasiya olunur
Custom pipe-lar — ArgumentMetadata artıq generic-dir, imzaları yeniləyin

Necə Yeniləmək Olar?

npm i -g @nestjs/cli@latest @nestjs/schematics@latest
npm i @nestjs/cli@latest @nestjs/schematics@latest
nest upgrade --dry-run
nest upgrade

Əvvəlcə --dry-run ilə dəyişikliklərə baxın. Mexaniki dəyişiklikləri CLI edir, custom kodu isə özünüz yoxlamalısınız.

ESM-ə keçmək istəsəniz (opsional)

package.json-a "type": "module" əlavə edin
tsconfig.json-da "module" və "moduleResolution" → "nodenext"
Nisbi importlara .js uzantısı əlavə edin
__dirname → import.meta.dirname

Nəticə

NestJS 12 ekosistemi ESM, Standard Schema və daha sürətli alətlər tərəfə aparır.
Mövcud layihələr üçün keçid yumşaqdır: nest upgrade işin çoxunu görür.
Mənim tövsiyəm: yeni layihələri ESM + Zod ilə başladın, köhnələri isə əvvəlcə CommonJS-də saxlayaraq v12-yə yeniləyin.

elchinabilov.