DEV Community: Костя Третяк

Testing "quickie posts" on dev.to

Костя Третяк — Sat, 30 Nov 2024 10:32:32 +0000

NestJS vs. Ditsmod: pipe features

Костя Третяк ・ Oct 3

NestJS vs. Ditsmod: pipe features

Костя Третяк — Thu, 03 Oct 2024 13:00:31 +0000

In reality, pipes only exist in NestJS, while in Ditsmod there is no need for a separate entity like "pipes" because the so-called FactoryProviders can easily cover similar functionality. Moreover, FactoryProviders have much broader capabilities, so pipes are merely a subset of what they can achieve.

Pipes in NestJS

As stated in the NestJS documentation, pipes perform two functions: transformation and validation.

In the following example, a controller method sets up a route with the parameter id, which is of type number:

import { Сontroller, Get, Param, ParseIntPipe } from '@nestjs/common';

@Сontroller()
class ExampleController {
  @Get(':id')
  async findOne(@Param('id', ParseIntPipe) id: number) {
    return this.catsService.findOne(id);
  }
}

As you can see, the first argument passed to the @Param() decorator is the name of the parameter to check, in this case, id. The second argument is the ParseIntPipe class. The pipe class itself may contain code like the following:

import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';

@Injectable()
export class ParseIntPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    const num = Number(value);
    if (isNaN(num)) {
      const msg1 = `"${metadata.data}" in the path parameters must have the Number data type.`;
      throw new TypeError(msg1);
    }
    return num;
  }
}

In the pipe class, the transform method must be implemented, which accepts the raw value from the client as the first argument and metadata as the second argument, following this interface:

interface ArgumentMetadata {
  type: 'body' | 'query' | 'param' | 'custom';
  metatype?: Type<unknown>; // String, Number, etc.
  data?: string; // property name, for example 'id'
}

What the transform method returns will be received by the controller method.

In addition to the usage described above, NestJS has another use of pipe application:

@Post()
@UsePipes(new ZodValidationPipe(createCatSchema))
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

In this example, a controller method sets up a route that accepts a request body. Here, the pipe instance is passed directly in the @UsePipes() decorator. This way, the pipe's transform method receives the request body and validates it based on a prepared Zod schema.

As of now, NestJS still does not support pipes for request headers.

"Pipes" in Ditsmod

Unlike NestJS, Ditsmod does not have a specific architectural entity like pipes. Instead, it has FactoryProviders, which are passed into the module or controller metadata like this:

import { rootModule } from '@ditsmod/core';
import { ParseIntPath } from './path-params-parsers.js';

@rootModule({
  // ...
  providersPerReq: [{ token: ParseIntPath, useFactory: [ParseIntPath, ParseIntPath.prototype.transform] }],
})
class AppModule {}

As you can see, we pass the ParseIntPath class as the provider's token, and its value will be what its transform() method returns. The ParseIntPath code could look like this:

import { inject, AnyObj, PATH_PARAMS, CTX_DATA, CustomError, Status } from '@ditsmod/core';

export class ParseIntPath {
  transform(@inject(PATH_PARAMS) pathParams: AnyObj, @inject(CTX_DATA) propertyName: string) {
    const num = Number(pathParams[propertyName]);
    if (isNaN(num)) {
      const msg1 = `"${propertyName}" in the path parameters must have the Number data type.`;
      throw new CustomError({ msg1, status: Status.BAD_REQUEST, level: 'debug' });
    }
    return num;
  }
}

Here, the @inject decorator is used before the method parameters, asking Ditsmod to provide values for the PATH_PARAMS and CTX_DATA tokens. The first token is self-explanatory, while the second is a special token used to get contextual data passed to the @inject decorator alongside ParseIntPath.

In the following example, a controller method sets up a route with the parameter id, which is of type number:

import { controller, route, Res } from '@ditsmod/core';
import { ParseIntPath } from './path-params-parsers.js';

@controller()
class ExampleController {
  @route('GET', ':id')
  findOne(res: Res, @inject(ParseIntPath, 'id') id: number) {
    res.sendJson({ id });
  }
}

Note that the @inject decorator takes a string as the second argument, representing the path parameter name. This way, ParseIntPath retrieves the value via the CTX_DATA token (this feature is available in Ditsmod starting from v2.59.1). Keep in mind that when @inject receives two arguments, the DI will not use a cache to search for the token's value.

If we compare this to the NestJS controller mentioned above, the syntax of the two controllers seems similar. However, using ParseIntPath as a provider to function as a "pipe" is just one way to utilize providers in Ditsmod. Methods of controllers in Ditsmod bound to routes can request any other provider.

Currently, this is not possible in NestJS, as controller methods can only request data via decorators like @Param, @Query, and @Body. Even the @Headers decorator is still unavailable in NestJS, and the framework's author has not yet expressed an intention to add it.

Conclusion

Compared to NestJS, Ditsmod offers broader provider capabilities, eliminating the need for a separate entity like pipes, which require additional learning and cannot be exported from a module. Moreover, controller methods in Ditsmod are not subject to the same restrictions found in NestJS. Essentially, Ditsmod's controller methods can receive any providers, just like in constructors of controllers or services. This adds consistency and simplicity to Ditsmod's architecture.

