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

Testing "quickie posts" on dev.to

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

NestJS vs. Ditsmod: pipe features

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

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?

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.

OPTIONS and CORS in Ditsmod application

Костя Третяк — Sun, 09 Oct 2022 03:29:54 +0000

If you haven't heard of the Ditsmod framework, you can check out its documentation.

If your application needs to use the OPTIONS HTTP methods or the CORS or CORS preflight mechanisms, you can use the @ditsmod/cors module.

Install

yarn add @ditsmod/cors

Work with default settings

A finished example with @ditsmod/cors can be viewed in the Ditsmod repository.

The module can work with default settings immediately after import:

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

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

Now all routes in SomeModule will be supplemented with new routes with OPTIONS HTTP method. That is, if SomeModule has GET /users and GET /posts routes, they will be automatically supplemented with OPTIONS /users and OPTIONS /posts routes.

You can check the operation of this module with approximately the following queries:

# Simply OPTIONS request
curl -isS localhost:3000 -X OPTIONS

# OPTIONS CORS request
curl -isS localhost:3000 -X OPTIONS -H 'Origin: https://example.com'

# GET CORS request
curl -isS localhost:3000 -H 'Origin: https://example.com'

# CORS Preflight request
curl -isS localhost:3000 \
-X OPTIONS \
-H 'Origin: https://example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: X-PINGOTHER, Content-Type'

# CORS request with credentials
curl -isS localhost:3000/credentials

Work with custom settings

If you want to change the default settings, during import you can pass some options that will be taken into account at the module level:

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

@featureModule({
  imports: [
    CorsModule.withParams({ origin: 'https://example.com' }),
    // ...
  ],
  // ...
})
export class SomeModule {}

It is also possible to pass CORS options at the route level:

import { featureModule, Providers } from '@ditsmod/core';
import { CorsModule, CorsOpts } from '@ditsmod/cors';

@featureModule({
  imports: [
    CorsModule,
    // ...
  ],
  providersPerRou: [
    ...new Providers()
      .useValue<CorsOpts>(CorsOpts, { origin: 'https://example.com' }),
    // ...
  ],
  // ...
})
export class SomeModule {}

Working with cookies during CORS requests

When you need the CORS HTTP response to contain cookies, and for those cookies to be accepted by web browsers, you can use CorsService:

import { controller, Res, route } from '@ditsmod/core';
import { CorsService } from '@ditsmod/cors';

@controller()
export class SomeController {
  constructor(private res: Res, private corsService: CorsService) {}

  @route('GET')
  getMethod() {
    this.corsService.setCookie('one', 'value for one');
    this.res.send('Some response');
  }
}

As you can see, the cookie is set using the setCookie() method. In this case, the response will contain the Access-Control-Allow-Credentials: true header.

@ditsmod/i18n - a module for translating system messages

Костя Третяк — Sun, 28 Aug 2022 13:20:00 +0000

i18n is an abbreviation of the internationalization. The @ditsmod/i18n module provides basic functionality for translating system messages (issued by the Ditsmod application at runtime) and provides the ability to easily extend dictionaries. In fact, you use ordinary services as dictionaries for translation, so the text for translation can be taken both from TypeScript files and from databases. The work of @ditsmod/i18n is designed so that each current module can have its own translation, and that the translation of any imported module can be changed or supplemented.

You can view the code with examples of the use of @ditsmod/i18n in the Ditsmod repository, although it is more convenient to view it locally, so it is better to clone it first:

git clone https://github.com/ditsmod/ditsmod.git
cd ditsmod
yarn
yarn boot

The example can be run with the command:

yarn start15

Directory structure

In the examples/15-i18n example, there are two modules, each of which has something like the following directory structure with translation files:

└── modulename
    ├── ...
    ├── locales
    │   ├── current
    │   │   ├── _base-en
    │   │   ├── de
    │   │   ├── fr
    │   │   ├── pl
    │   │   ├── uk
    │   │   └── index.ts
    │   └── imported
    │       ├── one
    │       │   ├── de
    │       │   ├── fr
    │       │   ├── pl
    │       │   └── uk
    │       ├── two
    │       │   ├── de
    │       │   ├── fr
    │       │   ├── pl
    │       │   └── uk
    │       └── index.ts

