Forem: Vladyslav Zubko

BEM Modifiers in Pure CSS Nesting

Vladyslav Zubko — Mon, 17 Jun 2024 08:42:06 +0000

When I was starting to learn web development, pure CSS often remained in the realm of theory. When it came to practice, especially working on real projects, pure CSS was a rarity. The market and the industry itself dictated that styles should be written using preprocessors.

Fortunately, over time, this trend has almost disappeared. Pure CSS now includes many features that were previously missing, causing people to prefer preprocessors.

Even though I have not used preprocessors for a long time, at least in my personal projects, there is one thing I missed while working with them: using the parent selector to create modifiers when using the BEM methodology. I thought for a long time that I would never be able to avoid duplicating the full selector when writing modifiers in pure CSS. However, while redesigning my website, I found a convenient way for myself to write BEM modifiers using native CSS nesting.

My Path with BEM & SCSS

I hate preprocessors. Be it SASS, SCSS, LESS, Stylus, or any other. Really, without any exceptions. Though, I think my hatred for preprocessors is not because of the technology itself, but because of how other people use them. Throughout my development career, I have often encountered tickets where a seemingly simple task, like changing the text size, which should take minutes, ended up taking me hours. This is because people often want to use the tool to its full extent. As a result, to find where I needed to change the text size in projects using preprocessors to the max, I had to go through several mixins, maybe a loop or even nested loops, and several nested selectors using the parent selector. Brr, just thinking about it gives me the shivers.

Like many who started their careers during the peak popularity of preprocessors, I initially did not spend much time on pure CSS. The industry, including the job market, dictated the need for preprocessor knowledge, and mentions of pure CSS in job listings were rare. I was no exception, and almost from the beginning of my learning journey, I began writing styles using SCSS. I was very fortunate with my mentors, as they instilled in me a great love for pure CSS, despite the use of preprocessors. SCSS was chosen deliberately because it closely resembles pure CSS compared to other preprocessors. Additionally, out of all the features preprocessors offer, we used only two: compiling all .scss files into one file and nesting with the parent selector, exclusively for pseudo-classes/pseudo-elements and creating modifiers using the BEM methodology. All other preprocessor features, such as loops and mixins, were forbidden, as they were meant to solve specific problems rather than being used just because they exist.

For what purpose I used SCSS when I was learning.

Later on, after my training, almost all of my work projects involved some preprocessor. It was during these experiences that I developed my strong dislike for preprocessors. In my personal projects, however, I never used preprocessors and wrote everything in pure CSS, adding precise enhancements through plugins for my .css bundler. For example, in the past, when I was bundling my .css files using PostCSS, I used a simple plugin called postcss-import to bundle all .css files into one final file (such as in this blog. Here is one of the first commits in this repository). I rarely used any additional plugins for CSS.

I always tried to avoid nesting in preprocessors wherever possible, but with the introduction of native CSS nesting, I gradually began incorporating it into my personal projects. It seems to me that native CSS nesting works more intuitively and correctly compared to nesting in preprocessors. One key difference with native CSS nesting compared to preprocessor nesting is that it does not have the functionality of a parent selector to create new selectors. This is what I used during my training for BEM modifiers, and it was perhaps the only thing I started to miss when using native CSS nesting.

Native CSS Nesting Modifiers

Before native CSS nesting became available, I had to describe all class modifiers with separate selectors. During those times, I particularly missed the functionality of creating a new selector using the parent selector in preprocessors. This was because the full selector for a modifier could be duplicated dozens of times.



.tag-list__tag {
  --background-color: var(--color-red-200);

  padding-block: 2px;
  padding-inline: 6px;
  background-color: hsl(var(--background-color) / 30%);
}

.tag-list__tag--html {
  --background-color: var(--color-green-100);
}

.tag-list__tag--github {
  --background-color: var(--color-gray-100);
}

.tag-list__tag--ts {
  --background-color: var(--color-blue-200);
}

But even with the introduction of native CSS nesting, I did not immediately solve this problem because native CSS nesting simply does not have anything functionally similar to creating a new selector through the parent selector functionality found in preprocessors.

The first thing I started using more actively was various attributes, such as aria-current="page", rel="prev"/rel="next", name, and others. Just this alone significantly helped reduce the number of class modifiers. However, not all modifiers can be covered with attributes, and in my code, there still remained a sizable number of places where the selector was duplicated entirely to create a BEM modifier.

I tried googling for solutions because BEM methodology markup is quite popular, but all the code examples and repositories I found were doing the same thing – simply duplicating the entire selector.

One day, as I was adding new modifiers and duplicating the entire selector, I decided to experiment. Like everyone starting out with CSS, I learned about attribute selectors. I was no exception and went through that section, but truthfully, I rarely used these selectors. However, I completely forgot that attribute selectors can be used with any attribute, including class (because it is odd to use an attribute selector for a class when you can just use a class selector, right?). Then it struck me – I also remembered about additional operators available in attribute selectors, specifically substring matching selectors, which work perfectly with native CSS nesting. Here is how it looks:



.tag-list__tag {
  --background-color: var(--color-red-200);

  padding-block: 2px;
  padding-inline: 6px;
  background-color: hsl(var(--background-color) / 30%);

  &[class*='--html'] {
    --background-color: var(--color-green-100);
  }

  &[class*='--github'] {
    --background-color: var(--color-gray-100);
  }

  &[class*='--ts'] {
    --background-color: var(--color-blue-200);
  }
}

It turned out quite close to the modifiers that I used to write using the parent selector in SCSS at the beginning of my learning, didn't it?

Perhaps not as concise as using the parent selector to create new selectors in preprocessors, but personally, I prefer the approach with native CSS nesting and attribute selectors paired with substring matching selectors much more. As I mentioned earlier, native CSS nesting is much clearer and more logical to me in understanding.

Here you can find the PR where I applied this trick across my entire project.

Conclusion

I love CSS and all its functionality. It is gratifying to see how the foundational aspects of CSS from the very beginning seamlessly complement the new functionalities emerging within it. Moreover, this synergy works in both directions.

I have never been part of the group of people who say that native CSS should incorporate everything found in tools like SASS or other preprocessors. To me, these are different tools, and this small trick using attribute selectors together with substring matching selectors in native CSS nesting for BEM modifiers &[class*="--modifier"] has finally fulfilled all my wishes that I had when using SCSS and other preprocessors. However, CSS continues to evolve, and on the horizon, we can already see native CSS mixins (one of the reasons why I always reluctantly talk about SCSS or other preprocessors).

Once upon a time, when native CSS nesting was just starting to be discussed, I thought, "Nesting? In pure CSS? I will never use that!" But over time, I got used to it, and now I even like it. Will the same happen with native CSS mixins, or, heaven forbid, native CSS loops? I want to say no, but I will not make predictions. At the very least, with experience, I have become acquainted with a wonderful tool like Stylelint and its life-easing rules such as max-nesting-depth and others. Hopefully, it will prevent me from becoming a hater of pure CSS someday.

Why it is Important to Update Linters and How to Do it Right

Vladyslav Zubko — Thu, 08 Feb 2024 10:22:05 +0000

Many developers approach “old” projects with great reluctance. An old project can be defined as one in which the majority of its components are written using outdated approaches, obsolete rules of linters, old versions of libraries, or an outdated development platform. There can be various reasons why projects age – strict release deadlines that only include business features, a lack of understanding on the business side of the project regarding the necessity of investing time just like that, and simply the indifference towards the technical side of the project. However, when a situation truly starts to heat up, for example, an urgent need to migrate to the Node.js LTS version or promptly update a library version because further development is impossible, the time, motivation, and explanation of why it is necessary to do this will be found.

When the time for updating the platform version and library versions inevitably comes, many developers mistakenly overlook linters. Often, configuring a linter and its rules is perceived as a one-time task, typically done at the start of the project, and it is assumed that after the initial setup, one can forget about it forever. Linters and their rules evolve, the same as any other libraries. New configurations, rules, and changes to existing rule options emerge. Depending on how and when you configured your linter, it will impact the quality of your code. After all, linters have long been not just about coding style but also about the correctness of code, staying up-to-date with new development approaches, and leveraging the language's new features.

Consequently, if you adhere to the approach that a linter needs to be configured exactly once at the project's outset, then most likely the quality of your code will remain at the level it was when you initially configured the linter.

A linter that does not receive enough love.

Many developers are hesitant to update a linter and its rules because they fear that it may lead to various issues. Often, they worry that adding or modifying rules will require editing all the old code in files that may not have been touched for months or even years. This concern is particularly pronounced in large projects. Even if a rule pertains to more stylistic aspects and theoretically should not break anything, a pull request that applies the updated/new linter rule to the entire project can result in potentially several thousands of changed files, depending on the project's size. Reviewing such changes can be quite a task, and there might not even be a review, as such code reviews are rightfully considered unacceptable.

Quality implementation of updated/new linter rules should follow a different process. First and foremost, the goal is to ensure that only all new files (or preferably new and modified ones) entering the codebase as part of a single code review adhere to the changed/new linter rule. With this approach, the process of modifying or adding rules becomes simple and safe, as there is no need to immediately edit the entire project to comply with the changes in linter. The application of linter updates will occur gradually, with each pull request incorporating more and more files that align with the new changes.

Indeed, in this article, we will further explore how to approach the implementation of this process effectively.

Enhanced Config

All modern linters incorporate functionality for extending configurations, although the syntax for this is often implemented differently. Taking ESLint as an example, in its latest versions, the primary extension method is through the use of the spread operator. Let's take a look at an example:

// eslint.config.js

const config = {
  languageOptions: {
    parserOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
    },
  },
  rules: {
    "arrow-parens": ["error", "always"],
  },
};

const configs = [config, /* other ESLint plugins can be used here */];

export default configs;

To extend this configuration, you can do the following:

// eslint.enhanced.config.js

import { default as baseConfigs } from "./eslint.config.js";

const config = {
  rules: {
    semi: ["error", "never"],
  },
};

const configs = [...baseConfigs, config];

export default configs;

As we can see from the example, extending the base config using the spread operator is quite simple and clear. The name of this config can be anything, allowing us to pass the desired config name to the linter. Information about this will be provided below.

Another common way to extend configs in linters is using the extends key in the configuration file. Let's take StyleLint as an example:

// stylelint.config.js

const config = {
  extends: ["stylelint-config-standard"],
};

export default config;

The values in the extends key array can be absolute or relative paths. Absolute paths are used for configs provided by package managers, for example, NPM, as shown in the example above. On the other hand, relative paths are used to extend local configuration files. The mechanism is similar to using the spread operator for extending ESLint configs.