A quick overview of Bun's basic features and how it compares to Node.js

Костя Третяк — Wed, 28 Aug 2024 06:12:00 +0000

Bun is a JavaScript runtime, positioned by its author as a set of ready-to-use tools "out of the box" provided along with the JavaScript runtime: this includes a package manager, a bundler, and a test runner. Additionally, the author strives to offer strong TypeScript support so that there’s no need to compile TypeScript files into JavaScript files. It's been almost a year since the first version of Bun was released. In this short post, I will examine how well the claimed features align with reality and the performance it delivers.

Installing Bun

As shown on Bun's main page, on Linux or macOS, it can be installed as follows:

curl -fsSL https://bun.sh/install | bash

It can be upgraded to the next stable version with:

bun upgrade --stable

Cloning the Repository with Benchmark Code

In this article, we will use the code that can be found in my repository. Clone it, navigate to the new directory, and install dependencies:

git clone https://github.com/KostyaTretyak/bun-vs-node.git
cd bun-vs-node
bun install

Additionally, install the wrk benchmarking utility on your computer.

Comparing the Speed of Bun's Native Web Server and Node.js

Node.js on single process

First, let's see what Node.js shows, and then compare these results with Bun benchmarks. So, in the first terminal, run the node.mjs file:

node node.mjs

On my machine, the cold start takes about 5ms.

Now, in the second terminal, run the benchmark:

wrk -H 'Connection: keep-alive' --latency -d 5 -c 256 --timeout 8 -t 4 http://localhost:3000/plaintext

This command makes requests in four threads, with a concurrency of 256, for a duration of 5 seconds. On my machine, the average result is as follows:

Running 5s test @ http://localhost:3000/plaintext
  4 threads and 256 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency    73.32ms  222.54ms   1.83s    92.72%
    Req/Sec     4.50k   665.94     6.39k    76.50%
  Latency Distribution
     50%   13.74ms
     75%   14.93ms
     90%   79.47ms
     99%    1.23s 
  89513 requests in 5.02s, 16.39MB read
Requests/sec:  17846.79
Transfer/sec:      3.27MB

So, about 17 thousand requests per second.

Node.js with cluster mode

Now let's try using the cluster mode. To do this, go back to the first terminal, stop the process by pressing Ctrl+C, and run the following:

node node-cluster.mjs

On my machine, it has 4 cores, and each process in the cluster starts twice as slowly - about 10ms on average.

Now, run the benchmark again:

wrk -H 'Connection: keep-alive' --latency -d 5 -c 256 --timeout 8 -t 4 http://localhost:3000/plaintext

This time, the results are as follows:

Running 5s test @ http://localhost:3000/plaintext
  4 threads and 256 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     9.03ms   18.69ms 345.62ms   97.60%
    Req/Sec     9.26k     1.55k   12.23k    83.50%
  Latency Distribution
     50%    6.42ms
     75%    8.32ms
     90%   10.85ms
     99%   85.68ms
  184883 requests in 5.03s, 33.85MB read
Requests/sec:  36720.73
Transfer/sec:      6.72MB

So, 36 thousand requests per second, which is slightly more than twice as fast compared to running on a single core without cluster mode.

Bun on single process

Now let's run the same benchmarks with Bun. Go to the first terminal, press Ctrl+C, and run:

bun bun.mjs

The process starts in about 4ms (almost as fast as in Node.js). When running the same benchmark with wrk, the following result is obtained:

Running 5s test @ http://localhost:3000/plaintext
  4 threads and 256 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     5.42ms  769.54us  26.37ms   93.00%
    Req/Sec    11.87k     0.86k   12.95k    75.00%
  Latency Distribution
     50%    5.28ms
     75%    5.80ms
     90%    6.04ms
     99%    6.77ms
  236197 requests in 5.04s, 31.99MB read
Requests/sec:  46849.13
Transfer/sec:      6.34MB

So, Bun handles 46 thousand requests per second on a single core, which is 2.5 times faster compared to Node.js.

Bun with cluster mode

Again, go to the first terminal, press Ctrl+C, and run:

bun bun-cluster.mjs

We see that in cluster mode, Bun's processes start just as quickly as without cluster mode.

Now, run the benchmark with wrk again, and the following result is obtained:

Running 5s test @ http://localhost:3000/plaintext
  4 threads and 256 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     3.09ms    2.08ms  32.22ms   70.02%
    Req/Sec    19.97k     1.99k   27.94k    85.50%
  Latency Distribution
     50%    2.86ms
     75%    4.16ms
     90%    5.70ms
     99%    9.41ms
  399353 requests in 5.07s, 54.08MB read
Requests/sec:  78753.89
Transfer/sec:     10.66MB

So, 78 thousand requests per second. There is a performance increase, but only about 1.5 times compared to non-cluster mode. However, this is twice as fast as Node.js in cluster mode.