This is the recommended directory structure. As you can see, each module has a translation in the locales folder, which contains two folders:

current - translation for the current module;
imported - changed or supplemented translation for imported modules.

Moreover, only the current folder contains the _base-en folder, which contains basic dictionaries (in this case - in English), from which dictionaries with translations into other languages are branched. An underscore character is used in the name so that _base-en is always above other folders.

Base and extended classes with translations

As already mentioned, dictionaries are ordinary services:

import { Dictionary, ISO639 } from '@ditsmod/i18n';
import { injectable } from '@ts-stack/di';

@injectable()
export class CommonDict implements Dictionary {
  getLng(): ISO639 {
    return 'en';
  }
  /**
   * Hi, there!
   */
  hi = `Hi, there!`;
  /**
   * Hello, ${name}!
   */
  hello(name: string) {
    return `Hello, ${name}!`;
  }
}

This is a basic dictionary with English localization. In this case, it has the name CommonDict, but it is not necessary to place the entire translation in one class, you can use other classes, for example, ErrorDict, EmailDict, etc.

Each basic dictionary must implement the Dictionary interface, which has a single requirement - that the dictionary has a getLng() method that returns the abbreviation of the language name according to the standard ISO 639 (for example, abbreviations for English and Ukrainian languages - en, uk).

Why does the method, and not the property, return the abbreviation of the language names?
The point is that in JavaScript, a class property cannot be viewed until an instance of this class is made. But the getLng() method can be easily viewed through YourClass.prototype.getLng(). This allows you to get statistics of available translations even before using dictionaries.

It is recommended to name each service class with the ending *Dict, and the file with the ending *.dict.ts. In addition, the class name of the base dictionary must not contain locales, and that is why in this case the class is not named CommonEnDict, but CommonDict. This is recommended because the base dictionary class will be used to translate to any other available language. For example, in code the following expression can actually return a translation to any language, despite using the underlying dictionary class as a token:

const dict = this.dictService.getDictionary(CommonDict);
dict.hello('World');

Each dictionary class containing a translation must extend the base dictionary class:

import { ISO639 } from '@ditsmod/i18n';
import { injectable } from '@ts-stack/di';

import { CommonDict } from '@dict/second/common.dict';

@injectable()
export class CommonUkDict extends CommonDict {
  override getLng(): ISO639 {
    return 'uk';
  }

  override hello(name: string) {
    return `Привіт, ${name}!`;
  }
}

At a minimum, every translation dictionary should override the getLng() method. For more strict control of dictionaries with translations, it is recommended to use TypeScript 4.3+, as well as the following setting in tsconfig.json:

{
  "compilerOptions": {
    "noImplicitOverride": true,
    // ...
  }
}

In this case, TypeScript will require the child class to add the override keyword before each method or property from the parent class. This improves the readability of the child class and prevents a mistake in the name of the method or property. If you create a method with an incorrect name, such as helo instead of hello, and mark it as override, TypeScript will issue a warning that no such method exists in the parent class. The same scenario will work if the previously written method has been removed from the parent class.

As you can see, the class names of dictionaries with translations already contain the locale CommonUkDict - this is a dictionary with Ukrainian localization. And since this dictionary extends the base dictionary class, all missing translations will be rendered in the language of the base dictionary. In this case, the base dictionary CommonDict has this property:

/**
 * Hi, there!
 */
hi = `Hi, there!`;

And the CommonUkDict dictionary does not have a translation of this phrase, so when requesting localization into the Ukrainian language, the English version from the base class will be used.

Note that each property or method that is directly used for translation is commented out with the template of the phrase they will return. This adds convenience to using the dictionary in your application code, because your IDE will show these comments:

const dict = this.dictService.getDictionary(CommonDict);
dict.hi;

In this case, when hovering over dict.hi, the IDE will show Hi, there!.

Collection of dictionaries in groups in the current folder