Both using the spread operator and the extends key in the linter's configuration file are popular methods for implementing the config extension mechanism. However, it is worth noting that the spread operator mechanism is becoming increasingly popular among linters in recent times. In earlier versions, ESLint also supported the extension mechanism through the extends key in the configuration file. Although this mechanism can still be used in ESLint, it is not recommended. Moreover, ESLint's authors plan to deprecate support for the extension mechanism via the extends key in future releases.

Another crucial aspect common to all linters is the CLI option --config (or -c), which allows us to explicitly specify the configuration to use for linting files. By default, all linters have a set of standard configuration file names they will look for in the project when the linter is run. For example, ESLint searches for the file eslint.config.js, while StyleLint looks for stylelint.config.js. Since most projects rarely have more than one linter configuration file, the --config CLI option is not frequently used, but it is essential not to overlook it.

Since we want to gradually implement the updated/new rule in the project, we can leverage the config extension mechanism to use the existing linter config and extend it with a newly created config. This new config will include all settings and rules from the base config and will also be extended with updated/new rules. This allows us to use the base linter config to lint all old files as before, and for all new files that should be introduced into the codebase via a pull request, we can lint them using the enhanced linter config and the CLI option --config.

We have covered the part about extending the config. Now, let's understand how to apply updated/new rules only to files involved in code reviews.

Continuous Integration Changes

In most projects, before other people start reviewing code in a pull request, it needs to pass machine reviews from various linters and tests. This process is commonly referred to as Continuous Integration (or CI for short). There are numerous tools available to help set up this process. In this article, we will use GitHub Actions, which is also the most popular tool for configuring the CI process on GitHub. However, the principles can be applied with any CI tool.

The simplest CI GitHub Actions for linting JavaScript files can look like this:

# .github/workflows/ci.yml

name: Continuous Integration

on:
  pull_request:
    branches:
      - main

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Code Checkout
        uses: actions/checkout@v4

      - name: Install NodeJS
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc

      - name: Install Dependencies
        run: npm install

      - name: Lint JS
        run: npx eslint .

If you are not familiar with the GitHub Actions syntax, you can refer to it here.

Currently, the main step in the action is the "Lint JS" step, which simply runs ESLint on all JS files in the project. You can learn more about ESLint's CLI capabilities here.

Now, we need to add additional steps that include checking for updated/new rules. The simplest implementation of this would look like the following:

# .github/workflows/ci.yml

# ...
# CI GitHub Action and its configuration
# ...

- name: Get Changed Files
  id: changed-files
  uses: tj-actions/changed-files@v42

- name: Lint JS with Enhanced Rules
  run: npx eslint --config eslint.enhanced.config.js ${{ steps.changed-files.outputs.added_files }}

We need to add two additional steps. The first one is to retrieve all new files, and the second one is to run the enhanced config only on the new files. In this example the third-party GitHub Action called changed-files is used to obtain the new files. In the GitHub Marketplace for Actions, there is a considerable number of similar actions with similar functionality. You can choose the one that suits you best, as the functionality is more or less the same for all of them.

It is important to note that in this example, we apply the enhanced config only to new files that will be in the pull request. Depending on the agreements within your team, such as the average size of your pull requests, it is strongly recommended to include not only new files but also modified ones when linting with the enhanced config. This will expedite the process of achieving 100% coverage of the project with updated/new rules.

Also, due to the simplicity of the example, a straightforward GitHub Actions workflow was used where all steps are performed within a single job. While this works, it is recommended to decompose the tasks performed by a GitHub Action into multiple jobs when it makes sense to divide them. This can enhance readability and maintainability of your workflows.

Conclusion

In modern development, where technologies are constantly evolving, keeping linters up-to-date becomes crucial for maintaining high code quality. Many developers, while focusing on platform and library updates, overlook the importance of updating linters. However, linters play a role not only in maintaining code style but also in ensuring its correctness and adherence to modern development practices.

The fear of updating linters is often associated with potential issues, such as the need to make changes to extensive old code. However, implementing linter updates can be done more safely by following methods of gradual modification, applying updated/new rules to new or modified files. This process ensures a gradual alignment of the entire project with updated standards, minimizing potential issues and providing a smooth adaptation process.

An important element of successfully updating a linter is the use of configuration extension functionality. Modern linters, such as ESLint, provide extension mechanisms, allowing updates to be gradually introduced by extending the existing config with updated/new rules. This approach ensures the ease of alignment for both existing code and new changes, contributing to maintaining a high coding standard in the project.

Additionally, once you achieve 100% coverage of the project with the updated/new rule in the enhanced linter config, do not forget to move this rule to the main config. This ensures that the rule is consistently applied across the entire project and helps maintain a unified code style.

A linter that receives enough love (but it can always be better!)

Try to incorporate this approach into your daily development routine, as now you know that it is not very complicated to do. I am sure you, your team, and your project will appreciate this change, as it embodies not only technical efficiency but also the flexibility required in the modern dynamic development environment.

You can find complete examples of using this approach here in the repository.

TypeScript Might Not Be Your God: Case Study of Migration from TS to JSDoc

Vladyslav Zubko — Tue, 16 Jan 2024 17:20:34 +0000

"We will soon migrate to TypeScript, and then..." – how often do you hear this phrase? Perhaps, if you mainly work within a single project or mostly just start new projects from scratch, this is a relatively rare expression for you to hear. For me, as someone working in an outsourcing company, who, in addition to my main project, sees dozens of various other projects every month, it is a quite common phrase from the development team or a client who would like to upgrade their project stack for easier team collaboration. Spoiler alert: it is probably not going to be as soon of a transition as you think (most likely, never).

While it may sound drastic, in most cases, this will indeed be the case. Most people who have not undergone such a transition may not be aware of the dozens of nuances that can arise during a project migration to TypeScript. For instance, are you prepared for the possibility that your project build, which took tens of seconds in pure JavaScript, might suddenly start taking tens of minutes when using TypeScript? Of course, it depends on your project's size, your pipeline configuration, etc., but these scenarios are not fabricated. You, as a developer, might be prepared for this inevitability, but what will your client think when you tell them that the budget for the server instance needs to be increased because the project build is now failing due to a heap out-of-memory error after adding TypeScript to the project? Yes, TypeScript, like any other tool, is not free.

On the Internet, you can find a large number of articles about how leading companies successfully migrated their projects from pure JavaScript to TypeScript. While they usually describe a lot of the issues they had during the transition and how they overcame them, there are still many unspoken obstacles that people can encounter which can become critical to your migration.

Despite the awareness among most teams that adding typing to their projects through migration to TypeScript might not proceed as smoothly as depicted in various articles, they still consider TypeScript as the exclusive and definitive solution to address typing issues in their projects. This mindset can result in projects remaining in pure JavaScript for extended periods, and the eagerly anticipated typing remains confined to the realm of dreams. While alternative tools for introducing typing to JavaScript code do exist, TypeScript's overwhelming popularity often casts them into the shadows. This widespread acclaim, justified by the TypeScript team's active development, may, however, prove disadvantageous to developers. Developers tend to lean towards the perception that TypeScript is the only solution to typing challenges in a project, neglecting other options.

Next, we will consider JSDoc as a tool that, when used correctly and understood in conjunction with other tools (like TypeScript), can help address the typing issue in a project virtually for free. Many might think that the functionality of JSDoc pales in comparison to TypeScript, and comparing them is unfair. To some extent, that is true, but on the other hand, it depends on the perspective. Each technology has its pros and cons, counterbalancing the other.

Code examples will illustrate a kind of graceful degradation from TypeScript to JavaScript while maintaining typing functionality. While for some, this might appear as a form of progressive enhancement. Again, it all depends on how you look at it…

TypeScript to JSDoc. My vanilla JavaScript enums.

JSDoc and Its Extensions

JSDoc is a specification for the comment format in JavaScript. This specification allows developers to describe the structure of their code, data types, function parameters, and much more using special comments. These comments can then be transformed into documentation using appropriate tools.



/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of the two numbers.
 */
const getSum = (a, b) => {
  return a + b
}

Initially, JSDoc was created with the goal of generating documentation based on comments, and this functionality remains a significant part of the tool. However, it is not the only aspect. The second substantial aspect of the tool is the description of various types within the program: variable types, object types, function parameters, and many other structures. Since the fate of ECMAScript 4 was uncertain, and many developers lacked (and still lack to this day) proper typing, JSDoc started adding this much-needed typing to JavaScript. This contributed to its popularity, and as a result, many other tools began to rely on the JSDoc syntax.

An interesting fact is that while the JSDoc documentation provides a list of basic tags, the specification itself allows developers to expand the list based on their needs. Tools built on top of JSDoc leverage this flexibility to the maximum by adding their own custom tags. Therefore, encountering a pure JSDoc setup is a relatively rare occurrence.

TypeScript to JSDoc. Function typing.

The most well-known tools that rely on JSDoc are Closure Compiler (not to be confused with the Closure programming language) and TypeScript. Both of these tools can help make your JavaScript typed, but they approach it differently. Closure Compiler primarily focuses on enhancing your .js files by adding typing through JSDoc annotations (after all, they are just comments), while TypeScript is designed for .ts files, introducing its own well-known TypeScript constructs such as type, interface, enum, namespace, and so on.

Not from its inception, but starting from version 2.3, TypeScript began allowing something similar to Closure Compiler – checking type annotations in .js files based on the use of JSDoc syntax. With this version, and with each subsequent version, TypeScript not only added support for JSDoc but also incorporated many of the core tags and constructs present in Closure Compiler. This made migration to TypeScript more straightforward. While Closure Compiler is still being updated, used by some teams, and remains the most effective tool for code compression in JavaScript (if its rules are followed), due to support for checking .js files and various other updates brought by the TypeScript team, Closure Compiler eventually lost to TypeScript.

From the implementation perspective, incorporating an understanding of JSDoc notation into TypeScript is not a fundamental change. Whether it is TypeScript types or JSDoc types, ultimately, they both become part of the AST (Abstract Syntax Tree) of the executed program. This is convenient for us as developers because all our everyday tools, such as ESLint (including all its plugins), Prettier, and others, primarily rely on the AST. Therefore, regardless of the file extensions we use, our favorite plugins can continue to work in both .js and .ts files (with some exceptions, of course).

TypeScript to JSDoc. Type Declaration.

Developer Experience

When adding typing to JavaScript code using JSDoc, it is advisable to use additional tools that enhance the development experience.