Describing a summary from my benchmarking experience, I can say that these are the best results comparing "Bun vs Node.js". It seems that Bun's web server is twice (or sometimes four times) faster, but this speed does not extend to all code. As you gradually increase the amount of JavaScript code in your application, Bun's performance will quickly degrade.

And when Bun works with database code, it shows noticeably worse results compared to Node.js. As far as I understand, this happens due to the significant amount of JavaScript code in database drivers.

How Bun Works with ExpressJS

Run it with the following command:

bun express.mjs

On my machine, Bun launches this code in about 10ms, while Node.js launches it in 4ms, meaning Node.js has a 2.5 times faster cold start.

However, Bun has a special feature designed to minimize startup time. To use it, create an executable file using the following command:

bun build ./express.mjs --compile --minify --outfile mycli

It will generate a mycli file from express.mjs, which can be run as follows:

./mycli

On my machine, this file launches slightly slower (about one millisecond slower) than the uncompiled file. However, this feature is primarily intended for large projects, so no optimization for cold start is noticeable in minimal code. However, the speed of the compiled file is slightly higher.

How Bun Works with Ditsmod

If you clone the seeds from Ditsmod and install the dependencies:

git clone --depth 1 https://github.com/ditsmod/seed.git my-app
cd my-app
bun install

And try to immediately run the application using Bun:

bun run build
bun dist/main.js

It will throw the following error:

1 | (function (entry, fetcher)
    ^
SyntaxError: export 'ValueProvider' not found in './types-and-models.js'

This bug is easily fixed - just delete all tsconfig files from node_modules/@ditsmod:

rm node_modules/@ditsmod/*/tsconfig.json

That's it, now Bun works as expected:

bun dist/main.js

Summary

Personally, I don't yet see any significant advantages for switching to Bun. It has fast dependency installation, a fast web server, and possibly fast SQLite. If you open its repository, you can see that the number of bugs is overwhelming, so the Bun team has a hard time handling them.

If nothing significant happens in Bun's development over the next year, it will be unpromising for me.

@ts-stack/multer simplifies uploading files to a Node.js-based backend

Костя Третяк — Mon, 29 Jul 2024 05:17:02 +0000

This package is actually a fork of the well-known native package for ExpressJS multer v2.0.0-rc.4. It will be interesting primarily to those developers who prefer Promise-style programming instead of middleware. In addition, it is also important that this package is written in TypeScript, so the type support and context documentation in it is top notch.

Install

Make sure you have Node.js >= v20.0.6 installed. The package can be installed with the following command:

npm install @ts-stack/multer

Usage

Multer returns an object with four properties: textFields, file, files and groups. The textFields object contains the values of the text fields of the form, the file, files or groups object contains the files (as Readable stream) uploaded via the form.

The following example uses ExpressJS only for simplicity. In fact, @ts-stack/multer does not return middleware, so it is less convenient for ExpressJS than the original module. Basic usage example:

import { Multer } from '@ts-stack/multer';
import express from 'express';
import { createWriteStream } from 'node:fs';

// Here `avatar`, `photos` and `gallery` - is the names of the field in the HTML form.
const multer = new Multer({ limits: { fileSize: '10MB' } });
const parseAvatar = multer.single('avatar');
const parsePhotos = multer.array('photos', 12);
const parseGroups = multer.groups([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }]);
const app = express();

app.post('/profile', async (req, res, next) => {
  const parsedForm = await parseAvatar(req, req.headers);
  // parsedForm.file is the `avatar` file
  // parsedForm.textFields will hold the text fields, if there were any
  const path = `uploaded-files/${parsedForm.file.originalName}`;
  const writableStream = createWriteStream(path);
  parsedForm.file.stream.pipe(writableStream);
  // ...
});

app.post('/photos/upload', async (req, res, next) => {
  const parsedForm = await parsePhotos(req, req.headers);
  // parsedForm.files is array of `photos` files
  // parsedForm.textFields will contain the text fields, if there were any
  const promises: Promise<void>[] = [];
  parsedForm.files.forEach((file) => {
    const promise = new Promise<void>((resolve, reject) => {
      const path = `uploaded-files/${file.originalName}`;
      const writableStream = createWriteStream(path);
      writableStream.on('error', reject);
      writableStream.on('finish', resolve);
      file.stream.pipe(writableStream);
    });
    promises.push(promise);
  });

  await Promise.all(promises);
  // ...
});

app.post('/cool-profile', async (req, res, next) => {
  const parsedForm = await parseGroups(req, req.headers);
  // parsedForm.groups is an object (String -> Array) where fieldname is the key, and the value is array of files
  //
  // e.g.
  //  parsedForm.groups['avatar'][0] -> File
  //  parsedForm.groups['gallery'] -> Array
  //
  // parsedForm.textFields will contain the text fields, if there were any
});

In case you need to handle a text-only multipart form, you can use the .textFields() method, example:

import { Multer } from '@ts-stack/multer';
import express from 'express';

const parsetextFields = new Multer().textFields();
const app = express();

app.post('/profile', async (req, res, next) => {
  const parsedForm = await parsetextFields(req, req.headers);
  // parsedForm.textFields contains the text fields
});

Error handling

This is a list of error codes:

const errorMessages = new Map<ErrorMessageCode, string>([
  ['CLIENT_ABORTED', 'Client aborted'],
  ['LIMIT_FILE_SIZE', 'File too large'],
  ['LIMIT_FILE_COUNT', 'Too many files'],
  ['LIMIT_FIELD_KEY', 'Field name too long'],
  ['LIMIT_FIELD_VALUE', 'Field value too long'],
  ['LIMIT_FIELD_COUNT', 'Too many fields'],
  ['LIMIT_UNEXPECTED_FILE', 'Unexpected file field'],
]);

You can see these error codes in the MulterError#code property:

import { Multer, MulterError, ErrorMessageCode } from '@ts-stack/multer';

// ...
try {
  const multer = new Multer().single('avatar');
  const parsedForm = await multer(req, req.headers);
  // ...
} catch (err) {
  if (err instanceof MulterError) {
    err.code // This property is of type ErrorMessageCode.
    // ...
  }
}

The "@ts-stack/body-parser" package passes the parsing results via a Promise

Костя Третяк — Mon, 22 Jul 2024 08:13:59 +0000

The package @ts-stack/body-parser is a fork of body-parser - the native ExpressJS package. It is written in TypeScript in ESM format, without support for older versions of Node.js < v20.6.0. To install it, run the following command:

npm install @ts-stack/body-parser

This package parses the body of an HTTP request that has the following types: JSON, Raw, Text, URL-encoded. You can use it as follows:

import http from 'http';
import { getJsonParser } from '@ts-stack/body-parser';

const jsonParser = getJsonParser({ limit: '1kb' });

http.createServer(async function (req, res) {
  try {
    const body = await jsonParser(req, req.headers);
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain')
    res.write('you posted:\n');
    res.end(JSON.stringify(body));
  } catch (err: any) {
    // handling an error
  }
});

Alternatively, you can use the BodyParserGroup helper. It is designed for cases when you do not know which parser is needed for a specific route. When creating an instance of the BodyParserGroup class, you can pass options for the corresponding parsers, after which you can use the parse method as follows:

import { BodyParserGroup } from '@ts-stack/body-parser';

const bodyParserGroup = new BodyParserGroup({
  jsonOptions: config.jsonOptions,
  textOptions: config.textOptions,
  urlencodedOptions: config.urlencodedOptions,
  rawOptions: config.rawOptions,
});

const body = await bodyParserGroup.parse(req, req.headers, {});

Passing metadata from TypeScript code to JavaScript code using decorators for Dependency Injection

Костя Третяк — Thu, 04 Jul 2024 12:51:40 +0000

When TypeScript decorators are used for Dependency Injection, they are needed for two things. First, they signal to the TypeScript compiler that it needs to read TypeScript types, transform them into JavaScript code, and save them. Second, if additional metadata is passed to the decorator factory, it must also be stored. This may surprise many, but in the first case, decorators are not used for their intended purpose in relation to how they should be used in JavaScript code.

Configuring TypeScript projects for Dependency Injection

If you want to take advantage of TypeScript for Dependency Injection, you need to write the following in your tsconfig files:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

In addition, you need to add the reflect-metadata library as a project dependency, and also import it in the entry file (usually this file is called main.ts):

// main.ts
import "reflect-metadata";

// Your code here...

Please note that such an import must be unique for your entire project. In addition, for testing it is also necessary to make such an import if there is no main.ts import in a particular test.

Unusual use of decorators in TypeScript projects

You may be wondering why the use of decorators might be unusual. Let's look at the simplest example first without a decorator and then with a fake decorator. So, let's say you have two classes, and the second class depends on the first class:

import "reflect-metadata";

class Service1 {}

class Service2 {
  constructor(public service1: Service1) {}
}

If we run the TypeScript compiler on this file, it will output the following JavaScript code:

class Service1 {
}
class Service2 {
    service1;
    constructor(service1) {
        this.service1 = service1;
    }
}
export {};

As you can see, without decorators, the TypeScript compiler does not transfer information about what type the service1 property in Service2 should be to the JavaScript code. In this case, this information is actually lost during compilation.

Now let's add any decorator:

import "reflect-metadata";

class Service1 {}

@(fakeDecorator as any)
class Service2 {
  constructor(public service1: Service1) {}
}

function fakeDecorator() {}

This time, the TypeScript compiler will already output the following JavaScript code:

var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
var __metadata = (this && this.__metadata) || function (k, v) {
    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
};
class Service1 {
}
let Service2 = class Service2 {
    service1;
    constructor(service1) {
        this.service1 = service1;
    }
};
Service2 = __decorate([
    fakeDecorator,
    __metadata("design:paramtypes", [Service1])
], Service2);
function fakeDecorator() { }
export {};

As you can see, the very presence of any decorator at the class level signals the TypeScript compiler that it needs to transfer information about the constructor parameters of this class to the JavaScript code. This information is stored using the reflect-metadata library, more precisely - using the Reflect class from this library.

As you can guess, now it remains to read the stored information using the same class Reflect.

Conclusion

Therefore, if there is any decorator at the class level, the TypeScript compiler passes metadata from the TypeScript code to the JavaScript code using its own decorator, and the user-defined decorator is called dynamically within its own decorator body. Thus, you can use a function with an empty body as a decorator, but the TypeScript compiler will still transfer the metadata into the JavaScript code.

Who knows the general current statistics on dev.to?

Костя Третяк — Sun, 16 Jul 2023 11:07:41 +0000

Although I have published 10 posts on dev.to since 2021, the statistics of views of these posts are very demotivating, because they get only a few dozen views for the whole time, up to a maximum of 200. For my posts, I use such popular tags as #node, #nestjs, #typescript (and the unpopular #ditsmod tag).

In general, few articles marked with these tags are published on dev.to per day. If you believe the statistics provided by similarweb, dev.to has 12.4 million visits per month. Given that users are most active on weekdays, we can assume that dev.to has about 12400/22 ~ 560K visits per day.

Thus, all posts on dev.to have approximately 560K visits per day. Unfortunately, I don't know the number of followers to the tags I've specified. But a tag like #node should theoretically have a lot of followers.

So, why is the number of views of posts marked with popular tags so low?

NestJS vs. Ditsmod: injection scopes

Костя Третяк — Wed, 05 Jul 2023 13:30:59 +0000

Good application modularity is closely related to the injector tree hierarchy that Dependency Injection (DI) creates.

This article uses NestJS v10.0 and Ditsmod v2.38 for comparison. I am the author of Ditsmod.
DI injectors are sometimes referred to as DI containers, but since NestJS and Ditsmod have borrowed many concepts from Angular, this post will use the term "injectors" as it does in Angular.

Scopes in NestJS

In NestJS, there are no explicitly defined levels of the DI injector hierarchy, but there are scopes that implicitly refer to such a hierarchy:

DEFAULT - A single instance of the provider is shared across the entire application. The instance lifetime is tied directly to the application lifecycle. Once the application has bootstrapped, all singleton providers have been instantiated. Singleton scope is used by default.
REQUEST - A new instance of the provider is created exclusively for each incoming request. The instance is garbage-collected after the request has completed processing.
TRANSIENT - Transient providers are not shared across consumers. Each consumer that injects a transient provider will receive a new, dedicated instance.

It appears that NestJS v10.0 does not yet have the ability to instantiate providers at the module level. This leads to a degradation of the modularity of applications:

DI injector hierarchy in Ditsmod

Ditsmod has 4 static levels of DI injector hierarchy:

Application level. Providers are instantiated only once during the application's life cycle (this is the equivalent of the DEFAULT scope in NestJS, but in Ditsmod this is instantiated on the first request, while in NestJS the instance is instantiated at application startup);
Module level. The provider instance is created once for each module;
Route level. The provider instance is created once for each route;
HTTP request level. A provider instance is created once for each HTTP request (this is the equivalent of the REQUEST scope in NestJS).

In addition, at each of these levels, Ditsmod has the ability to create a new instance of a particular provider each time without using the injector cache (this is the equivalent of the TRANSIENT scope in NestJS).

Features of controllers in NestJS

By default, NestJS instantiates a controller as a singleton. While this feature can improve application performance by several percent, it also increases the likelihood of "shooting yourself in the foot" when the developer creates a property in the controller for a particular HTTP request:

@Controller()
export class CatsController {
  private propertyWithRequestContext: any;

  @Get()
  method1() {
    // Works with this.propertyWithRequestContext
  }
}

Now, if 10 requests come to method1(), they will all overwrite propertyWithRequestContext and interfere with each other.

In addition, if a default-scoped controller has a dependency on a request-scoped service, then such a controller automatically (without warning) becomes request-scoped as well. In this way, the developer cannot rely on properties in the controller at all, because it is not clear what scope the controller will have as a result. Also, if the service is transient-scoped, then a similar scope change will not occur in the controller, introducing additional inconsistency into the NestJS architecture.

Features of controllers in Ditsmod

A controller instance is created for each HTTP request. Regardless, performance with this controller is about the same as NestJS + Fastify with the default scope. When an application-level service tries to get a request-scoped service, Ditsmod throws an error that the service is not found (the injector higher in the hierarchy does not see its child injectors).

Getting current injector

The NestJS documentation says:

Occasionally, you may want to resolve an instance of a request-scoped provider within a request context. Let's say that CatsService is request-scoped and you want to resolve the CatsRepository instance which is also marked as a request-scoped provider. In order to share the same DI container sub-tree, you must obtain the current context identifier instead of generating a new one

In the following example, the isSameInjector() method compares the CatsRepository instance that NestJS returns in the constructor with the instance returned by the this.moduleRef.resolve() method. If NestJS uses the same injector in both cases, isSameInjector() should return true:

import { REQUEST, ModuleRef, ContextIdFactory } from '@nestjs/core';
import { CatsRepository } from './cats-repository';

@Injectable()
export class CatsService {
  constructor(
    @Inject(REQUEST) private request: Record<string, unknown>,
    private moduleRef: ModuleRef,
    private catsRepository: CatsRepository
  ) {}

  async isSameInjector() {
    const contextId = ContextIdFactory.getByRequest(this.request);
    const catsRepository = await this.moduleRef.resolve(CatsRepository, contextId);
    return catsRepository === this.catsRepository;
  }
}

In Ditsmod, the same thing can be done much easier, because if CatsService and CatsRepository are request-scoped, they share the same injector:

import { injectable, Injector } from '@ditsmod/core';
import { CatsRepository } from './cats-repository';

@injectable()
export class CatsService {
  constructor(
    private injector: Injector,
    private catsRepository: CatsRepository
  ) {}

  isSameInjector() {
    const catsRepository = this.injector.get(CatsRepository);
    return catsRepository === this.catsRepository;
  }
}

Conclusion

If you like NestJS, chances are you'll like Ditsmod more.

DI providers collision in Ditsmod applications

Костя Третяк — Tue, 21 Feb 2023 11:35:29 +0000

During the process of importing Ditsmod modules, there may be a situation where among these modules there can be two (or more) modules that export non-identical providers with the same token. For example, a provider with the token Service1 can be exported from two modules simultaneously to the current module, in which case the developer may not know which version of the provider will be used. To avoid such ambiguity, Ditsmod throws an error.

This feature is especially useful when importing third-party modules and you don’t have the ability to control the import order. Now let’s take a closer look at when a provider collision can occur.

Imagine you have Module3 where you imported Module2 and Module1. You did this import because you need Service2 and Service1 from these modules, respectively. You are viewing how these services work, but for some reason Service1 does not work as expected. You start debug and it turns out that Service1 exports both modules: Module2 and Module1. You expected that Service1 would only be exported from Module1, but the version exported from Module2 actually worked.

To prevent this from happening, if you import two or more modules that export non-identical providers with the same token, Ditsmod will throw the following error:

Error: Importing providers to Module3 failed: exports from Module2 and Module1 causes collision with Service1. If Module3 declared in your application (it is not imported from node_modules), you should add Service1 to resolvedCollisionsPer* in this module. For example: resolvedCollisionsPerReq: [ [Service1, Module1] ].

Specifically in this case:

Module2 substitute and then exports the provider with the token Service1;
and Module1 substitute and then exports the provider with the token Service1;
providers with token Service1 are not identical in Module2 and Module1, ie from module Module2 can be exported, for example, object { token: Service1, useValue: {} }, and from Module1Service1 can be exported as a class.

And since both of these modules are imported into Module3, this causes a "provider collisions", because the developer may not know which of these substitutions will work in Module3.

Collision resolution

If Module3 is declared in your application (it is not imported from node_modules), the collision is resolved by adding to resolvedCollisionsPer* an array of two elements, with the provider's token in the first place and the module from which the provider needs to be taken in the second place:

import { Module1, Service1 } from './module1';
import { Module2 } from './module2';

@featureModule({
  imports: [Module2, Module1],
  resolvedCollisionsPerReq: [ [Service1, Module1] ]
})
export class Module3 {}

If you have installed Module3 using packages manager (npm, yarn, etc.), there is no point in modifying this module locally to resolve the collision.

This situation can only occur if Module2 and Module1 are exported from the root module, so you need to remove one of these modules from there. And, of course, after that you will have to explicitly import another module into those modules where it is needed.

NestJS vs. Ditsmod: features of the router

Костя Третяк — Fri, 02 Dec 2022 02:40:21 +0000

The description of NestJS specifically states that this framework was designed for "scalable server-side applications". Surprisingly, only in the eighth version it began to support prefixes at the module level, and this feature has a number of significant limitations.

In this post, NestJS v9.2 and Ditsmod v2.27 are used for comparison. A finished example with nested routes in Ditsmod can be viewed on github. I am the author of Ditsmod.

In addition to the slow implementation of nested routes in NestJS, its router even now (in the ninth version) does not care about collisions of path in routes. If you are writing a large project and accidentally duplicated a path, the NestJS router will not tell you anything about it. Likewise, it won't say anything if you accidentally duplicated the parameter name: one/:two/:two. It's especially easy to make such duplicates when you use third-party modules. Although this is how the Express router works, NestJS could fix this if it positions itself as a framework for "scalable server-side applications".

Currently, NestJS does not support the ability to import a module while simultaneously adding guards to routes of this module. This feature can also be very useful in large projects, especially for importing third-party modules.

Unlike NestJS, Ditsmod has been able to add prefixes at the module level since the first version. For example, to serve /posts/:postId, the parent module is imported as follows:

import { rootModule } from '@ditsmod/core';
import { PostsModule } from './posts/posts.module';

@rootModule({
  appends: [
    { path: 'posts/:postId', module: PostsModule }
    // ..
  ],
})
export class AppModule {}

And to import the child module serving /posts/:postId/comments/:commentId, in Ditsmod it is done as follows:

import { featureModule } from '@ditsmod/core';
import { CommentsModule } from './comments/comments.module';

@featureModule({
  appends: [{ path: 'comments/:commentId', module: CommentsModule }],
  // ...
})
export class PostsModule {}

In Ditsmod, appends is a lightweight version of imports that only allows you to appending modules, inheriting only the prefix of the current module. No providers or extensions are imported in this case.

Starting with the eighth version, NestJS can create nested routes in a similar way:

@featureModule({
  imports: [
    PostsModule,
    CommentsModule,
    RouterModule.register([
      {
        path: 'posts',
        module: PostsModule,
        children: [
          {
            path: ':postId/comments/:commentId',
            module: CommentsModule
          },
        ]
      },
    ]),
  ],
  // ...
})
export class AppModule {}

But there are the following limitations:

Such configuration import can be done only once for the entire application.
If imported modules have no controllers, all controllers from their child modules are ignored. That is, if there are no controllers in PostsModule from the previous example, then all controllers from CommentsModule will be ignored.
In this case, it is not enough that you pass PostsModule and CommentsModule to the RouterModule.register() method, you also need to directly pass them to the imports array of AppModule data. Moreover, if you do not make such an import, NestJS will not tell you anything about it, but routes from imported modules will not work.

These limitations very significantly reduce the possibility of scaling projects, their modularity.

Conclusion

Statistics show that currently NestJS is downloaded about 1.8 million times per week, which shows how much developers like this framework. NestJS took many concepts from Angular. Likewise, many concepts from Angular were taken to design Ditsmod. As the author of Ditsmod, I may not always be objective, but I try to criticize NestJS constructively. If you have anything to add to this criticism, please do so in the comments.

NestJS vs. Ditsmod: auto-validation

Костя Третяк — Fri, 02 Dec 2022 02:30:09 +0000

NestJS performs input validation using decorators, pipes, and the class-validator utility. For example, if validation is required for path-parameters or query-parameters, the @Param() or @Query() decorators are used for this, respectively, along with the necessary pipes. And if we validate the request body, we need to use the @Body() decorator, as well as the decorators provided by the class-validator utility. Surprisingly, NestJS does not provide similar support for validating headers or cookies. Unlike NestJS, Ditsmod has such support, it uses OpenAPI to describe validation models, and extensions, interceptors, and ajv utility for validation itself.

This post compares NestJS v9.2.0 and Ditsmod v2.54.0. A finished example of validation with the Ditsmod application can be viewed at github. I am the author of Ditsmod.

Turn on validation in NestJS

To globally turn on a native validation pipe in NestJS, you need to use app.useGlobalPipes() method in the main.ts file:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  // ...
}
bootstrap();

Note that the pipe is passed outside the module system, so the ValidationPipe instance cannot be obtained as a dependency via DI. The NestJS documentation suggests a workaround for this:

import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useClass: ValidationPipe,
    },
  ],
})
export class AppModule {}

But right away it is emphasized that such a pipe transfer is global and cannot be done at the module level. In my opinion, this looks rather strange, and also severely limits the modularity of NestJS applications.

Turn on validation in Ditsmod

Since the design of the architecture Ditsmod gives special attention to the concept of modularity, this framework allows you to import a ValidationModule into any single module:

import { featureModule } from '@ditsmod/core';
import { ValidationModule } from '@ditsmod/openapi-validation';

@featureModule({
  imports: [
    ValidationModule
    // ...
  ],
})
export class SomeModule {}

ValidationModule can also be imported globally in the root module:

import { featureModule } from '@ditsmod/core';
import { ValidationModule } from '@ditsmod/openapi-validation';

@featureModule({
  imports: [
    ValidationModule
    // ...
  ],
  exports: [
    ValidationModule
    // ...
  ],
})
export class AppModule {}

Hint: "When Ditsmod exports any module from the root module, it essentially makes it global."

Note that there are currently no pipes in Ditsmod, and there is no need to introduce them into the framework architecture yet, as HTTP interceptors paired with extensions serve their role well.

Description of path-parameters and query-parameters for validation in NestJS

The following example is taken from NestJS documentation, it shows how to describe the path parameter id and the query parameter sort directly in the controller method:

@Get(':id')
findOne(
  @Param('id', ParseIntPipe) id: number,
  @Query('sort', ParseBoolPipe) sort: boolean,
) {
  console.log(typeof id === 'number'); // true
  console.log(typeof sort === 'boolean'); // true
  return 'This action returns a user';
}

As you can see, pipes in NestJS, in addition to validation, also perform transformation to the specified types.

Note that headers and cookies cannot be handled similarly in NestJS. While there are workarounds for this, it's still pretty weird and doesn't add consistency to NestJS.

Description of path-parameters and query-parameters for validation in Ditsmod

Since automatic validation in Ditsmod is based on the OpenAPI documentation, you must first create a model for it:

import { property } from '@ditsmod/openapi';

class Params {
  @property()
  id: number;

  @property()
  sort: boolean;

  @property()
  otherQueryParam: string;

  @property()
  header1: string;

  @property()
  cookie1: string;
}

Now we will use this model in the controller method:

import { controller, inject, PATH_PARAMS, QUERY_PARAMS, Res } from '@ditsmod/core';
import { oasRoute, parameters } from '@ditsmod/openapi';

import { Params } from './models';

interface PathParams {
  id: number;
}

interface QueryParams {
  sort: boolean;
}

@controller()
export class FirstController {
  @oasRoute('GET', ':id', {
    parameters: new Parameters()
      .required('path', Params, 'id')
      .optional('query', Params, 'sort', 'otherQueryParam')
      .optional('header', Params, 'header1')
      .optional('cookie', Params, 'cookie1')
      .getParams(),
  })
  findOne(
    @inject(PATH_PARAMS) pathParams: PathParams,
    @inject(QUERY_PARAMS) queryParams: QueryParams,
    res: Res
  ) {
    console.log(typeof pathParams.id === 'number'); // true
    console.log(typeof queryParams.sort === 'boolean'); // true
    res.send('This action returns a user');
  }
}

As you can see, parameters in headers and cookies are described exactly the same as other parameters in OpenAPI. In this form of writing, the parameter names are controlled by TypeScript, so if you make a typo, TypeScript will tell you about it.

The transformation to the specified types also occurs if the corresponding option is passed during the import of the validation module.

Description of the request body for validation in NestJS

The description of the request body model in NestJS is similar to the description of Ditsmod models, but NestJS uses decorators provided by the utility class-validator. In NestJS, it is customary to name the request body model with the ending *Dto (this is an abbreviation of Data transfer object):

import { IsEmail, IsNotEmpty } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsNotEmpty()
  password: string;
}

@Post()
create(@Body() createUserDto: CreateUserDto) {
  return 'This action adds a new user';
}

The class-validator utility directly performs the validation itself.

Description of the request body for validation in Ditsmod

The description of the request body model in Ditsmod is done similarly to the description of parameters, but it is passed in requestBody.content:

import { property } from '@ditsmod/openapi';

export class CreateUserDto {
  @property()
  email: string;

  @property()
  password: string;
}

This model can now be used in a controller method:

import { controller, inject, Req, Res } from '@ditsmod/core';
import { getContent, oasRoute, property } from '@ditsmod/openapi';
import { HTTP_BODY } from '@ditsmod/body-parser';

import { CreateUserDto } from './models';

@controller()
export class FirstController {
  @oasRoute('POST', 'users', {
    requestBody: {
      content: getContent({ mediaType: 'application/json', model: CreateUserDto }),
    },
  })
  create(res: Res, @inject(HTTP_BODY) body: CreateUserDto) {
    res.sendJson(body); // Returns body back to the client
  }
}

In the @ditsmod/openapi-validation module, at the moment, the utility ajv directly performs the validation itself.

Conclusion

As the author of Ditsmod, I tried to write this framework in a modular and consistent way. It seems to me that NestJS clearly loses in this regard to Ditsmod in many points, in particular to validation. If you think there are significant advantages of NestJS over Ditsmod, please write about it in the comments.

NestJS vs. Ditsmod: features of providers

Костя Третяк — Fri, 02 Dec 2022 01:57:25 +0000

Interceptors, guards, pipes, and exception filters are sometimes referred to as "enhancers" in the NestJS documentation. Although they are all declared with the @Injectable() decorator and can use Dependency Injection, they are not providers. Therefore, they cannot be exported from the module like normal providers.

This article uses NestJS v10.1 and Ditsmod v2.54 for comparison. I am the author of Ditsmod.

I decided to write this article while browsing NestJS issues, in particular A guard with dependencies can't be injected into another module. Its author wonders why NestJS cannot resolve the dependency for AuthGuard because this dependency is imported into the module where the guard is declared.

And the creator of NestJS wrote the following answer:

Enhancers can’t be injected to other providers. Hence, they are not providers. Likewise, enhancers can be tied & injected to the method evaluation context, but you can’t bind providers this way. There’s no reason to change this, especially if you start thinking about enhancers scoped per host (module in which they exist). Adding them to the providers array explicitly creates an unnecessary redundancy and confusion (since enhancers don’t act equally to providers).

So, according to Kamil, adding interceptors, guards, pipes and exception filters to the list of providers will confuse NestJS users. As a result of these restrictions, NestJS applications must export all dependencies for guards from the module, even if those dependencies are not directly used outside the module in which the guards are declared. This restriction essentially breaks module encapsulation.

In Ditsmod, the guards, interceptors, and controller error handlers (analogous to exception filters in NestJS) are normal providers that are passed to the injector at the request level. In next code demonstrates the centralized addition of a guard on OtherModule:

import { featureModule } from '@ditsmod/core';

import { OtherModule } from '../other/other.module';
import { AuthModule } from '../auth/auth.module';
import { AuthGuard } from '../auth/auth.guard';

@featureModule({
  imports: [
    AuthModule,
    { path: 'some-path', module: OtherModule, guards: [AuthGuard] }
  ]
})
export class SomeModule {}

In this example, the AuthModule exports the AuthGuard so that the current module can use this guard as a regular provider.