Let me remind you that the current folder contains dictionaries with translations for the current module. These dictionaries must be collected in a single array in the index.ts file:

import { DictGroup, getDictGroup } from '@ditsmod/i18n';

import { CommonDict } from '@dict/second/common.dict';
import { CommonUkDict } from './uk/common-uk.dict';
import { ErrorDict } from '@dict/second/error.dict';
import { ErrorsUkDict } from './uk/errors-uk.dict';
// ...

export const current: DictGroup[] = [
  [CommonDict, CommonUkDict, CommonPlDict, CommonFrDict, CommonDeDict],
  [ErrorDict, ErrorsUkDict, ErrorsPlDict, ErrorsFrDict, ErrorsDeDict],
  // ...
];

As you can see, groups of dictionaries are transferred in the array, where the class with the base dictionary must always go first. In this case, two groups of dictionaries with base classes CommonDict and ErrorDict are transferred. It is not allowed to mix dictionaries from different groups. If you mix dictionaries from different groups, TypeScript won't be able to tell you about it, so it's recommended to use the getDictGroup() function for better control of class types:

import { DictGroup, getDictGroup } from '@ditsmod/i18n';

import { CommonDict } from '@dict/second/common.dict';
import { CommonUkDict } from './uk/common-uk.dict';
import { ErrorDict } from '@dict/second/error.dict';
import { ErrorsUkDict } from './uk/errors-uk.dict';
// ...

export const current: DictGroup[] = [
  getDictGroup(CommonDict, CommonUkDict, CommonPlDict, CommonFrDict, CommonDeDict),
  getDictGroup(ErrorDict, ErrorsUkDict, ErrorsPlDict, ErrorsFrDict, ErrorsDeDict),
  // ...
];

Collection of dictionaries in groups in the imported folder

Let me remind you that the imported directory contains dictionaries with translations for imported modules, and note that it does not contain base dictionaries (it does not have a _base-en folder), since the base dictionaries of imported modules are located in these modules in the current directories:

└── modulename
    ├── ...
    ├── locales
    │   ├── current
    │   │   ├── _base-en
    │   │   ├── de
    │   │   ├── fr
    │   │   ├── pl
    │   │   ├── uk
    │   │   └── index.ts
    │   └── imported
    │       ├── one
    │       │   ├── de
    │       │   ├── fr
    │       │   ├── pl
    │       │   └── uk
    │       ├── two
    │       │   ├── de
    │       │   ├── fr
    │       │   ├── pl
    │       │   └── uk
    │       └── index.ts

The directory imported contains individual folders of each module, for which you need to supplement or rewrite the translation. In this case, the imported folder contains additions or translation rewrites for modules one and two. Collection of groups of dictionaries in the imported folder is similar to how it is done in current, but the base dictionaries are taken from external modules:

import { DictGroup, getDictGroup } from '@ditsmod/i18n';

import { CommonDict } from '@dict/first/common.dict'; // A basic dictionary from an external module from the current folder
import { CommonUkDict } from './first/uk/common-uk.dict'; // Addition of translation for an external module from the imported folder

export const imported: DictGroup[] = [
  getDictGroup(CommonDict, CommonUkDict),
];

In this case, the basic dictionary CommonDict is imported from FirstModule, and the addition of the Ukrainian translation is taken in the current module from the imported folder.

Transfer of translations to the module

Now it remains to transfer groups of dictionaries to the module:

import { featureModule } from '@ditsmod/core';
import { I18nModule, I18nOptions, I18N_TRANSLATIONS, Translations } from '@ditsmod/i18n';

import { current } from './locales/current';
import { imported } from './locales/imported';

const translations: Translations = { current, imported };
const i18nOptions: I18nOptions = { defaultLng: 'uk' };

@featureModule({
  imports: [
    I18nModule,
    // ...
  ],
  providersPerMod: [
    { provide: I18N_TRANSLATIONS, useValue: translations, multi: true },
    { provide: I18nOptions, useValue: i18nOptions },
  ],
  exports: [I18N_TRANSLATIONS]
})
export class SecondModule {}

As you can see, each module containing a translation must:

import I18nModule;
to the providersPerMod array, add a multi-provider containing the I18N_TRANSLATIONS token and content with the Translations data type, where dictionary groups for both the current and the imported module are transferred;
the provider with the token I18nOptions can be transferred to the providersPerMod array;
you can optionally pass the I18N_TRANSLATIONS token to the exports array, if you want the base dictionaries from the current module to be available to external modules. At the same time, please note that such an export is only necessary if you want to directly use the base dictionaries, that is, in the code of your program, you import them. And if you export a certain service that internally uses base dictionaries (encapsulates their use), then you do not need to export I18N_TRANSLATIONS.

If you use the i18nProviders().i18n() helper, you can slightly reduce the amount of code:

import { featureModule } from '@ditsmod/core';
import { I18nModule, I18nProviders } from '@ditsmod/i18n';

import { current } from './locales/current';
import { imported } from './locales/imported';

@featureModule({
  imports: [
    I18nModule,
    // ...
  ],
  providersPerMod: [
    ...new I18nProviders().i18n({ current, imported }, { defaultLng: 'uk' }),
  ],
  exports: [I18N_TRANSLATIONS]
})
export class SecondModule {}

As the first argument for i18nProviders().i18n(), an object of type Translations is passed, options of type I18nOptions are passed in the second place. Note that the helper is preceded by an ellipsis, as it returns an array to be merged with the other providers in the providersPerMod array.

Use of dictionaries with translation

To use dictionaries, you need to use DictService:

import { injectable } from '@ts-stack/di';
import { DictService } from '@ditsmod/i18n';

import { CommonDict } from '@dict/first/common.dict';

@injectable()
export class FirstService {
  constructor(private dictService: DictService) {}

  countToThree() {
    const dict = this.dictService.getDictionary(CommonDict);
    return dict.countToThree;
  }
}

As you can see, base dictionary classes are always used as a token to search for the required group of dictionaries. In this case, this code will work if the base dictionary contains the countToThree property. It will output the required translation if there is a dictionary with the corresponding translation in the dictionary group CommonDict. You can specify the locale in the second argument:

countToThree() {
  const dict = this.dictService.getDictionary(CommonDict, 'uk');
  return dict.countToThree;
}

But in most cases, the language is selected through an HTTP request. By default, DictService takes the locale from the lng parameter in this.req.queryParams, but you can change the name of this parameter by passing the lngParam option:

// ...
@featureModule({
  // ...
  providersPerMod: [
    ...new I18nProviders().i18n({ current, imported },  { defaultLng: 'uk', lngParam: 'locale' }),
  ],
})
export class SecondModule {}

Note that DictService is declared at the HTTP request level, so you will not be able to use this service in other services declared at higher levels (at the application or module level). If you need a higher-level service, use DictPerModService, which is actually a parent class for DictService with an almost identical API.

Arbitrary definition of the request language

Although the default value of the query language is determined via this.req.queryParams, you can easily change the logic of determining the query language, for example, by accept-language headers. To do this, it is enough to change the dictService.lng getter.

If you cloned the repository, you will find an example of MyDictService in the examples/15-i18n/src/app/third/third.module.ts module. This service extends DictPerModService and only overwrites the getter of mydictService.lng and the setter is also overwritten so that mydictService.lng can be edited. Well, after your own implementation of the definition of the language of the request, of course, you need to add the new service providersPerReq in the module.

Announcing Ditsmod 2.0 beta (with RealWorld example)

Костя Третяк — Mon, 10 Jan 2022 09:27:49 +0000

Today I'm excited to announce the release of Ditsmod 2.0 beta!

For those who aren’t familiar with Ditsmod, it's NodeJS framework written in TypeScript. To learn more, you can visit our website.

To get started using Ditsmod 2.0 beta, you can get it from github ditsmod/seed:

git clone https://github.com/ditsmod/seed.git ditsmod-app
cd ditsmod-app
yarn

Also, you can browse Ditsmod application containing real world examples (CRUD, auth, advanced patterns, etc) that adheres to the RealWorld spec and API.