eslint-plugin-jsdoc is a JSDoc plugin for ESLint. This plugin reports errors in case of invalid JSDoc syntax usage and helps standardize the written JSDoc. An important setting for this plugin is the mode option, which offers one of the following values: typescript, closure (referring to Closure Compiler), or jsdoc. As mentioned earlier, JSDoc can vary, and this option allows you to specify which JSDoc tags and syntax to use. The default value is typescript (though this has not always been the case), which, given TypeScript's dominance over other tools that work with JSDoc, seems like a sensible choice.

TypeScript to JSDoc. Type casting.

It is also important to choose a tool for analyzing the type annotations written in JSDoc, and in this case, it will be TypeScript. This might sound strange because, in this article, it seems like we are discussing its replacement. However, we are not using TypeScript for its primary purpose – our files still have the .js extension. We will only use TypeScript as a type checking linter. In most projects where TypeScript is used fully, there is typically a build script responsible for compiling .ts files into .js. In the case of using TypeScript as a linting tool, instead of a build command handling compilation, you will have a command for linting your types.



// package.json

{
  "scripts": {
       "lint:type": "tsc --noEmit"
  }
}

If, in the future, a tool emerges that surpasses TypeScript as a linting tool for project typing, we can always replace it in this script.

To make this script work correctly, you need to create a tsconfig.json file in your project or add additional parameters to this script. These parameters include allowJs and checkJs, which allow TypeScript to check code written in .js files. In addition to these parameters, you can enable many others. For example, to make type checking stricter, you can use strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noPropertyAccessFromIndexSignature, and more. TypeScript will rigorously check your code even if you are using .js files.

The TypeScript team consistently enhances the functionality of TypeScript when working with JSDoc. With almost every release, they introduce both fixes and new features. The same applies to code editors. Syntax highlighting and other DX features provided by TypeScript when working with .ts files also work when dealing with .js files using JSDoc. Although there are occasional instances where support for certain JSDoc features may come later, many GitHub issues labeled with JSDoc in the TypeScript backlog indicate that the TypeScript team continues to work on improving JSDoc support.

TypeScript to JSDoc. Generics.

Many might mention the nuance that when using TypeScript solely for .js files, you are deprived of the ability to use additional constructs provided by TypeScript. For example: Enums, Namespaces, Class Parameter Properties, Abstract Classes and Members, Experimental (!) Decorators, and others, as their syntax is only available in files with the .ts extension.

Again, for some, this may seem like a drawback, but for others, it could be considered a benefit, as most of these constructs have their drawbacks. Primarily, during TypeScript compilation to JavaScript, anything related to types simply disappears. In the case of using the aforementioned constructs, all of them are translated into less-than-optimal JavaScript code. If this does not sound compelling enough for you to refrain from using them, you can explore the downsides of each of these constructs on your own, as there are plenty of articles on the Internet discussing these issues.

Overall, the use of these constructs is generally considered an anti-pattern. On most of my projects where I use TypeScript to its full extent (with all my code residing in .ts files), I always use a custom ESLint rule:



// eslint.config.js

/** @type {import('eslint').Linter.FlatConfig} */
const config = {
  rules: {
    'no-restricted-syntax': [
      'error',
      {
        selector: 'TSEnumDeclaration,TSModuleDeclaration,TSParameterProperty,ClassDeclaration[abstract=true],Decorator',
        message: 'TypeScript shit is forbidden.',
      },
    ],
  },
}

This rule prohibits the use of TypeScript constructs that raise concerns.

When considering what remains of TypeScript when applying this ESLint rule, essentially, only the typing aspect remains. In this context, when using this rule, leveraging JSDoc tags and syntax provided by TypeScript for adding typing to .js files is almost indistinguishable from using TypeScript with .ts files.

TypeScript to JSDoc. Class and its members.

As mentioned earlier, most tools rely on AST for their operations, including TypeScript. TypeScript does not care whether you define types using TypeScript's keywords and syntax or JSDoc tags supported by TypeScript. This principle also applies to ESLint and its plugins, including the typescript-eslint plugin. This means that we can use this plugin and its powerful rules to check typing even if the entire code is written in .js files (provided you enabled the appropriate parser).

Unfortunately, a significant drawback when using these tools with .js files is that some parts of these tools, such as specific rules in typescript-eslint, rely on the use of specific TypeScript keywords. Examples of such rules include explicit-function-return-type, explicit-member-accessibility, no-unsafe-return, and others that are tied explicitly to TypeScript keywords. Fortunately, there are not many such rules. Despite the fact that these rules could be rewritten to use AST, the development teams behind these rules are currently reluctant to do so due to the increased complexity of support when transitioning from using keywords to AST.

Conclusion

JSDoc, when used alongside TypeScript as a linting tool, provides developers with a powerful means of typing .js files. Its functionality does not lag significantly behind TypeScript when used to its full potential, keeping all the code in .ts files. Utilizing JSDoc allows developers to introduce typing into a pure JavaScript project right now, without delaying it as a distant dream of a full migration to TypeScript (which most likely will never happen).

Many mistakenly spend too much time critiquing the JSDoc syntax, deeming it ugly, especially when compared to TypeScript. It is hard to argue otherwise, TypeScript's syntax does indeed look much more concise. However, what is truly a mistake is engaging in empty discussions about syntax instead of taking any action. In the end, you will probably want to achieve a similar result, as shown in the screenshot below. Performing such a migration is significantly easier and more feasible when transitioning from code that already has typing written in JSDoc.

JSDoc to TypeScript. Possibly a long-awaited migration. React Component.

By the way, many who label the JSDoc syntax as ugly, while using TypeScript as their sole primary tool, after such remarks, nonchalantly return to their .ts files, fully embracing TS Enums, TS Parameter Properties, TS Experimental (!) Decorators, and other TS constructs that might raise questions. Do they truly believe they are on the right side?

Most of the screenshots were taken from the migration of .ts files to .js while preserving type functionality in my library form-payload (here is the PR). Why did I decide to make this migration? Because I wanted to. Although this is far from my only experience with such migrations. Interestingly, the sides of migrations often change (migrations from .js to .ts undoubtedly occur more frequently). Despite my affection for TypeScript and its concise syntax, after several dozen files written/rewritten using JSDoc, I stopped feeling any particular aversion to the JSDoc syntax, as it is just syntax.

Summing up: JSDoc provides developers with real opportunities for gradually improving the codebase without requiring a complete transition to TypeScript from the start of migration. It is essential to remember that the key is not to pray to the TypeScript-God but to start taking action. The ultimate transition to using TypeScript fully is possible, but you might also realize that JSDoc is more than sufficient for successful development, as it has its advantages. For example, here is what a "JSDoc-compiler" might look like:



// bundler.js

await esbuild.build({
  entryPoints: [jsMainEntryPoint],
  minify: true, // 👌
})

Give it a try! Do not stand still, continually develop your project, and I am sure you will find many other benefits!

The Strictest TypeScript Config

Vladyslav Zubko — Wed, 13 Dec 2023 09:24:47 +0000

Most people know that to make projects using TypeScript "strict" in terms of typing, you need to enable the "strict": true option in the tsconfig. What this option does is enable a multitude of other options, such as alwaysStrict, strictNullChecks, strictBindCallApply, strictFunctionTypes, strictPropertyInitialization, noImplicitAny, noImplicitThis, useUnknownInCatchVariables. Indeed, all these options will undoubtedly make your TypeScript project stricter.

However, not everyone knows that in the TypeScript config, there are other options that can more reliably protect your project from type-related errors, which are not yet automatically included by the strict option. Let's take a look at these options together to make our projects using TypeScript more robust.

`noUncheckedIndexedAccess`

The first option we will explore is called noUncheckedIndexedAccess. Historically, TypeScript automatically infers a type if it has grounds to do so. For example, if we manually specify the type of an array while leaving it empty or use an index signature for objects. It might seem like TypeScript is doing us a favor, but very often, this can lead to unintended consequences.

This is where noUncheckedIndexedAccess comes to the rescue. It adds undefined to any undeclared key of an object or index of an array, prompting additional checks to ensure that you are fully aware of what you are doing.

// noUncheckedIndexedAccess: false (default behavior)

const ids: number[] = [];
const user: Record<string, string> = {};

const id0 = ids[0]; // number
const username = user.username // string

id0.toFixed(); // ✅ but 💥
username.trim(); // ✅ but 💥

// noUncheckedIndexedAccess: true

const id0 = ids[0]; // number | undefined
const username = user.username // string | undefined

id0.toFixed(); // ❌ Error: 'id0' is possibly 'undefined'.
username.trim(); // ❌ Error: 'username' is possibly 'undefined'.

`exactOptionalPropertyTypes`

Next, we have the option exactOptionalPropertyTypes, which also addresses a long-standing pain point in TypeScript. Specifically, the issue that the ? prefix in object keys serves two purposes – indicating that a field can be undefined and also signifying that the field might not exist in the object at all (yes, these are two different things).

With this option enabled, TypeScript retains only one behavior with the ? prefix. Now, it signifies only the absence of a key, not that it could be undefined. If you need to allow the value to be undefined, you must specify it explicitly (e.g., hasFriends: string | undefined).

// exactOptionalPropertyTypes: false (default behavior)

type User = {
    name: string;
    age: number;
    hasFriends?: boolean;
};

const user: User = {
    name: 'John',
    age: 18,
};

user.hasFriends = true; // ✅
user.hasFriends = undefined; // ✅

// exactOptionalPropertyTypes: true

user.hasFriends = true; // ✅
user.hasFriends = undefined; // ❌

`noPropertyAccessFromIndexSignature`

Concluding the trio of significant options, which are not part of the strict option but play a crucial role in enforcing stricter typing in TypeScript projects, is the noPropertyAccessFromIndexSignature option.

There is often a temptation to either write your own index signature for an object, even when it seems like there is nothing preventing you from explicitly describing all the keys of the object, or to use index signatures from libraries, as library authors often indulge in them. noPropertyAccessFromIndexSignature requires the use of bracket notation when accessing keys of objects described through index signatures.

The goal of this option is to make sure you are absolutely certain about what you are doing. Since nobody likes bracket notation where it can be avoided, this option forces you to avoid index signatures as much as possible. Indeed, many problems arise from them, and this option aims to mitigate those issues.

// noPropertyAccessFromIndexSignature: false (default behavior)

type Settings = {
  mode: string;
  [key: string]: string;
};

const settings: Settings = {
  mode: 'MFA',
  kind: 'google',
};

settings.mode // ✅
settings.kind // ✅
settings.wat // ✅

// noPropertyAccessFromIndexSignature: true

settings.mode // ✅
settings.kind // ❌
settings.wat // ❌
settings['kind'] // ✅, but it's better to avoid index signatures and describe all type keys explicitly
settings['wat'] // ✅

By the way, the TypeScript ESLint plugin developers have thoughtfully provided the ability to use this and many other options from the TypeScript config, along with their rules. The @typescript-eslint/dot-notation rule syncs seamlessly with this option, once again emphasizing that using index signatures is not a good practice.

Conclusion

There are also other options improving typing in the TypeScript config that are not automatically enabled with the strict option, but they are not as crucial as the three mentioned above.

For all new projects where you will be using TypeScript, I recommend starting with a TypeScript config where the strict option is enabled along with the additional three options we discussed earlier: noUncheckedIndexedAccess, exactOptionalPropertyTypes, and noPropertyAccessFromIndexSignature.

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true
  }
}

Or try enabling them in an existing project, but be prepared to uncover many areas where you might have taken shortcuts 😉

All these options, by imposing additional constraints and promoting more correct coding practices, will help make your project more reliable. This simplifies both its maintenance in the long run and the quicker detection of incorrect behavior in your code.

How We Started Managing BSA Delivery Processes on GitHub

Vladyslav Zubko — Sat, 25 Nov 2023 22:00:00 +0000

Hello everyone! I am Vladyslav. At the beginning of 2022, I was offered the role of Delivery Head of BSA (Binary Studio Academy). Binary Studio Academy is a free, international course that transforms people with basic programming language knowledge into true beginner engineers.

From a delivery perspective, each Academy consists of several specific stages, each of which comprises a varying number of checklists that need to be completed for the stage to be considered successfully completed. Additionally, the Academy involves a substantial amount of documentation for various roles within it, as well as a wealth of content ranging from concise lecture summaries to automated tests that assess homework completion of these lectures.

Despite having two years of experience within the Academy at the time I received this role, I still felt the need for more examples and checklists for all the actions I needed to take at each stage of the Academy. Documentation was not always helpful because we all know that documentation has a tendency to become outdated or get lost when stored in different places. Establishing a process where everyone understands what they need to do, having a single source of truth, and maintaining a history of past Academies became my top priority for change.

How It Was

Before diving into the current process we use, I would like to start with what we had before. We had a significant number of tools at our disposal. Here are the key ones:

Trello. Was our tool for managing task boards. Depending on who held the position of Delivery Head of BSA, boards were created by different individuals, sometimes not even within the organization but on personal accounts. This led to the problem that there was no real history of the boards. As a result, for almost every Academy, we had to recall the number of tasks that needed to be completed at each stage. While everyone usually understood what needed to be done, without a clear list of tasks, things were occasionally forgotten.
Google Docs. This tool was used both for storing general information, such as documentation and lecture content, and for collecting information required for each Academy. Despite using Google Drive and keeping most of the information in one place, there was still a situation where some documents in each Academy were created on the fly to test something or provide a rough draft, and eventually, those documents could become quite valuable. Sometimes, these documents were created not in the BSA Google Drive but in someone's personal account which led to the occasional loss of such documents.
Google Sheets. They were mainly used for collecting statistics but created similar issues as Google Docs, with documents sometimes being scattered across different accounts and losing some degree of organization and accessibility.

While Google Docs/Sheets in combination with Google Drive are decent tools for storing information in one place, their functionality sometimes fell short of providing convenient management. For example, the process of reviewing changes, especially when it involves multiple people, could become increasingly challenging. The more individuals were involved in working on a single document, the harder it was to control the process.

Another significant problem was related to document version history. Sometimes it was easier to create a new document than to maintain it for each Academy. As a result, the appearance of certain stages or lectures as they were in the past often got lost. Occasionally, it was crucial to view how certain documents looked in their previous states.

Another challenge for us was that while all the content was stored in Google Docs, it was often written using Markdown. Although Google Docs has partial support for Markdown, it was insufficient for our needs, and we had to store raw Markdown in Google Docs. This experience was not the most pleasant because things often broke or did not display as intended due to a lack of full Markdown support.

We also had other tools in use, such as Miro. This tool was primarily used for visualizing certain process flows, like document change approval processes. Or at some point, we considered using boards in Asana because non-delivery processes were managed in that tool. However, when we contemplated the move to Asana, I decided to explore other potential tools. After reading many articles and conducting some research, especially on emerging tools, my attention turned to something unusual.

How It Is Now

I did not have the goal of using just one tool, although that is usually the most convenient option. Providing access to a single tool is much easier than granting access to multiple tools, especially given the volume of people involved in each Academy. Reflecting on what tool we could use to cover all our needs and after reading many articles about the experiences of other products, I chose GitHub. It seemed ideal to me in terms of what it could offer us – version history, boards, and a clear process for accepting changes.

A significant factor in my decision was observing GitHub's development over the past six months. I was confident that while not all the features GitHub offered looked perfect at the time, the GitHub team would continue to refine and improve them. Roadmaps of GitHub features, such as the GitHub Actions Roadmap, were helpful to me. I am a fan of GitHub Actions and enjoy keeping an eye on what is coming soon. Some other GitHub features, like GitHub Projects, also have open roadmaps that provide insights into upcoming updates in those features.

Now, let's discuss the core functionality of GitHub that we use for managing delivery processes in the Academy.

Git. Since GitHub is primarily about version control, we immediately resolved the issue of any file getting lost. Additionally, we now have a clear version history for every file, easily accessible through the familiar to all GitHub interface.

Certainly, version history is not the only advantage of Git. In general, it provides a robust toolkit that we make use of. For instance, the ability to quickly revert to a specific version or the conflict resolution functionality when someone starts editing the same file are valuable features. GitHub, in combination with Git, has proven to be a highly convenient tool for managing textual content.
Markdown. Since a substantial portion of the content we use in the Academy is written with Markdown syntax, we no longer needed to come up with various workarounds as we did when using Google Docs. Finally, we were able to use .md files, which are the standard format for Markdown syntax. We no longer had to worry about the output of information for students being different from what we could see in Google Docs because all the content was stored in files with the appropriate extension.
Issues & Projects. We started using GitHub Projects as our primary board for each Academy. GitHub Projects are closely tied to GitHub Issues, which serve as tasks on the board. In addition, GitHub Projects itself offers a lot of useful functionality, such as various views and filters that allow you to easily and conveniently display information based on your specific criteria.

To be honest, when we first started using GitHub Projects as our main board, not everyone, including myself, was initially thrilled about it. At the outset, we missed some convenient features that Trello offered, such as due dates or easy Slack notification setup for board actions. This was during our first Academy where we began using GitHub as our primary tool for managing delivery processes in the Academy. Since then, GitHub has created a lot of useful documentation, such as how to add automation with GitHub Actions, and they have also introduced many new features, like custom fields for Issues, which can be used in various ways. For instance, we started using them to store due dates. By the time we got to the second Academy where we used GitHub as our primary tool, it covered everything we needed and even more.

Once again, because GitHub is fundamentally about version control, GitHub Projects had a simple but crucial feature for us – project archiving. It might seem like a small detail, but the issue of losing boards, which we experienced when using Trello, could be critically important at times. Storing everything within a single GitHub repository, from boards to content, minimized the risk of losing anything.

All our checklists migrated into Issues. With all the statistical highlights, including how much is left to complete an issue and quick navigation to the relevant lectures and pull requests, Issues seemed much more convenient than what tickets in Trello offered. Primarily, this was because we used two separate tools, Trello for tickets and Google Docs/Sheets for content. These two tools did not integrate seamlessly, and each time, we had to set up convenient interactions between them for every ticket.

Since Issues are also about clear communication, we agreed with the team that a significant portion of Academy-related communication would take place within Issues. This was primarily for historical purposes, but also because using Issues for this purpose proved to be very convenient. Any internal references, such as to pull requests, were transformed by GitHub into concise text. Additionally, it linked Issues and Pull Requests, making the history of changes and decision-making clearer and more aesthetically pleasing than ever before.
Issues Templates. To standardize all the issues and never forget the checklists that needed to be completed in them, we made use of the Issues Templates feature. One significant advantage is that an issues template is just a text file, like all other files in the repository. This means it benefits from all the powerful functionality of Git, has its own version history, and in case of any issues, you can easily revert it to a specific version.
Pull Requests. With Google Docs/Sheets, the process of accepting changes to existing lecture content and documentation, as well as creating new documents, was not particularly convenient. The main inconvenience was assigning permissions to users. Since lecture and content owners changed quite frequently in our Academy, keeping track of it all was challenging. It was especially tricky when the change process depended on multiple people. Unfortunately, Google Docs/Sheets did not offer a convenient way to implement a change approval workflow for such cases.

The familiar process of proposing changes through pull requests was well-received by the entire team. No one needed extensive explanations about how it works because everyone had experience with it. Configuring content ownership through code owners resolved the issue of content authorship and whose approvals were needed to get changes into the Academy.
GitHub Actions. At some point, we realized the importance of automation. We started with linters that run on every pull request. Our linters help us maintain a consistent style throughout all our content and serve as the first line of defense that everyone must pass through when they want to introduce changes to the Academy.

Here is a list of our main linters:
- remark. Primarily, this is a linter for Markdown. Additionally, thanks to its numerous plugins, it allows us to perform additional checks for grammatical mistakes within the content itself. Before using this linter, our content was not scrutinized to this extent.
- prettier. A code formatter and linter for code formatting. It ensures that all our files have a consistent appearance.
- ls-lint. A linter for file and folder names. Again, we aim for uniformity in this aspect as well.
- editorconfigchecker. A linter that checks files for compliance with editorconfig rules. Another linter that helps maintain consistency in the format of all files.
- commitlint & dangerjs. Linters that help maintain consistency in all user-provided information related to Git and GitHub (commits, branch names, PR titles, etc.).
Since we aimed to reduce our reliance on Google Docs/Sheets wherever possible, especially in cases where we could extract information from existing data instead of conducting manual audits of lectures in Google Sheets for each Academy, we decided to write a script that automatically compiles statistics based on the information already present in the repository. This script was connected to an GitHub Actions that triggers and updates the statistics every time new changes are pushed to the main branch.
Teams. GitHub has an excellent system of teams and permissions that continues to evolve. The most convenient thing is that by adding an Academy participant to one of the teams, the participant automatically gained access to all the necessary repositories and Projects, of which we have quite a few, while only having the permissions they needed.