For most users, Ditsmod is a hitherto unknown framework, so I will present it here as for the first time.

Some major highlights of Ditsmod are:

Modular architecture on decorators, which allows you to declaratively describe the structure of the application.
Convenient mechanism for specifying and resolving between different application classes: you in constructor specify instances of which classes you need, and DI undertakes a difficult task "how to get it".
Ability to write your own extensions (sometimes called plugins) that can be asynchronously initialized and that can depend on each other.
Ability to dynamically add and remove modules after starting the web server, without the need to restart.
Has OpenAPI support, and has the ability to validate requests based on OpenAPI metadata.
To date, Ditsmod is one of the fastest among Node.js web frameworks.

Example controller:

import { Controller, Res, Route } from '@ditsmod/core';

@controller()
export class HelloWorldController {
  constructor(private res: Res) {}

  @route('GET')
  tellHello() {
    this.res.send('Hello World!');
  }
}

Example module that has controllers:

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

import { Params } from '@models/params';
import { ArticlesController } from './articles.controller';
import { CommentsModule } from './comments/comments.module';
import { DbService } from './db.service';
import { FavoriteModule } from './favorite/favorite.module';

@featureModule({
  imports: [
    { prefix: 'comments', module: CommentsModule },
    { prefix: 'favorite', module: FavoriteModule },
  ],
  controllers: [ArticlesController],
  providersPerReq: [DbService]
})
export class ArticlesModule {}

Example module that has services only:

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

import { AuthService } from './auth.service';
import { BearerGuard } from './bearer.guard';
import { ModuleConfigService } from './config.service';
import { CryptoService } from './crypto.service';
import { PermissionsGuard } from './permissions.guard';

const jwtModuleWithParams = JwtModule.withParams({ secret: process.env.JWT_SECRET, signOptions: { expiresIn: '1y' } });

@featureModule({
  imports: [jwtModuleWithParams],
  providersPerMod: [ModuleConfigService],
  providersPerReq: [BearerGuard, CryptoService, AuthService, PermissionsGuard],
  exports: [BearerGuard, CryptoService, AuthService, PermissionsGuard]
})
export class AuthModule {}

Ditsmod vs NestJS

Ditsmod is similar to NestJS only because both of these frameworks are inspired by the concepts that Angular has. But Ditsmod under the hood does not have Express, Fastify or other frameworks. Ditsmod is 11% faster than NestJS + Fastify, provided that an instance of controller is created for each request. And more than twice as fast as NestJS + Express. Ditsmod also consumes significantly less memory compared to NestJS.

Thanks to the system of extensions, Ditsmod applications are more expressive and with less code. For example, if you compare OpenAPI modules written in Ditsmod and NestJS, the Ditsmod module is 3.5 times smaller in the number of lines of code or the number of files.

NestJS did not care about numerous gross mistakes in the tests

Костя Третяк — Mon, 13 Dec 2021 15:18:29 +0000

As I write my Node.js framework, I sometimes open the documentation of other frameworks to see what features they have, and I look at issues on github to see what features users of these frameworks want. This is especially true of NestJS, as it has also adopted many concepts from Angular, as has my framework.

The other day I was writing a module to integrate with the well-known jsonwebtoken library. NestJS also has an integration with this library, so I decided to peek at what tests they write to test something similar.

The @nestjs/jwt module is now downloaded 308,000 times a week, which is about a third of all NestJS users, and is responsible for such an important part as setting up security tokens and verifying them.

And what did I see in the tests of this module? - "Horror!" Because of this I opened the corresponding issue on github. Tests are not just written with small inconspicuous mistakes, such as the lack of await before expect(), there is generally a hell of a lot, and in almost all tests.

And how do you think the author of NestJS would react? He will say something like: "Wow! Thank you, colleague, for your attention, let's fix it!" - No, he stupidly closed the issue, and even locked it, with the words:

Tests were added via external contribution as part of this commit 9bae007. Feel free to create a follow-up PR to improve them.

I say - Wow! It would not be terrible if the author of an unknown framework reacted in this way. But this framework is downloaded as much as 1 million times a week, and such an indifferent attitude...