Since some of our content, such as starters for lecture homework or lecture auto-checks, was already in GitHub repositories, setting up teams and permissions took minimal time because we essentially had everything ready prior to the creation of the Academy delivery process management repository.

The list above only enumerates the main features we use to manage our delivery processes at the Academy. I may have missed some aspects because some of these features have become so familiar that it is sometimes hard to remember how we managed processes without them in the past.

GitHub Gets Better

To be honest, I wanted to write this article after the first Academy when we started actively using GitHub as the primary tool for managing the delivery processes of the Academy. However, I kept delaying it for various reasons. One of the reasons was that I was not entirely satisfied with how we worked around some limitations that existed at the time. For example, as mentioned earlier, we now use custom fields for setting due dates in issues. Before this feature, we had to set due dates directly in the issue body. While this approach worked, it did not look as elegant as due dates in Trello. Nevertheless, even with these workarounds for limitations at the time, we still liked GitHub better. Moreover, we knew that these limitations would soon be addressed, and GitHub with all its features, would become even better. Currently, we do not feel like we are missing anything from the old set of tools we used.

GitHub is constantly evolving, and one of the recent innovations we want to try in the next Academy is called "Project Templates". I think the name itself makes it clear what this feature entails. Currently, for each Academy, we need to create a specific set of issues that always repeats. While we never lose the content of these issues because we use issue templates, it is still repetitive work that needs to be done for every Academy. No one likes to do the same thing over and over again, and project templates were created precisely to automate this task.

The project templates feature is just one example. As mentioned earlier, because GitHub develops features using an open-source development approach, anyone interested can keep track of upcoming feature updates.

Conclusions

GitHub has long ceased to be a tool exclusively for developers. All the toolsets that appear in GitHub allow it to be used for more than just storing code history. Different companies find various uses for it. From managing an open-source blog to hosting a podcast website (by the way, they store all their recordings in repositories).

Some readers might suggest that similar behavior could be achieved by continuing to use Trello and Google Docs/Sheets while adding stricter requirements and constraints. I partly agree with that, but that approach did not work for us. It is precisely because everything in GitHub is integrated, interconnected, and complements each other seamlessly that there's no desire to create anything on a personal account, as was the case with our old tools. Not to mention the additional automation, from grammar mistakes linting to automatic statistics generation, that GitHub provides.

Undoubtedly, we are pleased with the fact that we now manage our delivery processes in GitHub, and the statistics we collect from people participating in the Academy are a testament to its effectiveness.

Before GitHub became our main tool:

After GitHub became our main tool:

While we have not completely eliminated Google Docs/Sheets (although we now use Notion more for this purpose. Yes-yes, one more tool…), it's often easier to quickly create a new MVP for statistics in Google Sheets than to immediately start implementing some logic in GitHub. However, we aim to keep all the essential functionality within GitHub, which serves as the primary tool for controlling all of the Academy's delivery processes.

Coming into the role of Delivery Head of BSA, I was not tasked with establishing a process where every participant understood what they needed to do. While I did not have an exact checklist at that time outlining what each participant should do at each stage, I believe that after 1-2 Academies, I would have formed a similar checklist for myself, and I would have felt confident. The problem is that most likely, I would have been the only one that felt confident with this process. Perhaps for the next people who will support the Academy afterward, it would still not be entirely clear, just as it was for me in the beginning.

Quoting the words of Jimmy Carter, the 39th president of the USA, from my favorite movie "Miracle": "We've always had a faith that the days of our children would be better than our own", by introducing tools like GitHub and all the other innovations into the Academy, which I have implemented and continue to implement, I wanted to facilitate the experience of participating in the Academy for both the current generation and all those who come after us.

What the ideal end of the Academy looks like to me:

JavaScript Naming Conventions are Important

Vladyslav Zubko — Mon, 13 Nov 2023 22:00:00 +0000

IMPORTANT NOTE: The latest updates to the article and changelog can be found by following the link to the original article publication.

It is no secret that developers have to ponder over numerous everyday tasks. Part of their thoughts is always dedicated to various routine matters, such as "In which module should I place this function?", "How should I name this variable?", or "What should this variable do?". Despite these questions appearing simple and trivial, they consistently consume mental resources. However, if there are ways to simplify this process by automating some routine tasks, thereby focusing attention on more critical matters, it undoubtedly makes sense to take advantage of them.

In this context, naming conventions play a crucial role. Acquiring knowledge and employing these conventions judiciously contribute to enhanced code readability, simplifying comprehension, and reducing the developer's cognitive load. However, not all developers are aware of, and sometimes forget, how to correctly apply these conventions, mindlessly diverting their attention to seemingly more critical matters. This, in turn, complicates the readability and understanding of their code, making ostensibly "more critical" tasks more intricate than they could actually be.

Below is a screenshot from a real project I had the opportunity to work on. Take note of each import. Try to guess, based on the names, what item we can obtain from each of the imports.

In this article, we will explore most of them, learning or reminding ourselves which principles are best to follow when choosing names for the constructs you write. This will help both you and anyone who works with your code in the future – whether it is your team or yourself after some time – avoid guesswork and enhance the readability of your code.

JavaScript Naming Conventions

This article will consist of a set of naming recommendations. I would not want you to perceive them as the sole truth. Firstly, it is not entirely the case, as most recommendations come with a disclaimer that there are numerous exceptions, hinting that the conventions themselves do not cover all cases. Secondly, while most recommendations are accepted in the JavaScript community, not everyone follows them for various reasons, and some recommendations are either partially or significantly modified to suit specific teams.

The main message of the article is that each project should establish its naming conventions, whether they align with widely adopted ones or are unique to your team. The crucial aspect is to have conventions and adhere to them.

General Rules

On the internet, there is a considerable number of articles written about best naming practices. Well-known conventions emphasize that a name should be short and, more importantly, understandable. The name should be specific, correspond to the context in which it is used, and convey the meaning of the code at a glance. In reality, these conventions can and should be applied not only when working with JavaScript but also with any programming language. In these general rules, I would like to focus on some specific details in conventions that are widely known but often forgotten or not fully adhered to.

Uniformity. In JavaScript projects, there are numerous conventions, but the most valuable one to adhere to is maintaining a consistent coding style within a single project. Individuals involved in different projects know better than anyone that writing styles can vary significantly between projects.

Situations often arise where different parts of an application are developed by different teams or use different technologies in their development. Naming conventions may differ based on the chosen programming language or the preferences of the development team. Despite these differences, different parts of the application need to interact with each other, such as data exchange between the frontend and backend. For example, the naming style for data requested from the backend might differ from the style used in the frontend code.

Despite the convention in the JavaScript language to write in camelCase, it is worth noting that nothing is preventing the use of, for instance, snake_case. As already mentioned, this notation might be more familiar to many other programming languages and some teams. There might be situations where a naming case different from the style of your application starts creeping into your code.

It is not our place to judge whether using different naming cases is good or bad, as various reasons may drive such choices. However, explicit mixing of two or more naming cases can pose challenges. For new developers joining the project, understanding what is happening and deciding which naming case to use can become quite challenging.
```
// Bad 
const hasAccess = checkHasUserAccess(session.current_user) && checkIsPageVisible(session.current_page)

// Good
const hasAccess = checkHasUserAccess(session.currentUser) && checkIsPageVisible(session.currentPage)

// Also good, if such a naming case is preferred
const has_access = check_has_user_access(session.current_user) && check_is_page_visible(session.current_page)
```
There are several ways to address this issue, ranging from using renaming with destructuring, import renaming, using mapping functions (e.g., Array.prototype.map()), and more advanced approaches like utilizing the Adapter design pattern.

The key is to adopt a consistent approach, not only in naming conventions but also in how tasks are accomplished. Whenever possible, prefer a single method for a particular action. Avoid forcing yourself and other developers to spend time and extra mental resources deciding which approach to use. Consider delegating such tasks, especially those related to coding style, to tools like ESLint.
English only. Despite the fact that you can use non-Latin letters when writing in JavaScript, it is not recommended to do so. While there will not be any programming errors, it is strongly discouraged to use any languages other than English. Even if you are writing something for yourself, every piece of code has the ability to "live long", and there may come a time when you need to share this code with other developers. For other developers, especially from different countries, it will be difficult to understand what is happening in the code.

When emphasizing the use of only English, people often think only about keyboard layout. However, one should not forget about abbreviations and the general use of short forms for names. They should only be used with commonly accepted words, such as idx, err, evt, xhr, src, and other historically accepted words in the community. In other cases, the use of abbreviations and short forms of words is strongly discouraged, as they often lead to confusion, and deciphering them can take a lot of time.
```
// Bad
const 新規ユーザーのウェルカムメッセージ = 'こんにちは'

const usrInf = { fName: 'John', lName: 'Doe' }

const isAdult = a >= 18

// Good
const newUserWelcomeMessage = 'こんにちは'

const userInfo = { firstName: 'John', lastName: 'Doe' }

const isAdult = userAge >= 18
```
It is also recommended to enable a spell checker in your code editor, which will highlight grammatical errors in words. In many editors it is enabled by default, and for some you may need to install an extension, such as Code Spell Checker for VS Code. Today's spell checkers are smart enough, and most commonly accepted abbreviations and short forms of words will not be flagged as errors.
Not only camelCase. Many resources emphasize using camelCase notation exclusively when writing in JavaScript. However, this is not entirely accurate. The recommendation is more about adhering to the notation used by the language itself. While a significant portion of the JavaScript language is written in camelCase, it is not universally so. Here are a few examples:
```
parseInt('18') // camelCase

new RegExp('[A-Z]', 'i') // PascalCase

Number.MAX_SAFE_INTEGER // PascalCase + UPPER_SNAKE_CASE
```
As we can see, JavaScript incorporates not only camelCase notation but also some others. All classes and constructor functions in JavaScript are written using PascalCase notation. When declaring custom classes and constructor functions, it is customary to follow the same naming convention as the language itself. The same applies to constants, representing fixed values. Both built-in JavaScript constants and those created by developers are conventionally named in UPPER_SNAKE_CASE.

In contrast to some programming languages where the API is written using various cases without clear distribution, JavaScript's API does not suffer from this issue. Therefore, it is customary to adhere to the conventions present in the language itself.
Follow readme.md. Suppose you are working with a network request library like axios, and the library's README recommends using the standard name axios for imports.
```
import httpRequester from 'npm:axios'

// Somewhere very far at the bottom of the file

httpRequester('https://example.com')
```
Changing the name from axios to httpRequester can cause confusion and errors, as other developers working on the project and expecting the standard name axios may encounter issues. Therefore, it is important to adhere to the recommendations set in the library's README to ensure compatibility and code understanding.

At first glance, the example with the axios library may seem harmless, but similar renaming scenarios can arise with the use of more complex libraries and frameworks deeply integrated into a project. Teams that adopt meaningful renaming practices will need to create their own documentation because new team members will not find sufficient information in the official documentation to understand the changes in the technology's usage style.

Typically, meaningful renaming into something more abstract, is used in conjunction with the dependency inversion principle. However, it is important to understand the fine line here. You and your team must have a clear understanding of what you are doing and why, as there needs to be a balance in adopting such practices.
No data types. It can be tempting to include data types in variable names, but succumbing to this temptation often adds unnecessary semantic load to the name. For instance, using the name arr for a variable containing an array can lead to conflicts if a variable with the same name is used elsewhere. Moreover, the name arr does not convey meaningful information. Making the name more specific, like userArr, is an improvement, but it does not address all the issues.
```
// Bad
const userNameMinLengthConst = 3

const userObj = getUser()

const getUniqueUserNames = (arr) => Array.from(new Set(arr))

// Good
const USER_NAME_MIN_LENGTH_COUNT = 3

const user = getUser()

const getUniqueUserNames = (names) => Array.from(new Set(names))
```
For each language construct, whether built-in or custom data structures, there exists a conventional way to indicate the intended data type of the value. This is reflected in the name of the construct, which should align with both the established community conventions and those within your team. It is advisable to prioritize community conventions, as explaining something widely accepted is generally easier than introducing something entirely unique. In the case of community conventions, you can refer someone to an internet article, while for team-specific conventions, you might need to write that article yourself.

Specific Rules

In this section, we will discuss specific naming conventions for data types and data structures. While JavaScript may appear limited in its built-in data types and structures, it offers extensive capabilities. These encompass a variety of methods, which in other programming languages are often segregated into distinct built-in types or data structures.

For instance, in JavaScript, an object can serve as an enum, map (dictionary), graph, and more. The number data type in JavaScript includes handling both integers and floating-point numbers. Depending on specific requirements, JavaScript data types and structures can be flexibly adapted for use, providing JavaScript with versatility and power.

It is in this context that the importance of naming conventions becomes clear. They not only enhance code readability but also prevent confusion and errors when interacting with other parts of the codebase. Good naming conventions ensure clarity within the code and facilitate understanding of data structures and their purposes for other developers, contributing to more effective collaboration within a team.

Booleans. Names of boolean values should start with an affirmative prefix, meaning the prefix should answer the question "yes." Although there are several affirmative words (should, can, will, etc.) that answer "yes," it is advisable to prefer the two most common ones – is and has. While using other affirmative words will not be considered an error, their use should be treated as an exception, and if possible, it is better to avoid using them.

An important addition to this convention, often overlooked, is that the affirmative prefix should not include a negation. The reason behind this is that the negation operator (!) is most commonly used with boolean values. Therefore, a value named something like isNotAllowed with the negation applied to it !isNotAllowed can be quite misleading. Do not believe so? Then try quickly figuring out what !!isNotAllowed (double negation) equals. Even if you manage to do it quickly, imagine working with real code where all these negation inversions are scattered throughout the file. Keeping track of such logic, especially when there is a lot of it, can be quite challenging. In such cases, it is better to alter the logic of evaluating the boolean variable using a positive affirmative in its name.
```
// Bad
const userLogin = user !== null

const user = {
  friend: false,
}

const isNotUserRemoved = userActionState !== ActionState.REMOVED
if (isNotUserRemoved) { /* some logic */ }

// Good
const isUserAuthorized = user !== null
const hasUser = user !== null

const user = {
  hasFriend: false,
}

const isUserRemoved = userActionState === ActionState.REMOVED
if (!isUserRemoved) { /* some logic */ }
```
Along with the convention to use affirmative prefixes for boolean names, we diverge from the W3C specification recommendations, as it advises against using these prefixes for boolean names. This contradicts the idea mentioned earlier to prefer conventions used by the language itself. However, there are always exceptions, and this is one of them. It is normal since the way specification authors think may differ from the community's perspective.

JavaScript was created a long time ago, and at the time of its inception, the authors decided not to use affirmative prefixes for boolean names. Now, they do their best by continuing to follow their convention, even if it goes against the community's opinion. Even if the authors wanted to introduce new naming conventions in the specification, they could not do it, at least not coherently. Old code cannot be renamed because JavaScript must remain backward-compatible. And starting to write new code using new approaches is not a great idea either, as there would be two ways to do the same thing, which is also undesirable.

Exceptions are normal. Nothing in this world is perfect. Even the specification itself has exceptions – node.isContentEditable or evt.isTrusted. The key is to try to minimize them while adhering to previously established conventions.
Functions & Methods. The name of a function/method should be a verb and correspond to the action it performs.
```
// Bad
const userNaming = (name) => name.charAt(0).toUpperCase() + name.slice(1)

const user = {
  name: 'John',
  action() {
    console.log('Hey')
  },
}

const userPermissions = (userId) => permissionRepository.getByUserId(userId)

// Good
const getCapitalizedUserName = (name) => name.charAt(0).toUpperCase() + name.slice(1)

const user = {
  name: 'John',
  sayHello() {
    console.log('Hey')
  },
}

const getUserPermissions = (userId) => permissionRepository.getByUserId(userId)
```
Although the naming convention for functions/methods may seem simple at first glance, their naming is the one that has the most exceptions and other conventions.
- Following the JavaScript writing style (Number.isNaN(), Array.isArray(), salary.toFixed(), constructor functions, etc.).
- Naming conventions for event handler functions (onBtnClick, onImgMouseOver, etc.).
- Library functions, for example, a reducer function in the Redux library (const users = (state, action) => { /* some logic */ }), functional components in React (const UserDashboard = () => { /* component */ }), and many other exceptions and conventions proposed by libraries and frameworks.
You can learn about all of them by working directly with them. However, for most functions and methods, the main convention that the name should be a verb and correspond to the action they perform remains unchanged.
Collections & Iterators. The naming convention is as follows – if Iterator or indexed collections (e.g., Array, NodeList, FileList, etc.) are used, the name should be a plural noun. Otherwise, if keyed collections (Set, Map) are used, and we are only interested in values that we can obtain by keys (usually using Array.from() or spread syntax), the naming convention remains the same – the name should be a plural noun. However, if the keys are also important to us in keyed collections, then such collections should be named using a singular noun, and at the end of the name, add one of the prefixes that signifies a set of something. For example, Collection, List, Group, and others.

An important addition is that this convention should also be applied to user-created indexed or keyed collections using Iteration protocols.
```
// Bad
const userRoleArr = Object.values(UserRole)

const usersAccordionList = document.querySelectorAll('.users-accordion__list-item',)

const groupPermissions = new Map(Object.entries(Object.groupBy(permissions, (permission) => permission.group)))

// Good
const userRoles = Object.values(UserRole)

const usersAccordionItemNodes = document.querySelectorAll('.users-accordion__list-item',)

const permissionsByGroupList = new Map(Object.entries(Object.groupBy(permissions, (permission) => permission.group)))
```
Classes. When working with classes, it is important to follow several conventions. Here is the list:
- Use PascalCase for the class name, following the same case style that JavaScript uses for classes and constructor functions.
- The class name should be a singular noun.
- Names of all class members should not include the class name.
```
// Bad
class userService { /* class members */ }

class Permissions { /* class members */ }

class UserAuthPopup {
  isPopupOpen = false

  openPopup() {
    this.isPopupOpen = true
  }
}

// Good
class UserService { /* class members */ }

class PermissionService { /* class mmebers */ }

class UserAuthPopup {
  isOpen = false

  open() {
    this.isOpen = true
  }
}
```
If there is a temptation to use the class name in the names of its members, it is likely that the class is overloaded with logic or is responsible for more things than it should be. In such cases, a violation of the Single Responsibility Principle can often be observed. To avoid such situations, it is recommended to create additional classes and use inheritance or dependency injection to limit the responsibility of each class.
Constants. Used to describe values which are known before the program's execution and that should not change during its execution.

Constants are a crucial and widely adopted approach to organizing a program's code. Regarding naming conventions, there is an important agreement among developers: the name of a constant should be written using the UPPER_SNAKE_CASE notation.
```
// Bad
const userFailingLoginAttempts = 3 

const USER_ROLE = calculateUserRole(user)

let userDefaultAuthMethod = 'mfa'

// Good
const USER_FAILING_LOGIN_ATTEMPTS_COUNT = 3

const userRole = calculateUserRole(user)

let USER_DEFAULT_AUTH_METHOD = 'mfa'
```
Although there are several ways to declare a variable in JavaScript, and for constants, it might seem logical to use only the const keyword, which prevents it from being changed during program execution, as some teams prefer not to worry about choosing the keyword for variable declarations. They may use automation tools like ESLint to enforce the use of only the let keyword for variable declarations in the program code.

Again, every team is different, and each may have its own conventions. However, even the prohibition of using seemingly more appropriate constructs and keywords is not an indicator of how something should be done or named. Naming always carries more meaning than the use of any keywords. This is why naming is such a crucial aspect of code writing.
Enums. Also known as enumerations. In JavaScript, this data structure is used to enumerate a set of fixed values.

Unlike many other programming languages that have a separate data type for enumerations, JavaScript does not have such a data type (at least, as of now). Instead, to simulate an enumeration in JavaScript, a plain object can be used, but with specific naming conventions. Here is a list of these naming conventions:
- The name of the enumeration should start with a capital letter.
- The name of the enumeration should be in the singular noun.
- The keys of the enumeration should be in uppercase.
```
// Bad
const userRole = {
  admin: 'admin',
  guest: 'guest',
}

const USER_API_PATHS = {
  root: '/',
  users$Id: '/users/:id',
}

const userValidationRules = {
  MIN_PASSWORD_LENGTH: 8,
  MAX_NAME_LENGTH: 20,
  VALID_REFERRER_DOMAINS: ['google.com'],
}

// Good
const UserRole = {
  ADMIN: 'admin',
  GUEST: 'guest',
}

const UserApiPath = {
  ROOT: '/',
  USERS_$ID: '/users/:id',
}

const UserValidationRule = {
  MIN_PASSWORD_LENGTH: 8,
  MAX_NAME_LENGTH: 20,
  VALID_REFERRER_DOMAINS: ['google.com'],
}
```
Since TypeScript is now a significant part of JavaScript development, it is worth mentioning that TypeScript has the enum keyword for enumerations. If you decide to use TypeScript's enumerations with your team, it is customary to follow the same naming conventions.
Maps. Also known as a dictionary data structure. This data structure is used for mapping one value to another.