Udate: see fix of this bug https://github.com/nestjs/jwt/pull/808

Ditsmod - new NodeJS webframework writen in TypeScript

Костя Третяк — Sun, 23 May 2021 22:55:59 +0000

If you look through the search results on github for the keyword nodejs-framework (with only TypeScript projects selected), you can see that there are currently about 5 different frameworks designed to create applications that process HTTP requests on the server side.

So why create yet another similar framework? Well, let's see what I, as the author of Ditsmod, can offer you:

Ditsmod doesn't have ExpressJS or any other similar framework under the hood, so it's not complicated by backward compatibility with legacy packages, which makes Ditsmod a more consistent API.
For Ditsmod, modularity is a top priority, so each of its modules can easily migrate to microservices in the future when the need to scale to several separate servers arises. Other frameworks do not have the concept of modularity at all, or their modularity is not as clear as Ditsmod's.
Ditsmod has a powerful Dependency Injection, which allows you to create hierarchical relationships between different injectors (aka IoC containers). At the same time, it boasts high speed and memory efficiency.
Thanks to Dependency Injection, you can override the native classes of the logger, error handler, and any other service. This also helps when writing tests.
If you compare different Node.js frameworks in terms of speed, Ditsmod is one of the fastest (after fastify, koa, and restify). And if we take only those frameworks that have Dependency Injection, I assume that the results will be even better.
Ditsmod has a system of extensions (or plugins), which not all frameworks have.

Of course, these are the most basic differences of this framework. You can read more information on the official website.

Components of Ditsmod applications

Despite the fact that Ditsmod is a new framework, its applications can have a rich structure thanks to such components as:

modules;
controllers;
services;
HTTP interceptors;
guards;
extensions.

This framework relies heavily on decorators, which declaratively describe what needs to be done. Even if you've never seen this kind of programming in TypeScript code before, you can guess what's going on here:

import { controller, route, Res } from '@ditsmod/core';

import { FirstService } from './first.service';

@controller()
export class HelloWorldController {
  @route('GET', 'hello')
  method1(res: Res, firstService: FirstService) {
    res.send(firstService.sayHello());
  }
}

This example declares a controller with a single route that accepts GET requests that have the path /hello. It is worth noting here that Dependency Injection is responsible for passing parameters to method1().

Dependency resolution for services is also handled by Dependency Injection, but in services, most often, dependencies are specified in constructors:

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

import { FirstService } from './first.service';

@injectable()
export class SecondService {
  constructor(private firstService: FirstService) {}

  methodOne() {
    this.firstService.doSomeThing();
  }
}

Those users who are familiar with other TypeScript frameworks may have seen many similar concepts in NestJS. The fact is that both NestJS and Ditsmod were heavily inspired by Angular, which is why there are some external similarities between them. At the same time, there are plenty of differences between them. For example, they differ greatly in the hierarchy of injectors (aka IoC containers). Ditsmod currently (v2.38) has four static hierarchy levels:

Application level;
Module level;
Route level;
HTTP request level.

While NestJS v10.0 has one injector at the application level, the other is at the HTTP request level. This feature has a significant impact on building a modular application architecture.

There are also significant differences between NestJS and Ditsmod in terms of interceptors and guards, as in NestJS they are so-called "enhancers", so they cannot be exported and imported like regular providers, which degrades the modularity of NestJS applications. In Ditsmod, it's easier with interceptors and guards because they are regular providers.

Ditsmod also compares favorably with NestJS in that it has much better support for nested routes and the ability to write extensions (aka plugins).

Native Ditsmod modules

At the moment (v2.38), Ditsmod has the following native modules:

Examples from the RealWorld

You can also see examples with RealWorld implementation. The specification itself can be found on the official website:

While most "todo" demos provide an excellent cursory glance at a framework's capabilities, they typically don't convey the knowledge & perspective required to actually build real applications with it.RealWorld solves this by allowing you to choose any frontend (React, Angular, & more) and any backend (Node, Django, & more) and see how they power a real world, beautifully designed fullstack app called Conduit.