A map is a very useful and frequently used data structure in any programming language. For maps in the JavaScript world, there is a specific naming convention. The name should follow the pattern aToB, where a serves as the key for retrieving values from the map, followed by the preposition To, implying the mapping of two things, and then B, which is the mapped value for a.
```
// Bad
const userRolesReadable = {
  [UserRole.ADMIN]: 'Administrator',
  [UserRole.GUEST]: 'Guest',
}

const REDIRECTING = {
  '/groups': '/admin-login',
  '/profile': '/login',
}

const UserPermissions = {
  [UserRole.ADMIN]: [Permission.MANAGE_USERS, Permission.MANAGE_GROUPS],
  [UserRole.GUEST]: [Permission.EDIT_PROFILE],
}

// Good
const userRoleToReadable = {
  [UserRole.ADMIN]: 'Administrator',
  [UserRole.GUEST]: 'Guest',
}

const pagePathToRedirectPath = {
  '/groups': '/admin-login',
  '/profile': '/login',
}

const userRoleToPermissions = {
  [UserRole.ADMIN]: [Permission.MANAGE_USERS, Permission.MANAGE_GROUPS],
  [UserRole.GUEST]: [Permission.EDIT_PROFILE],
}
```
There is a built-in Map class in JavaScript. The main difference from a regular object is the ability to use any data type (even an object) as a key. Usually, using the native Map class is redundant for creating a map as a data structure. However, if you need the functionality provided by the native Map, you can use it to create a map data structure. In most cases, a regular object will suffice.
Types & Interfaces. As mentioned earlier, TypeScript has become an integral part of JavaScript development today. In general, in most cases, types and interfaces are interchangeable. However, since there are already enough discussions about which one to choose, in this article, we will focus specifically on naming. For types and interfaces, the following naming conventions exist:
- Names of types and interfaces should be written in PascalCase notation.
- The name should describe what the type or interface will be used for, often as straightforwardly as possible: const user: User = getUserById(id) / const users: User[] = getUsers().
- If a development team has decided to actively use both types and interfaces in one codebase, it is recommended to add a prefix to interfaces to distinguish them. The most popular prefixes are I and Contract.
```
// Bad
type TUser = {
  firstName: string
  lastName: string
}

interface user {
  firstName: string
  lastName: string
}

interface userServiceInterface {
  findByEmail: (email: string) => User
}

// Good
type User = {
  firstName: string
  lastName: string
}

interface User {
  firstName: string
  lastName: string
}

interface UserServiceContract {
  findByEmail: (email: string) => User
}
interface IUserService {
  findByEmail: (email: string) => User
}
```

It is important to realize that despite the extensive overview of JavaScript naming conventions in this article, it cannot cover all possible scenarios. Even within the presented points, numerous exceptions should be considered. The naming process, although fundamental, implies flexibility in application, taking into account the unique features and requirements of each project.

Conclusion

During development, we often delve into complex technical details, forgetting that the power often lies in the details. Years of development experience only affirm the truth that attention to details, such as naming, plays a crucial role in creating efficient and readable code. Simplicity and the absence of the need to ponder over how to name a value and how quickly to understand what it contains bring incredible relief in the daily work of a developer.

Can a developer consider themselves strong if their variables are not clearly named? Clear naming not only makes the code more understandable for other developers but also for the programmer themselves, making the development process more efficient and less error-prone.

It often happens that searching for poor naming leads to the discovery of bad code. This only underscores how naming conventions serve as an indicator of code quality. Proper naming reflects care for details, which, in turn, speaks to an attentive approach to development.

Here is how the import of values from the introductory part looks when applying the conventions discussed in this article. Now it looks much clearer, doesn't it? I am sure it will take you much less effort now to understand the meaning of each import.

In conclusion, it is essential to remember that while naming standards are important, they are not absolute. Every project has its peculiarities, and it is crucial to define your conventions. The main thing is that they should exist, and you adhere to them to ensure consistency in the code and improve collective productivity. Also, if possible, try to delegate code style issues to tools like ESLint to simplify and enhance the development process.

ECMAScript Decorators. The Ones That are Real

Vladyslav Zubko — Tue, 24 Oct 2023 10:31:26 +0000

IMPORTANT NOTE: The latest updates to the article and changelog can be found by following the link to the original article publication.

In 2015, ECMAScript 6 was introduced – a significant release of the JavaScript language. This release introduced many new features, such as const/let, arrow functions, classes, etc. Most of these features were aimed at eliminating JavaScript's quirks. For this reason, all these features were labeled as "Harmony." Some sources say that the entire ECMAScript 6 is called "ECMAScript Harmony." In addition to these features, the "Harmony" label highlights other features expected to become part of the specification soon. Decorators are one of such anticipated features.

Nearly 10 years have passed since the first mentions of decorators. The decorators’ specification has been rewritten several times almost from scratch but they have not become part of the specification yet. As JavaScript has long extended beyond just browser-based applications, authors of specifications must consider a wide range of platforms where JavaScript can be executed. This is precisely why progressing to stage 3 for this proposal has taken so much time.

Something Completely New?

First of all, let's clarify what decorators are in the programming world.

“Decorator is a structural design pattern that lets you attach new behaviors to objects by placing these objects inside special wrapper objects that contain the behaviors.”
© https://refactoring.guru/design-patterns/decorator

The key point here is that a decorator is a design pattern. This means that typically it can be implemented in any programming language. If you have even a basic familiarity with JavaScript, chances are you have already used this pattern without even realizing it.

Sound interesting? Then try to guess what the most popular decorator in the world is... Meet the most famous decorator in the world, the higher-order function – debounce.

Debounce

Before we delve into the details of the debounce function, let's remind ourselves what higher-order functions are. Higher-order functions are functions that take one or more functions as arguments or return a function as their result. The debounce function is a prominent example of a higher-order function and at the same time the most popular decorator for JS developers.

The higher-order function debounce delays the invocation of another function until a certain amount of time has passed since the last invocation, without changing its behavior. The most common use case is to prevent sending multiple requests to the server when a user is inputting values into a search bar, such as loading autocomplete suggestions. Instead, it waits until the user has finished or paused input and only then sends the request to the server.

On most resources for learning JavaScript language in the section about timeouts, you will find exercises that involve writing this function. The simplest implementation looks like this:

const debounce = (fn, delay) => {
  let lastTimeout = null

  return (...args) => {
    clearInterval(lastTimeout)

    lastTimeout = setTimeout(() => fn.call(null, ...args), delay)
  }
}

Using this function may look like the following:

class SearchForm {
  constructor() {
    this.handleUserInput = debounce(this.handleUserInput, 300)
  }

  handleUserInput(evt) {
    console.log(evt.target.value)
  }
}

When using a special syntax for decorators which we will discuss in the next section, the implementation of the same behavior will look like this:

class SearchForm {
  @debounce(300)
  handleUserInput(evt) {
    console.log(evt.target.value)
  }
}

All the boilerplate code is gone, leaving only the essentials. Looks nice and clean, doesn't it?

Higher-Order Component (HOC)

The next example will come from the React-world. Although the use of Higher-Order Components (HOC) is becoming less common in applications built with this library, HOCs still serve as a good and well-known example of decorator usage.

Let's take a look at an example of the withModal HOC:

const withModal = (Component) => {
  return (props) => {
    const [isOpen, setIsOpen] = useState(false)

    const handleModalVisibilityToggle = () => setIsOpen(!isOpen)

    return (
      <Component
        {...props}
        isOpen={isOpen}
        onModalVisibilityToggle={handleModalVisibilityToggle}
      />
    )
  }
}

And now, let's see how it can be used:

const AuthPopup = ({ onModalVisibilityToggle }) => {
  // Component
}

const WrappedAuthPopup = withModal(AuthPopup)

export { WrappedAuthPopup as AuthPopup }

Here is what using the HOC with the special decorator syntax would look like:

@withModal()
const AuthPopup = ({ onModalVisibilityToggle }) => {
  // Component
}

export { AuthPopup }

Important Note: Function decorators are not a part of the current proposal. However, they are on the list of things that could be considered for the future development of the decorators specification.

Once again, all the boilerplate code is gone, leaving only what truly matters.

Perhaps some of the readers did not see anything special in this. In the example above, only one decorator was used. Let's take a look at such an example:

const AuthPopup = ({
  onSubmit,
  onFocusTrapInit,
  onModalVisibilityToggle,
}) => {
  // Component
}

const WrappedAuthPopup = withForm(
  withFocusTrap(
    withModal(AuthPopup)
  ), {
  mode: 'submit',
})

export { WrappedAuthPopup as AuthPopup }

See that hard-to-read nesting? How much time did it take you to understand what is happening in the code? Now, let's take a look at the same example but with the use of decorator syntax:

@withForm({ mode: 'submit' })
@withFocusTrap()  
@withModal()
const AuthPopup = ({
  onSubmit,
  onFocusTrapInit,
  onModalVisibilityToggle,
}) => {
  // Component
}

export { AuthPopup }

Would you not agree that the code that goes from top to bottom is much more readable than the previous example with nested function calls?

The higher-order function debounce and the higher-order component withModal are just a few examples of how the decorator pattern is applied in everyday life. This pattern can be found in many frameworks and libraries that we use regularly, although many of us may often not pay attention to it. Try analyzing the project you are working on and look for places where the decorator pattern is applied. You will likely discover more than one such example.

JavaScript Implementations

Before we delve into the decorators proposal itself and its implementation, I would like us to take a look at this image:

With this image, I would like to remind you of the primary purpose for which JavaScript language was originally created. I am not one of those people who like to complain, saying, "Oh, JavaScript is only good for highlighting form fields." Typically, I refer to such individuals as “dinosaurs”.

JavaScript primarily focuses on the end user for whom we write code. This is a crucial point to understand because every time new things are introduced in JavaScript language such as classes with implementations differing from what is found in other programming languages, the same complainers come and start lamenting that things are not done in a user-friendly manner. Quite the opposite, in JavaScript everything is designed with end users in mind, which is something that no other programming language can boast about.

Today, JavaScript is not just a browser language. It can be run in various environments, including on the server. The TC39 committee responsible for introducing new features to the language, faces the challenging task of meeting the needs of all platforms, frameworks, and libraries. However, the primary focus remains on end users in the browser.

History of Decorators

To delve deeper into the history of this proposal, let's review a list of key events.

2014-04 – Stage 0. Decorators were proposed by Yehuda Katz and they were initially intended to become a part of the ECMAScript 7.
```
type Decorator = (
  target: DecoratedClass,
  propertyKey: string,
  descriptor: PropertyDescriptor
) => PropertyDescriptor | void

function debounce(delay: number): PropertyDescriptor {
  return (target, propertyKey, descriptor) => {
    let lastTimeout: number
    const method = descriptor.value

    descriptor.value = (...args: unknown[]) => {
      clearInterval(lastTimeout)

      lastTimeout = setTimeout(() => method.call(null, ...args), delay)
    }

    return descriptor
  }
}
```
Already at this stage, you can see one of the reasons why the decorators API underwent such significant changes later on. The first argument of the decorator was an entire class, even if you were decorating only one of its members. Moreover, it was assumed that developers could mutate this class. JavaScript engines always strive to optimize as much as possible, and in this case, the developer's call to mutate the entire class undermined a significant number of optimizations provided by the engine. Later, we will see that this was indeed a major reason why the decorators API was rewritten multiple times, almost from scratch.
2015-03 – Stage 1. Without significant changes, the proposal advanced to stage 2. However, an event occurred that significantly influenced the further development of this proposal: TypeScript 1.5 was released, which supported decorators. Despite decorators being marked as experimental (--experimentalDecorators), projects like Angular and MobX actively started using them. Furthermore, the overall workflow for these projects assumed the use of decorators exclusively. Due to the popularity of these projects, many developers mistakenly believed that decorators were already a part of the official JS standard.

This created additional challenges for the TC39 committee because they had to consider the expectations and requirements of the developer community as well as optimization issues in language engines.

2016-07 – Stage 2. After the decorators proposal reached stage 2, its API began to undergo significant changes. Furthermore, at one point the proposal was referred to as "ESnext class features for JavaScript." During its development, there were numerous ideas about how decorators could be structured. To get a comprehensive view of the entire history of changes, I recommend reviewing the commits in the proposal's repository. Here is an example of what the decorators API used to look like:

type Decorator = (args: {
  kind: 'method' | 'property' | 'field',
  key: string | symbol,
  isStatic: boolean,
  descriptor: PropertyDescriptor
}) => {
  kind: 'method' | 'property' | 'field',
  key: string | symbol,
  isStatic: boolean,
  descriptor: PropertyDescriptor,
  extras: unknown[]
}

By the end of stage 2, the decorator API looked as follows:

type Decorator = (
  value: DecoratedValue,
  context: {
    kind: 'class' | 'method' | 'getter' | 'setter' | 'field' | 'accessor',
    name: string | symbol,
    access?: {
      get?: () => unknown,
      set?: (value: unknown) => void
    },
    private?: boolean,
    static?: boolean,
    addInitializer?: (initializer: () => void) => void
  }
) => UpdatedDecoratedValue | void

function debounce(delay: number): UpdatedDecoratedValue {
  return (value, context) => {
    let lastTimeout = null

    return (...args) => {
      clearInterval(lastTimeout)

      lastTimeout = setTimeout(() => value.call(null, ...args), delay)
    }
  }
}

The entire stage 2 took 6 years, during which the decorator API underwent significant changes. However, as we can see from the code above, mutations were excluded. This made the proposal more acceptable for JS engines as well as for various platforms, frameworks, and libraries. But the development history of decorators is not over yet.

2020-09 – Announcing MobX 6. Bye-bye Decorators. Some libraries that relied exclusively on decorators started to move away from their old implementation because they understood that the way they were working with decorators would no longer be standardized.

”Using decorators is no longer the norm in MobX. This is good news to some of you, but others will hate it. Rightfully so, because I concur that the declarative syntax of decorators is still the best that can be offered. When MobX started, it was a TypeScript only project, so decorators were available. Still experimental, but obviously they were going to be standardized soon. That was my expectation at least (I did mostly Java and C# before). However, that moment still hasn't come yet, and two decorators proposals have been cancelled in the mean time. Although they still can be transpiled.”
© Michel Weststrate, author of MobX
2022-03 – Stage 3. After years of changes and refinements, decorators finally reached stage 3. Thanks to the extensive adjustments and refinements during the second stage, the third stage began without significant changes. A particular highlight is the creation of a new proposal called Decorator Metadata.
2022-08 – SpiderMonkey Newsletter. SpiderMonkey, the browser engine used by Firefox, became the first engine to begin working on the implementation of decorators. Implementations like this indicate that the proposal is generally ready to become a full-fledged part of the specification.
2022-09 – Babel 7.19.0. Stage 3 decorators. Adding support in a compiler is a very significant update for any proposal. Most proposals have a similar item in their standardization plan and the decorators proposal was no exception.
2022-11 – Announcing TypeScript 4.9. ECMAScript decorators were listed in TS 4.9 Iteration Plan. However, after some time, the TS team decided to move decorators to the 5.0 release. Here is the authors' comment:

“While decorators have reached stage 3, we saw some behavior in the spec that needed to be discussed with the champions. Between addressing that and reviewing the changes, we expect decorators will be implemented in the next version.”

In general, this decision makes sense, as they did not want to risk incorporating a feature into TS prematurely, especially if it did not become part of the standard. There is always a chance of such situations happening. Although in this case, it might not be as significant as the first implementation.

In TS 4.9, only a small part of decorators specification was included – Class Auto-Accessors. This addition to the decorators specification served as a correction for the mutations that were prevalent in the first stages of implementation. The reason behind this is that often there is a desire to make properties reactive, meaning that some effects should occur when the property changes, such as UI re-rendering, for example:
```
class Dashboard extends HTMLElement {
  @reactive
  tab = DashboardTab.USERS
}
```
In the old implementation, with the reactive decorator, you had to mutate the target class by adding additional set and get accessors to achieve the desired behavior. With the use of auto-accessors, this behavior now occurs more explicitly, which in turn allows engines to optimize it better.
```
class Dashboard extends HTMLElement {
  @reactive
  accessor tab = DashboardTab.USERS
}
```
Another interesting thing is how decorators were supposed to work. Since the TS team could not remove the old implementation that worked under the --experimentalDecorators flag, they decided on the following approach: if the --experimentalDecorators flag is present in the configuration, the old implementation will be used. If this flag is not present, then the new implementation will be used.
2023-03 – Announcing TypeScript 5.0. As promised, the TS team released the full version of decorators specification in TS 5.0.
2023-03 – Deno 1.32. Although in version 1.32 Deno supported TS 5.0, they decided to postpone the functionality related to decorators.

“Take note that ES decorators are not yet supported, but we will be working towards enabling them by default in a future version.”
2023-05 – Angular v16 is here. Angular 16 also added support for ECMAScript decorators. However, some other frameworks built around decorators (and which were inspired by Angular?) have stated that they will not make changes toward ECMAScript decorators for now. For many of them, two important aspects are Metadata and Parameter decorators.

”I don't think we'll support JS decorators till the metadata support & parameter decorators are implemented.”
© Kamil Mysliwiec, creator of NextJS
2023-08 – Announcing TypeScript 5.2. In TS 5.2, another standard was added that complements the decorators specification – Decorator Metadata. The primary idea behind this proposal is to simplify decorators' access to class metadata in which they are used. Another reason there were so many debates regarding syntax and usage was that the authors had to create a whole separate proposal for this purpose.

Just Syntactic Sugar or Not?

After all the explanations and examples, you might have a question: "So, are decorators in JavaScript just higher-order functions with special syntax, and that is it?”.

It is not all that simple. In addition to what was mentioned earlier regarding how JavaScript primarily focuses on end-users, it is also worth adding that JS-engines always try to use the new syntax as a reference point to at least attempt to make your JavaScript faster.

import { groupBy } from 'npm:lodash@4.17.21'

const getGroupedOffersByCity = (offers) => {
  return groupBy(offers, (it) => it.city.name)
}

// OR ?

const getGroupedOffersByCity = (offers) => {
  return Object.groupBy(offers, (it) => it.city.name)
}

It may seem like there is no difference, but there are distinctions for the engine. Only in the second case, when native functions are used, can the engine attempt optimization.

Describing how optimizations work in JavaScript engines would require a separate article. Do not hesitate to explore browser source code or search for articles to gain a better understanding of this topic.

It is also important to remember that there are many JavaScript engines, and they all perform optimizations differently. However, if you assist the engine by using native syntax, your application code will generally run faster in most cases.

Possible Extensions

The new syntax in the specification also opens the door for additional features in the future. As an analogy, consider constructor functions and classes. When private fields were introduced in the specification, they were introduced as a feature for classes. For those who staunchly denied the usefulness of classes and claimed that constructor functions were equivalent, private fields became another reason to move away from constructor functions in favor of classes. Such features are likely to continue evolving.

While we can currently achieve many of the same effects as decorators using higher-order functions in many cases, they still do not cover all the potential functionality that will be added to the decorators specification in the future.

The "possible extensions" file in the decorators specification repository provides insights into how the decorators specification may evolve in the future. Some of the points were listed in the first stages but are not present in the current standard, such as parameter decorators. However, there are also entirely new concepts mentioned, like const/let decorators or block decorators. These potential extensions illustrate the ongoing development and expansion of the decorator functionality in JavaScript.

Indeed, numerous proposals and extensions are being considered to enhance the decorators specification further. Some of these proposals like the Decorator Metadata, are already under consideration even though the core decorator specification has not yet been standardized. This underscores the idea that decorators have a promising future in the specification and we can hope to see them become a part of the standard in the near future.

Conclusion

The lengthy consideration of the decorators proposal over 10 years may indeed seem like an extended period. It is true that the early adoption of decorators by leading frameworks and libraries played a role in uncovering the shortcomings of the initial implementation. However, this early adoption also served as an invaluable learning experience, highlighting the importance of harmonizing with web platforms and developing a solution that aligns with both platforms and the developer community, while preserving the essence of decorators. The time spent refining the proposal has ultimately contributed to making it a more robust and well-considered addition to the JavaScript language.

Indeed, decorators will bring significant changes to how we write applications today. Perhaps not immediately, as the current specification primarily focuses on classes, but with all the additions and ongoing work JavaScript code in many applications will soon look different. We are now closer than ever to the moment when we can finally see those ones that are real decorators in the specification. It is an exciting development that promises to enhance the expressiveness and functionality of JavaScript applications.