DEV Community: Maksim Zemskov

Mastering Type-Safe JSON Serialization in TypeScript

Maksim Zemskov — Mon, 26 Feb 2024 19:01:21 +0000

Almost every web application requires data serialization. This need arises in situations like:

Transferring data over the network (e.g. HTTP requests, WebSockets)
Embedding data in HTML (for hydration, for instance)
Storing data in a persistent storage (like LocalStorage)
Sharing data between processes (like web workers or postMessage)

In many cases, data loss or corruption can lead to serious consequences, making it essential to provide a convenient and safe serialization mechanism that helps detect as many errors as possible during the development stage. For these purposes, it's convenient to use JSON as the data transfer format and TypeScript for static code checking during development.

TypeScript serves as a superset of JavaScript, which should enable the seamless use of functions like JSON.stringify and JSON.parse, right? Turns out, despite all its benefits, TypeScript doesn't naturally understand what JSON is and which data types are safe for serialization and deserialization into JSON. Let's illustrate this with an example.

The Problem with JSON in TypeScript

Consider, for example, a function that saves some data to LocalStorage. As LocalStorage cannot store objects, we use JSON serialization here:

interface PostComment {
  authorId: string;
  text: string;
  updatedAt: Date;
}

function saveComment(comment: PostComment) {
    const serializedComment = JSON.stringify(comment);
    localStorage.setItem('draft', serializedComment);
}

We will also need a function to retrieve the data from LocalStorage.

function restoreComment(): PostComment | undefined {
    const text = localStorage.getItem('draft');
    return text ? JSON.parse(text) : undefined;
}

What’s wrong with this code? The first problem is that when restoring the comment, we will get a string type instead of Date for the updatedAt field.

This happens because JSON only has four primitive data types (null, string, number, boolean), as well as arrays and objects. It is not possible to save a Date object in JSON, as well as other objects that are found in JavaScript: functions, Map, Set, etc.

When JSON.stringify encounters a value that cannot be represented in JSON format, type casting occurs. In the case of a Date object, we get a string because the Date object implements the toJson() method, which returns a string instead of a Date object.

const date = new Date('August 19, 1975 23:15:30 UTC');

const jsonDate = date.toJSON();
console.log(jsonDate);
// Expected output: "1975-08-19T23:15:30.000Z"

const isEqual = date.toJSON() === JSON.stringify(date);
console.log(isEqual);
// Expected output: true

The second problem is that the saveComment function returns the PostComment type, in which the date field is of type Date. But we already know that instead of Date, we will actually receive a string type. TypeScript could help us find this error, but why doesn't it?

Turns out, in TypeScript's standard library, the JSON.parse function is typed as (text: string) => any. Due to the use of any, type checking is essentially disabled. In our example, TypeScript simply took our word that the function would return a PostComment containing a Date object.

This TypeScript behavior is inconvenient and unsafe. Our application may crash if we try to treat a string like a Date object. For example, it might break if we call comment.updatedAt.toLocaleDateString().

Indeed, in our small example, we could simply replace the Date object with a numerical timestamp, which works well for JSON serialization. But in real applications, data objects might be extensive, types can be defined in multiple locations, and identifying such an error during development may be a challenging task.

What if we could enhance TypeScript's understanding of JSON?

Dealing with Serialization

To start with, let's figure out how to make TypeScript understand which data types can be safely serialized into JSON. Suppose we want to create a function safeJsonStringify, where TypeScript will check the input data format to ensure it's JSON serializable.

function safeJsonStringify(data: JSONValue) {
    return JSON.stringify(data);
}

In this function, the most important part is the JSONValue type, which represents all possible values that can be represented in the JSON format. The implementation is quite straightforward:

type JSONPrimitive = string | number | boolean | null | undefined;

type JSONValue = JSONPrimitive | JSONValue[] | {
    [key: string]: JSONValue;
};

First, we define the JSONPrimitive type, which describes all the primitive JSON data types. We also include the undefined type based on the fact that when serialized, keys with the undefined value will be omitted. During deserialization, these keys will simply not appear in the object, which in most cases is the same thing.

Next, we describe the JSONValue type. This type uses TypeScript's ability to describe recursive types, which are types that refer to themselves. Here, JSONValue can either be a JSONPrimitive, an array of JSONValue, or an object where all values are of the JSONValue type. As a result, a variable of type JSONValue can contain arrays and objects with unlimited nesting. The values within these will also be checked for compatibility with the JSON format.

Now we can test our safeJsonStringify function using the following examples:

// No errors
safeJsonStringify({
    updatedAt: Date.now()
});

// Yields an error:
// Argument of type '{ updatedAt: Date; }' is not assignable to parameter of type 'JSONValue'.
//   Types of property 'updatedAt' are incompatible.
//     Type 'Date' is not assignable to type 'JSONValue'.
safeJsonStringify({
    updatedAt: new Date();
});

Everything seems to function properly. The function allows us to pass the date as a number, but yields an error if we will pass the Date object.

But let's consider a more realistic example, in which the data passed to the function is stored in a variable and has a described type.

interface PostComment {
    authorId: string;
    text: string;
    updatedAt: number;
};

const comment: PostComment = {...};

// Yields an error:
// Argument of type 'PostComment' is not assignable to parameter of type 'JSONValue'.
//   Type 'PostComment' is not assignable to type '{ [key: string]: JSONValue; }'.
//     Index signature for type 'string' is missing in type 'PostComment'.
safeJsonStringify(comment);

Now, things are getting a bit tricky. TypeScript won't let us assign a variable of type PostComment to a function parameter of type JSONValue, because "Index signature for type 'string' is missing in type 'PostComment'".

So, what is an index signature and why is it missing? Remember how we described objects that can be serialized into the JSON format?

type JSONValue = {
    [key: string]: JSONValue;
};

In this case, [key: string] is the index signature. It means "this object can have any keys in the form of strings, the values of which have the JSONValue type". So, it turns out we need to add an index signature to the PostComment type, right?

interface PostComment {
    authorId: string;
    text: string;
    updatedAt: number;

    // Don't do this:
    [key: string]: JSONValue;
};

In fact, doing so would imply that the comment could contain any arbitrary fields, which is not typically the desired outcome when defining data types in an application.

The real solution to the problem with the index signature comes from Mapped Types, which allow to recursively iterate over fields, even for types that don't have an index signature defined. Combined with generics, this feature allows converting any data type T into another type JSONCompatible<T>, which is compatible with the JSON format.

type JSONCompatible<T> = unknown extends T ? never : {
    [P in keyof T]:
        T[P] extends JSONValue ? T[P] :
        T[P] extends NotAssignableToJson ? never :
        JSONCompatible<T[P]>;
};

type NotAssignableToJson =
    | bigint
    | symbol
    | Function;

The JSONCompatible<T> type is a mapped type that inspects whether a given type T can be safely serialized into JSON. It does this by iterating over each property in type T and doing the following:

The T[P] extends JSONValue ? T[P] : ... conditional type verifies if the property's type is compatible with the JSONValue type, assuring it can be safely converted to JSON. When this is the case, the property's type remains unchanged.
The T[P] extends NotAssignableToJson ? never : ... conditional type verifies if the property’s type isn't assignable to JSON. In this case, the property's type is converted to never, effectively filtering the property out from the final type.
If neither of these conditions is met, the type is recursively checked until a conclusion can be made. This way it works even if the type doesn’t have an index signature.

The unknown extends T ? never :... check at the beginning is used to prevent the unknown type from being converted to an empty object type {}, which is essentially equivalent to the any type.

Another interesting aspect is the NotAssignableToJson type. It consists of two TypeScript primitives (bigint and symbol) and the Function type, which describes any possible function. The Function type is crucial in filtering out any values which aren't assignable to JSON. This is because any complex object in JavaScript is based on the Object type and has at least one function in its prototype chain (e.g., toString()). The JSONCompatible type iterates over all of those functions, so checking functions is sufficient to filter out anything that isn't serializable to JSON.

Now, let's use this type in the serialization function:

function safeJsonStringify<T>(data: JSONCompatible<T>) {
    return JSON.stringify(data);
}

Now, the function uses a generic parameter T and accepts the JSONCompatible<T> argument. This means it takes an argument data of type T, which should be a JSON compatible type. Now we can use the function with data types without an index signature.

The function now uses a generic parameter T that extends from the JSONCompatible<T> type. This means that it accepts an argument data of type T, which ought to be a JSON compatible type. As a result, we can utilize the function with data types that lack an index signature.

interface PostComment {
  authorId: string;
  text: string;
  updatedAt: number;
}

function saveComment(comment: PostComment) {
    const serializedComment = safeJsonStringify(comment);
    localStorage.setItem('draft', serializedComment);
}

This approach can be used whenever JSON serialization is necessary, such as transferring data over the network, embedding data in HTML, storing data in localStorage, transferring data between workers, etc. Additionally, the toJsonValue helper can be used when a strictly typed object without an index signature needs to be assigned to a variable of JSONValue type.

function toJsonValue<T>(value: JSONCompatible<T>): JSONValue {
    return value;
}

const comment: PostComment = {...};

const data: JSONValue = {
    comment: toJsonValue(comment)
};

In this example, using toJsonValue lets us bypass the error related to the missing index signature in the PostComment type.

Dealing with Deserialization

When it comes to deserialization, the challenge is both simpler and more complex simultaneously because it involves both static analysis checks and runtime checks for the received data's format.

From the perspective of TypeScript's type system the challenge is quite simple. Let's consider the following example:

function safeJsonParse(text: string) {
    return JSON.parse(text) as unknown;
}

const data = JSON.parse(text);
//    ^?  unknown

In this instance, we're substituting the any return type with the unknown type. Why choose unknown? Essentially, a JSON string could contain anything, not just the data what we expect to receive. For example, the data format might change between different application versions, or another part of the app could write data to the same LocalStorage key. Therefore, unknown is the safest and most precise choice.

However, working with the unknown type is less convenient than merely specifying the desired data type. Apart from type-casting, there are multiple ways to convert the unknown type into the required data type. One such method is utilizing the Superstruct library to validate data at runtime and throw detailed errors if the data is invalid.

import { create, object, number, string } from 'superstruct';

const PostComment = object({
    authorId: string(),
    text: string(),
    updatedAt: number(),
});

// Note: we no longer need to manually specify the return type
function restoreDraft() {
    const text = localStorage.getItem('draft');
    return text ? create(JSON.parse(text), PostComment) : undefined;
}

Here, the create function acts as a type guard, narrowing the type to the desired Comment interface. Consequently, we no longer need to manually specify the return type.

Implementing a secure deserialization option is only half the story. It's equally crucial not to forget to use it when tackling the next task in the project. This becomes particularly challenging if a large team is working on the project, as ensuring all agreements and best practices are followed can be difficult.

Typescript-eslint can assist in this task. This tool helps identify all instances of unsafe any usage. Specifically, all usages of JSON.parse can be found and it can be ensured that the received data's format is checked. More about getting rid of the any type in a codebase can be read in the article Making TypeScript Truly "Strongly Typed".

Conclusion

Here are the final utility functions and types designed to assist in safe JSON serialization and deserialization. You can test these in the prepared TS Playground.

type JSONPrimitive = string | number | boolean | null | undefined;

type JSONValue = JSONPrimitive | JSONValue[] | {
    [key: string]: JSONValue;
};

type NotAssignableToJson = 
    | bigint 
    | symbol 
    | Function;

type JSONCompatible<T> = unknown extends T ? never : {
    [P in keyof T]: 
        T[P] extends JSONValue ? T[P] : 
        T[P] extends NotAssignableToJson ? never : 
        JSONCompatible<T[P]>;
};

function toJsonValue<T>(value: JSONCompatible<T>): JSONValue {
    return value;
}

function safeJsonStringify<T>(data: JSONCompatible<T>) {
    return JSON.stringify(data);
}

function safeJsonParse(text: string): unknown {
    return JSON.parse(text);
}

These can be used in any situation where JSON serialization is necessary.

I've been using this strategy in my projects for several years now, and it has demonstrated its effectiveness by promptly detecting potential errors during application development.

I hope this article has provided you with some fresh insights. Thank you for reading!

Useful Links

Making TypeScript Truly "Strongly Typed"

Maksim Zemskov — Tue, 12 Sep 2023 06:50:00 +0000

TypeScript claims to be a strongly typed programming language built on top of JavaScript, providing better tooling at any scale. However, TypeScript includes the any type, which can often sneak into a codebase implicitly and lead to a loss of many of TypeScript's advantages.

This article explores ways to take control of the any type in TypeScript projects. Get ready to unleash the power of TypeScript, achieving ultimate type safety and improving code quality.

Disadvantages of Using Any in TypeScript

TypeScript provides a range of additional tooling to enhance developer experience and productivity:

It helps catch errors early in the development stage.
It offers excellent auto-completion for code editors and IDEs.
It allows for easy refactoring of large codebases through fantastic code navigation tools and automatic refactoring.
It simplifies understanding of a codebase by providing additional semantics and explicit data structures through types.

However, as soon as you start using the any type in your codebase, you lose all the benefits listed above. The any type is a dangerous loophole in the type system, and using it disables all type-checking capabilities as well as all tooling that depends on type-checking. As a result, all the benefits of TypeScript are lost: bugs are missed, code editors become less useful, and more.

For instance, consider the following example:

function parse(data: any) {
    return data.split('');
}

// Case 1
const res1 = parse(42);
//           ^  TypeError: data.split is not a function

// Case 2
const res2 = parse('hello');
//    ^  any

In the code above:

You will miss auto-completion inside the parse function. When you type data. in your editor, you won't be given correct suggestions for the available methods for data.
In the first case, there is a TypeError: data.split is not a function error because we passed a number instead of a string. TypeScript is not able to highlight the error because any disables type checking.
In the second case, the res2 variable also has the any type. This means that a single usage of any can have a cascading effect on a large portion of a codebase.

Using any is okay only in extreme cases or for prototyping needs. In general, it is better to avoid using any to get the most out of TypeScript.

Where the Any Type Comes From

It's important to be aware of the sources of the any type in a codebase because explicitly writing any is not the only option. Despite our best efforts to avoid using the any type, it can sometimes sneak into a codebase implicitly.

There are four main sources of the any type in a codebase:

Compiler options in tsconfig.
TypeScript's standard library.
Project dependencies.
Explicit use of any in a codebase.

I have already written articles on Key Considerations in tsconfig and Improving Standard Library Types for the first two points. Please check them out if you want to improve type safety in your projects.

This time, we will focus on automatic tools for controlling the appearance of the any type in a codebase.

Stage 1: Using ESLint

ESLint is a popular static analysis tool used by web developers to ensure best practices and code formatting. It can be used to enforce coding styles and find code that doesn't adhere to certain guidelines.

ESLint can also be used with TypeScript projects, thanks to typesctipt-eslint plugin. Most likely, this plugin has already been installed in your project. But if not, you can follow the official getting started guide.

The most common configuration for typescript-eslint is as follows:

module.exports = {
    extends: [
        'eslint:recommended',
        'plugin:@typescript-eslint/recommended',
    ],
    plugins: ['@typescript-eslint'],
    parser: '@typescript-eslint/parser',
    root: true,
};

This configuration enables eslint to understand TypeScript at the syntax level, allowing you to write simple eslint rules that apply to manually written types in a code. For example, you can forbid the explicit use of any.

The recommended preset contains a carefully selected set of ESLint rules aimed at improving code correctness. While it's recommended to use the entire preset, for the purpose of this article, we will focus only on the no-explicit-any rule.

no-explicit-any

TypeScript's strict mode prevents the use of implied any, but it doesn't prevent any from being explicitly used. The no-explicit-any rule helps to prohibit manually writing any anywhere in a codebase.

// ❌ Incorrect
function loadPokemons(): any {}
// ✅ Correct
function loadPokemons(): unknown {}

// ❌ Incorrect
function parsePokemons(data: Response<any>): Array<Pokemon> {}
// ✅ Correct
function parsePokemons(data: Response<unknown>): Array<Pokemon> {}

// ❌ Incorrect
function reverse<T extends Array<any>>(array: T): T {}
// ✅ Correct
function reverse<T extends Array<unknown>>(array: T): T {}

The primary purpose of this rule is to prevent the use of any throughout the team. This is a means of strengthening the team's agreement that the use of any in the project is discouraged.

This is a crucial goal because even a single use of any can have a cascading impact on a significant portion of the codebase due to type inference. However, this is still far from achieving ultimate type safety.

Why no-explicit-any is Not Enough

Although we have dealt with explicitly used any, there are still many implied any within a project's dependencies, including npm packages and TypeScript's standard library.

Consider the following code, which is likely to be seen in any project:

const response = await fetch('https://pokeapi.co/api/v2/pokemon');
const pokemons = await response.json();
//    ^?  any

const settings = JSON.parse(localStorage.getItem('user-settings'));
//    ^?  any

Both variables pokemons and settings were implicitly given the any type. Neither no-explicit-any nor TypeScript's strict mode will warn us in this case. Not yet.

This happens because the types for response.json() and JSON.parse() come from TypeScript's standard library, where these methods have an explicit any annotation. We can still manually specify a better type for our variables, but there are nearly 1,200 occurrences of any in the standard library. It's nearly impossible to remember all the cases where any can sneak into our codebase from the standard library.

The same goes for external dependencies. There are many poorly typed libraries in npm, with most still being written in JavaScript. As a result, using such libraries can easily lead to a lot of implicit any in a codebase.

Generally, there are still many ways for any to sneak into our code.

Stage 2: Enhancing Type Checking Capabilities

Ideally, we would like to have a setting in TypeScript that makes the compiler complain about any variable that has received the any type for any reason. Unfortunately, such a setting does not currently exist and is not expected to be added.

We can achieve this behavior by using the type-checked mode of the typescript-eslint plugin. This mode works in conjunction with TypeScript to provide complete type information from the TypeScript compiler to ESLint rules. With this information, it is possible to write more complex ESLint rules that essentially extend the type-checking capabilities of TypeScript. For instance, a rule can find all variables with the any type, regardless of how any was obtained.

To use type-aware rules, you need to slightly adjust ESLint configuration:

module.exports = {
    extends: [
        'eslint:recommended',
-       'plugin:@typescript-eslint/recommended',
+       'plugin:@typescript-eslint/recommended-type-checked',
    ],
    plugins: ['@typescript-eslint'],
    parser: '@typescript-eslint/parser',
+   parserOptions: {
+       project: true,
+       tsconfigRootDir: __dirname,
+   },
    root: true,
};

To enable type inference for typescript-eslint, add parserOptions to ESLint configuration. Then, replace the recommended preset with recommended-type-checked. The latter preset adds about 17 new powerful rules. For the purpose of this article, we will focus on only 5 of them.

no-unsafe-argument

The no-unsafe-argument rule searches for function calls in which a variable of type any is passed as a parameter. When this happens, type checking is lost, and all the benefits of strong typing are also lost.

For example, let's consider a saveForm function that requires an object as a parameter. Suppose we receive JSON, parse it, and obtain an any type.

// ❌ Incorrect

function saveForm(values: FormValues) {
    console.log(values);
}

const formValues = JSON.parse(userInput);
//    ^?  any

saveForm(formValues);
//       ^  Unsafe argument of type `any` assigned
//          to a parameter of type `FormValues`.

When we call the saveForm function with this parameter, the no-unsafe-argument rule flags it as unsafe and requires us to specify the appropriate type for the value variable.

This rule is powerful enough to deeply inspect nested data structures within function arguments. Therefore, you can be confident that passing objects as function arguments will never contain untyped data.

// ❌ Incorrect

saveForm({
    name: 'John',
    address: JSON.parse(addressJson),
//  ^  Unsafe assignment of an `any` value.
});

The best way to fix the error is to use TypeScript’s type narrowing or a validation library such as Zod or Superstruct. For instance, let's write the parseFormValues function that narrows the precise type of parsed data.

// ✅ Correct

function parseFormValues(data: unknown): FormValues {
    if (
        typeof data === 'object' &&
        data !== null &&
        'name' in data &&
        typeof data['name'] === 'string' &&
        'address' in data &&
        typeof data.address === 'string'
    ) {
        const { name, address } = data;
        return { name, address };
    }
    throw new Error('Failed to parse form values');
}

const formValues = parseFormValues(JSON.parse(userInput));
//    ^?  FormValues

saveForm(formValues);

Note that it is allowed to pass the any type as an argument to a function that accepts unknown, as there are no safety concerns associated with doing so.

Writing data validation functions can be a tedious task, especially when dealing with large amounts of data. Therefore, it is worth considering the use of a data validation library. For instance, with Zod, the code would look like this:

// ✅ Correct

import { z } from 'zod';

const schema = z.object({
    name: z.string(),
    address: z.string(),
});

const formValues = schema.parse(JSON.parse(userInput));
//    ^?  { name: string, address: string }

saveForm(formValues);

no-unsafe-assignment

The no-unsafe-assignment rule searches for variable assignments in which a value has the any type. Such assignments can mislead the compiler into thinking that a variable has a certain type, while the data may actually have a different type.

Consider the previous example of JSON parsing:

// ❌ Incorrect

const formValues = JSON.parse(userInput);
//    ^  Unsafe assignment of an `any` value

Thanks to the no-unsafe-assignment rule, we can catch the any type even before passing formValues elsewhere. The fixing strategy remains the same: We can use type narrowing to provide a specific type to the variable's value.

// ✅ Correct

const formValues = parseFormValues(JSON.parse(userInput));
//    ^?  FormValues

no-unsafe-member-access and no-unsafe-call

These two rules trigger much less frequently. However, based on my experience, they are really helpful when you are trying to use poorly typed third-party dependencies.

The no-unsafe-member-access rule prevents us from accessing object properties if a variable has the any type, since it may be null or undefined.

The no-unsafe-call rule prevents us from calling a variable with the any type as a function, as it may not be a function.

Let's imagine that we have a poorly typed third-party library called untyped-auth:

// ❌ Incorrect

import { authenticate } from 'untyped-auth';
//       ^?  any

const userInfo = authenticate();
//    ^?  any    ^  Unsafe call of an `any` typed value.

console.log(userInfo.name);
//          ^  Unsafe member access .name on an `any` value.

The linter highlights two issues:

Calling the authenticate function can be unsafe, as we may forget to pass important arguments to the function.
Reading the name property from the userInfo object is unsafe, as it will be null if authentication fails.

The best way to fix these errors is to consider using a library with a strongly typed API. But if this is not an option, you can augment the library types yourself. An example with the fixed library types would look like this:

// ✅ Correct

import { authenticate } from 'untyped-auth';
//       ^?  (login: string, password: string) => Promise<UserInfo | null>

const userInfo = await authenticate('test', 'pwd');
//    ^?  UserInfo | null    

if (userInfo) {
    console.log(userInfo.name);
}

no-unsafe-return

The no-unsafe-return rule helps to not accidentally return the any type from a function that should return something more specific. Such cases can mislead the compiler into thinking that a returned value has a certain type, while the data may actually have a different type.

For instance, suppose we have a function that parses JSON and returns an object with two properties.

// ❌ Incorrect

interface FormValues {
    name: string;
    address: string;
}

function parseForm(json: string): FormValues {
    return JSON.parse(json);
    //     ^  Unsafe return of an `any` typed value.
}

const form = parseForm('null');

console.log(form.name);
//          ^  TypeError: Cannot read properties of null

The parseForm function may lead to runtime errors in any part of the program where it is used, since the parsed value is not checked. The no-unsafe-return rule prevents such runtime issues.

Fixing this is easy by adding validation to ensure that the parsed JSON matches the expected type. Let's use the Zod library this time:

// ✅ Correct

import { z } from 'zod';

const schema = z.object({
    name: z.string(),
    address: z.string(),
});

function parseForm(json: string): FormValues {
    return schema.parse(JSON.parse(json));
}

A Note About Performance

Using type-checked rules comes with a performance penalty for ESLint since it must invoke TypeScript's compiler to infer all the types. This slowdown is mainly noticeable when running the linter in pre-commit hooks and in CI, but it is not noticeable when working in an IDE. The type checking is performed once on IDE startup and then updates the types as you change the code.

It is worth noting that just inferring the types works faster than the usual invocation of the tsc compiler. For example, on our most recent project with about 1.5 million lines of TypeScript code, type checking through tsc takes about 11 minutes, while the additional time required for ESLint's type-aware rules to bootstrap is only about 2 minutes.

For our team, the additional safety provided by using type-aware static analysis rules is worth the tradeoff. On smaller projects, this decision is even easier to make.

Conclusion

Controlling the use of any in TypeScript projects is crucial for achieving optimal type safety and code quality. By utilizing the typescript-eslint plugin, developers can identify and eliminate any occurrences of the any type in their codebase, resulting in a more robust and maintainable codebase.

By using type-aware eslint rules, any appearance of the keyword any in our codebase will be a deliberate decision rather than a mistake or oversight. This approach safeguards us from using any in our own code, as well as in the standard library and third-party dependencies.

Overall, a type-aware linter allows us to achieve a level of type safety similar to that of statically typed programming languages such as Java, Go, Rust, and others. This greatly simplifies the development and maintenance of large projects.

I hope you have learned something new from this article. Thank you for reading!

Useful Links

Unleashing the Power of TypeScript: Improving Standard Library Types

Maksim Zemskov — Mon, 14 Aug 2023 12:27:00 +0000

In my previous article, we discussed how to configure TypeScript’s compiler to catch more errors, reduce usage of the any type, and obtain a better Developer Experience. However, properly configuring the tsconfig file is not enough. Even when following all the recommendations, there is still a significant risk of suboptimal type checking quality in our codebase.

The issue is that our code is not the only code required to build an application. The standard library and runtime environment are also involved in type checking. These refer to the JavaScript methods and Web Platform APIs that are available in the global scope, including methods for working with arrays, the window object, Fetch API, and more.

In this article, we will explore some of the most common issues with TypeScript's standard library and ways to write safer, more reliable code.

The Issue with TypeScript's Standard Library

While the TypeScript’s Standard Library provides high-quality type definitions for the most part, some widely-used APIs have type declarations that are either too permissive or too restrictive.

The most common issue with too permissive types is the use of any instead of more precise types, such as unknown. The Fetch API is the most common source of type safety issues in the standard library. The json() method returns a value of type any, which can lead to runtime errors and type mismatches. The same goes for the JSON.parse method.

async function fetchPokemons() {
    const response = await fetch('https://pokeapi.co/api/v2/pokemon');
    const data = await response.json();
    return data;
}

const pokemons = await fetchPokemons();
//    ^?  any

pokemons.data.map(pokemon => pokemon.name);
//            ^  TypeError: Cannot read properties of undefined

On the other hand, there are APIs with unnecessarily restrictive type declarations, which can lead to a poorer developer experience. For example, the Array.filter method works counter-intuitively, requiring developers to manually type cast or write type guards.

// the type of filteredArray is Array<number | undefined>
const filteredArray = [1, 2, undefined].filter(Boolean);

// the type of filteredArray is Array<number>
const filteredArray = [1, 2, undefined].filter(
    (item): item is number => Boolean(item)
);

There is no easy way to upgrade or replace type declarations for the standard library since its type definitions are shipped with the TypeScript compiler. However, there are several ways to work around this issue if we want to get the most out of using TypeScript. Let's explore some options using the Fetch API as an example.

Using Type Assertions

One solution that quickly comes to mind is to manually specify a type. To do this, we need to describe the response format and cast any to the desired type. By doing so, we can isolate the use of any to a small piece of the codebase, which is already much better than using the returned any type throughout a program.

interface PokemonListResponse {
    count: number;
    next: string | null;
    previous: string | null;
    results: Pokemon[];
}

interface Pokemon {
    name: string;
    url: string;
}

async function fetchPokemons() {
    const response = await fetch('https://pokeapi.co/api/v2/pokemon');
    const data = await response.json() as PokemonListResponse;
    //                                 ^  Manually cast the any
    //                                    to a more precise type
    return data;
}

const pokemons = await fetchPokemons();
//    ^?  PokemonListResponse

In addition, TypeScript will now highlight errors with access to non-existent fields. However, it should be understood that type casting imposes additional responsibility on us to accurately describe the type that is returned from the server.

pokemons.data.map(pokemon => pokemon.name);
//       ^  Error: Property 'data' does not exist on type 'PokemonListResponse'
//          We shold use the 'results' field here.

Type assertions can be risky and should be used with caution. They can result in unexpected behavior if the assertion is incorrect. For example, there is a high risk of making mistakes when describing types, such as overlooking the possibility of a field being null or undefined.

Additionally, if the response format on a server changes unexpectedly, we may not become aware of it as quickly as possible.

Using Type Guards

We can enhance the solution by first casting any to unknown. This clearly indicates that the fetch function can return any type of data. We then need to verify that the response has the data we need by writing a type guard, as shown below:

function isPokemonListResponse(data: unknown): data is PokemonListResponse {
    if (typeof data !== 'object' || data === null) return false;
    if (typeof data.count !== 'number') return false;
    if (data.next !== null && typeof data.next !== 'string') return false;
    if (data.previous !== null && typeof data.previous !== 'string') return false;

    if (!Array.isArray(data.results)) return false;
    for (const pokemon of data.results) {
        if (typeof pokemon.name !== 'string') return false;
        if (typeof pokemon.url !== 'string') return false;
    }

    return true;
}

The type guard function takes a variable with the unknown type as input. The is operator is used to specify the output type, indicating that we have checked the data in the data variable and it has this type. Inside the function, we write all the necessary checks that verify all the fields we are interested in.

We can use the resulting type guard to narrow the unknown type down to the type we want to work with. This way, if the response data format changes, we can quickly detect it and handle the situation in application logic.

async function fetchPokemons() {
    const response = await fetch('https://pokeapi.co/api/v2/pokemon');
    const data = (await response.json()) as unknown;
    //                                   ^  1. Cast to unknown

    // 2. Validate the response
    if (!isPokemonListResponse(data)) {
        throw new Error('Неизвестный формат ответа');
    }

    return data;
}

const pokemons = await fetchPokemons();
//    ^?  PokemonListResponse

However, writing type guards can be tedious, especially when dealing with large amounts of data. Additionally, there is a high risk of making mistakes in the type guard, which is equivalent to making a mistake in the type definition itself.

Using the Zod Library

To simplify the writing of type guards, we can use a library for data validation such as Zod. With Zod, we can define a data schema and then call a function that checks the data format against this schema.

import { z } from 'zod';

const schema = z.object({
    count: z.number(),
    next: z.string().nullable(),
    previous: z.string().nullable(),
    results: z.array(
        z.object({
            name: z.string(),
            url: z.string(),
        })
    ),
});

These types of libraries are initially developed with TypeScript in mind, so they have a nice feature. They allow us to describe the data schema once and then automatically get the type definition. This eliminates the need to manually describe TypeScript interfaces and removes duplication.

type PokemonListResponse = z.infer<typeof schema>;

This function essentially acts as a type guard, which we don't have to write manually.

async function fetchPokemons() {
    const response = await fetch('https://pokeapi.co/api/v2/pokemon');
    const data = (await response.json()) as unknown;
    // Validate the response
    return schema.parse(data);
}

const pokemons = await fetchPokemons();
//    ^?  PokemonListResponse

As a result, we get a reliable solution that leaves no room for human error. Mistakes in type definitions cannot be made since we don't write them manually. Mistakes in type guards are also impossible. Mistakes in the schema can be made, but we will quickly become aware of them during development.

Alternatives for Zod

Zod has many alternatives that differ in functionality, bundle size, and performance. For each application, you can choose the most suitable option.

For example, the superstruct library is a lighter alternative to Zod. This library is more suitable for use on the client side since it has a relatively small size (13.1 kB vs 3.4 kB).

The typia library is a slightly different approach with ahead-of-time compilation. Due to compilation stage, data validation works significantly faster. This can be especially important for heavy server code or for large volumes of data.

Fixing the Root Cause

Using libraries such as Zod for data validation can help overcome the issue of any types in TypeScript's standard library. However, it is still important to be aware of standard library methods that return any, and to replace these types with unknown whenever we use these methods.

Ideally, the standard library should use unknown types instead of any. This would enable the compiler to suggest all the places where a type guard is needed. Fortunately, TypeScript's declaration merging feature provides this possibility.

In TypeScript, interfaces have a useful feature where multiple declarations of an interface with the same name will be merged into one declaration. For example, if we have an interface User with a name field, and then declare another interface User with an age field, the resulting User interface will have both the name and age fields.

interface User {
    name: string;
}

interface User {
    age: number;
}

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

This feature works not only within a single file but also globally across the project. This means that we can use this feature to extend the Window type or even to extend types for external libraries, including the standard library.

declare global {
    interface Window {
        sayHello: () => void;
    }
}

window.sayHello();
//     ^  TypeScript now knows about this method

By using declaration merging, we can fully resolve the issue of any types in TypeScript's standard library.

Better Types for Fetch API

To improve the Fetch API from the standard library, we need to correct the types for the json() method so that it always returns unknown instead of any. Firstly, we can use the "Go to Type Definition" function in an IDE to determine that the json method is part of the Response interface.

interface Response extends Body {
    readonly headers: Headers;
    readonly ok: boolean;
    readonly redirected: boolean;
    readonly status: number;
    readonly statusText: string;
    readonly type: ResponseType;
    readonly url: string;
    clone(): Response;
}

However, we cannot find the json() method among the methods of Response. Instead, we can see that the Response interface inherits from the Body interface. So, we look into the Body interface to find the method we need. As we can see, the json() method actually returns the any type.

interface Body {
    readonly body: ReadableStream<Uint8Array> | null;
    readonly bodyUsed: boolean;
    arrayBuffer(): Promise<ArrayBuffer>;
    blob(): Promise<Blob>;
    formData(): Promise<FormData>;
    text(): Promise<string>;
    json(): Promise<any>;
    //              ^  We are going to fix this
}

To fix this, we can define the Body interface once in our project as follows:.

declare global {
    interface Body {
        json(): Promise<unknown>;
    }
}

Thanks to declaration merging, the json() method will now always return the unknown type.

async function fetchPokemons() {
    const response = await fetch('https://pokeapi.co/api/v2/pokemon');
    const data = await response.json();
    //    ^?  unknown
    return data;
}

This means that forgetting to write a type guard will no longer be possible, and the any type will no longer be able to sneak into our code.

Better Types for JSON.parse

In the same way, we can fix JSON parsing. By default, the parse() method returns the any type, which can lead to runtime errors when using parsed data.

const data = JSON.parse(text);
//    ^?  any

To fix this, we need to figure out that the parse() method is part of the JSON interface. Then we can declare the type in our project as follows:

declare global {
    interface JSON {
        parse(
            text: string, 
            reviver?: (this: any, key: string, value: any) => any
        ): unknown;
    }
}

Now, JSON parsing always returns the unknown type, for which we will definitely not forget to write a type guard. This leads to a safer and more maintainable codebase.

const data = JSON.parse(text);
//    ^?  unknown

Better Types for Array.isArray

Another common example is checking if a variable is an array. By default, this method returns an array of any, which is essentially the same as just using any.

if (Array.isArray(userInput)) {
    console.log(userInput);
    //          ^?  any[]
}

We have already learned how to fix the issue. By extending the types for the array constructor as shown below, the method now returns an array of unknown, which is much safer and more accurate.

declare global {
    interface ArrayConstructor {
        isArray(arg: any): arg is unknown[];
    }
}

if (Array.isArray(userInput)) {
    console.log(userInput);
    //          ^?  unknown[]
}

Better Types for structuredClone

Unfortunately, the recently introduced method for cloning objects also returns any.

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

const copy = structuredClone(user);
//    ^?  any

Fixing it is just as simple as the previous methods. However, in this case, we need to add a new function signature instead of augmenting the interface. Fortunately, declaration merging works for functions just like it does for interfaces. Therefore, we can fix the issue as follows:

declare global {
    declare function structuredClone<T>(value: T, options?: StructuredSerializeOptions): T;
}

The cloned object will now be of the same type as the original object.

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

const copy = structuredClone(user);
//    ^?  { name: string, age: number }

Better Types for Array.filter

Declaration merging is not only useful for fixing the any type issue, but it can also improve the ergonomics of the standard library. Let's consider the example of the Array.filter method.

const filteredArray = [1, 2, undefined].filter(Boolean);
//    ^?  Array<number | undefined>

We can teach TypeScript to automatically narrow the array type after applying the Boolean filter function. To do so, we need to extend the Array interface as follows:

type NonFalsy<T> = T extends false | 0 | "" | null | undefined | 0n ? never : T;

declare global {
    interface Array<T> {
      filter(predicate: BooleanConstructor, thisArg?: any): Array<NonFalsy<T>>;
    }
}

Describing how the NonFalsy type works requires a separate article, so I will leave this explanation for another time. The important thing is that now we can use the shorthand form of the filter and get the correct data type as a result.

const filteredArray = [1, 2, undefined].filter(Boolean);
//    ^?  Array<number>

Introducing ts-reset

TypeScript's standard library contains over 1,000 instances of the any type. There are many opportunities to improve the developer experience when working with strictly typed code. One solution to avoid having to fix the standard library yourself is to use the ts-reset library. It is easy to use and only needs to be imported once in your project.

import "@total-typescript/ts-reset";

The library is relatively new, so it does not yet have as many fixes to the standard library as I would like. However, I believe this is just the beginning. It is important to note that ts-reset only contains safe changes to global types that do not lead to potential runtime bugs.

Caution Regarding Usage in Libraries

Improving TypeScript's standard library has many benefits. However, it is important to note that redefining global types of the standard library limits this approach to applications only. It is mostly unsuitable for libraries because using such a library would unexpectedly change the behavior of global types for the application.

In general, it is recommended to avoid modifying TypeScript's standard library types in libraries. Instead, you can use static analysis tools to achieve similar results in terms of code quality and type safety, which are suitable for library development. I will write another article about this soon.

Conclusion

TypeScript's standard library is a crucial component of the TypeScript Compiler, providing a comprehensive range of built-in types for working with JavaScript and Web Platform APIs. However, the standard library is not perfect, and there are issues with some of the type declarations that can lead to suboptimal type checking quality in our codebase. In this article, we explored some of the most common issues with TypeScript's standard library and ways to write safer and more reliable code.

By using type assertions, type guards, and libraries such as Zod, we can improve the type safety and code quality in our codebase. Additionally, we can fix the root cause of the issue by using declaration merging to improve the type safety and ergonomics of TypeScript's standard library.

I hope you have learned something new from this article. In the next article, we will discuss how to use static analysis tools to further improve type safety. Thank you for reading!

Useful Links

Unleashing the Power of TypeScript: Key Considerations in tsconfig

Maksim Zemskov — Sun, 16 Jul 2023 08:35:16 +0000

If you're building complex web applications, TypeScript is likely your programming language of choice. TypeScript is well-loved for its strong type system and static analysis capabilities, making it a powerful tool for ensuring that your code is robust and error-free. It also accelerates the development process through integration with code editors, allowing developers to navigate the code more efficiently and get more accurate hints and auto-completion, as well as enabling safe refactoring of large amounts of code.

The Compiler is the heart of TypeScript, responsible for checking type correctness and transforming TypeScript code into JavaScript. However, to fully utilize TypeScript's power, it's important to configure the Compiler correctly. Each TypeScript project has one or more tsconfig.json files that hold all the configuration options for the Compiler.

Configuring tsconfig is a crucial step in achieving optimal type safety and developer experience in your TypeScript projects. By taking the time to carefully consider all of the key factors involved, you can speed up the development process and ensure that your code is robust and error-free.

Downsides of the Standard Configuration

The default configuration in tsconfig can cause developers to miss out on the majority of benefits of TypeScript. This is because it does not enable many powerful type checking capabilities. By "default" configuration, I mean a configuration where no type checking compiler options are set. For example:

{
    "compilerOptions": {
        "target": "esnext",
        "module": "esnext",
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "skipLibCheck": true,
    },
    "include": ["src"]
}

The absence of several key configuration options can result in lower code quality for two primary reasons. Firstly, TypeScript's compiler may incorrectly handle null and undefined types in various cases. Secondly, the any type may appear uncontrollably in your codebase, leading to disabled type checking around this type.

Fortunately, these issues are easy to fix by tweaking a few options in the configuration.

The Strict Mode

{
    "compilerOptions": {
        "strict": true
    }
}

Strict mode is an essential configuration option that provides stronger guarantees of program correctness by enabling a wide range of type checking behaviors. Enabling strict mode in the tsconfig file is a crucial step towards achieving maximum type safety and a better developer experience. It requires a little extra effort in configuring tsconfig, but it can go a long way in improving the quality of your project.

The strict compiler option enables all of the strict mode family options, which include noImplicitAny, strictNullChecks, strictFunctionTypes, among others. These options can also be configured separately, but it's not recommended to turn off any of them. Let's look at examples to see why.

Implicit Any Inferring

{
    "compilerOptions": {
        "noImplicitAny": true
    }
}

The any type is a dangerous loophole in the static type system and using it disables all type checking rules. As a result, all benefits of TypeScript are lost: bugs are missed, code editor hints stop working properly, and so on. Using any is okay only in extreme cases or for prototyping needs. Despite our best efforts, the any type can sometimes sneak into a codebase implicitly.

By default, the compiler forgives us a lot of errors in exchange for the appearance of any in a codebase. Specifically, TypeScript allows us to not specify the type of variables, even when the type cannot be inferred automatically. The problem is that we may accidentally forget to specify the type of a variable, for example, to a function argument. Instead of showing an error, TypeScript will automatically infer the type of the variable as any.

function parse(str) {
    //         ^?  any
    return str.split('');
}

// TypeError: str.split is not a function
const res1 = parse(42);

const res2 = parse('hello');
//    ^?  any

Enabling the noImplicitAny compiler option will cause the compiler to highlight all places where the type of a variable is automatically inferred as any. In our example, TypeScript will prompt us to specify the type for the function argument.

function parse(str) {
    //         ^  Error: Parameter 'str' implicitly has an 'any' type.
    return str.split('');
}

When we specify the type, TypeScript will quickly catch the error of passing a number to a string parameter. The return value of the function, stored in the variable res2, will also have the correct type.

function parse(str: string) {
    return str.split('');
}

const res1 = parse(42);
//                 ^  Error: Argument of type 'number' is not
//                    assignable to parameter of type 'string'

const res2 = parse('hello');
//    ^?  string[]

Unknown Type in Catch Variables

{
    "compilerOptions": {
        "useUnknownInCatchVariables": true
    }
}

Configuring useUnknownInCatchVariables allows for safe handling of exceptions in try-catch blocks. By default, TypeScript assumes that the error type in a catch block is any, which allows us to do anything with the error. For example, we could pass the caught error as-is to a logging function that accepts an instance of Error.

function logError(err: Error) {
    // ...
}

try {
    return JSON.parse(userInput);
} catch (err) {
    //   ^?  any

    logError(err);
}

However, in reality, there are no guarantees about the type of error, and we can only determine its true type at runtime when the error occurs. If the logging function receives something that is not an Error, this will result in a runtime error.

Therefore, the useUnknownInCatchVariables option switches the type of the error from any to unknown to remind us to check the type of the error before doing anything with it.

try {
    return JSON.parse(userInput);
} catch (err) {
    //   ^?  unknown

    // Now we need to check the type of the value
    if (err instanceof Error) {
        logError(err);
    } else {
        logError(new Error('Unknown Error'));
    }
}

Now, TypeScript will prompt us to check the type of the err variable before passing it to the logError function, resulting in more correct and safer code. Unfortunately, this option does not help with typing errors in promise.catch() functions or callback functions. But we will discuss ways to deal with any in such cases in the next article.

Type Checking for the Call and Apply Methods

{
    "compilerOptions": {
        "strictBindCallApply": true
    }
}

Another option fixes the appearance of any in function calls via call and apply. This is a less common case than the first two, but it's still important to consider. By default, TypeScript does not check types in such constructions at all.

For example, we can pass anything as an argument to a function, and in the end, we will always receive the any type.

function parse(value: string) {
    return parseInt(value, 10);
}

const n1 = parse.call(undefined, '10');
//    ^?  any

const n2 = parse.call(undefined, false);
//    ^?  any

Enabling the strictBindCallApply option makes TypeScript smarter, so the return type will be correctly inferred as number. And when trying to pass an argument of the wrong type, TypeScript will point to the error.

function parse(value: string) {
    return parseInt(value, 10);
}

const n1 = parse.call(undefined, '10');
//    ^?  number

const n2 = parse.call(undefined, false);
//                               ^  Argument of type 'boolean' is not
//                                  assignable to parameter of type 'string'.

Strict Types for Execution Context

{
    "compilerOptions": {
        "noImplicitThis": true
    }
}

The next option that can help prevent the appearance of any in your project fixes the handling of the execution context in function calls. JavaScript's dynamic nature makes it difficult to statically determine the type of the context inside a function. By default, TypeScript uses the type any for the context in such cases and doesn't provide any warnings.

class Person {
    private name: string;

    constructor(name: string) {
        this.name = name;
    }

    getName() {
        return function () {
            return this.name;
            //     ^  'this' implicitly has type 'any' because
            //         it does not have a type annotation.
        };
    }
}

Enabling the noImplicitThis compiler option will prompt us to explicitly specify the type of the context for a function. This way, in the example above, we can catch the error of accessing the function context instead of the name field of the Person class.

Null and Undefined Support in TypeScript

{
    "compilerOptions": {
        "strictNullChecks": true
    }
}

Next several options that are included in the strict mode do not result in the any type appearing in the codebase. However, they make the behavior of the TS compiler stricter and allow for more errors to be found during development.

The first such option fixes the handling of null and undefined in TypeScript. By default, TypeScript assumes that null and undefined are valid values for any type, which can result in unexpected runtime errors. Enabling the strictNullChecks compiler option forces the developer to explicitly handle cases where null and undefined can occur.

For example, consider the following code:

const users = [
    { name: 'Oby', age: 12 },
    { name: 'Heera', age: 32 },
];

const loggedInUser = users.find(u => u.name === 'Max');
//    ^?  { name: string; age: number; }

console.log(loggedInUser.age);
//                       ^  TypeError: Cannot read properties of undefined

This code will compile without errors, but it may throw a runtime error if the user with name “Max” does not exist in the system, and users.find() returns undefined. To prevent this, we can enable strictNullChecks compiler option.

Now, TypeScript will force us to explicitly handle the possibility of null or undefined being returned by users.find().

const loggedInUser = users.find(u => u.name === 'Max');
//    ^?  { name: string; age: number; } | undefined

if (loggedInUser) {
    console.log(loggedInUser.age);
}

By explicitly handling the possibility of null and undefiined, we can avoid runtime errors and ensure that our code is more robust and error-free.

Strict Function Types

{
    "compilerOptions": {
        "strictFunctionTypes": true
    }
}

Enabling strictFunctionTypes makes TypeScript's compiler more intelligent. Prior to version 2.6, TypeScript did not check the contravariance of function arguments. This will lead to runtime errors if the function is called with an argument of the wrong type.

For example, even if a function type is capable of handling both strings and numbers, we can assign a function to that type that can only handle strings. We can still pass a number to that function, but we will receive a runtime error.

function greet(x: string) {
    console.log("Hello, " + x.toLowerCase());
}

type StringOrNumberFn = (y: string | number) => void;

// Incorrect Assignment
const func: StringOrNumberFn = greet;

// TypeError: x.toLowerCase is not a function
func(10);

Fortunately, enabling the strictFunctionTypes option fixes this behavior, and the compiler can catch these errors at compile-time, showing us a detailed message of the type incompatibility in functions.

const func: StringOrNumberFn = greet;
//    ^  Type '(x: string) => void' is not assignable to type 'StringOrNumberFn'.
//         Types of parameters 'x' and 'y' are incompatible.
//           Type 'string | number' is not assignable to type 'string'.
//             Type 'number' is not assignable to type 'string'.

Class Property Initialization

{
    "compilerOptions": {
        "strictPropertyInitialization": true
    }
}

Last but not least, the strictPropertyInitialization option enables checking of mandatory class property initialization for types that do not include undefined as a value.

For example, in the following code, the developer forgot to initialize the email property. By default, TypeScript would not detect this error, and an issue could occur at runtime.

class UserAccount {
    name: string;
    email: string;

    constructor(name: string) {
        this.name = name;
        // Forgot to assign a value to this.email
    }
}

However, when the strictPropertyInitialization option is enabled, TypeScript will highlight this problem for us.

email: string;
// ^  Error: Property 'email' has no initializer and
//           is not definitely assigned in the constructor.

Safe Index Signatures

{
    "compilerOptions": {
        "noUncheckedIndexedAccess": true
    }
}

The noUncheckedIndexedAccess option is not a part of the strict mode, but it is another option that can help improve code quality in your project. It enables the checking of index access expressions to have a null or undefined return type, which can prevent runtime errors.

Consider the following example, where we have an object for storing cached values. We then get the value for one of the keys. Of course, we have no guarantee that the value for the desired key actually exists in the cache. By default, TypeScript would assume that the value exists and has the type string. This can lead to a runtime error.

const cache: Record<string, string> = {};

const value = cache['key'];
//    ^?  string

console.log(value.toUpperCase());
//                ^  TypeError: Cannot read properties of undefined

Enabling the noUncheckedIndexedAccess option in TypeScript requires checking index access expressions for undefined return type, which can help us avoid runtime errors. This applies to accessing elements in an array as well.

const cache: Record<string, string> = {};

const value = cache['key'];
//    ^?  string | undefined

if (value) {
    console.log(value.toUpperCase());
}

Recommended Configuration

Based on the options discussed, it is highly recommended to enable the strict and noUncheckedIndexedAccess options in your project's tsconfig.json file for optimal type safety.

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

If you have already enabled the strict option, you may consider removing the following options to avoid duplicating the strict: true option:

noImplicitAny
useUnknownInCatchVariables
strictBindCallApply
noImplicitThis
strictFunctionTypes
strictNullChecks
strictPropertyInitialization

It is also recommended to remove the following options that can weaken the type system or cause runtime errors:

keyofStringsOnly
noStrictGenericChecks
suppressImplicitAnyIndexErrors
suppressExcessPropertyErrors

By carefully considering and configuring these options, you can achieve optimal type safety and a better developer experience in your TypeScript projects.

Conclusion

TypeScript has come a long way in its evolution, constantly improving its compiler and type system. However, to maintain backwards compatibility, the TypeScript configuration has become more complex, with many options that can significantly affect the quality of type checking.

By carefully considering and configuring these options, you can achieve optimal type safety and a better developer experience in your TypeScript projects. It is important to know which options to enable and remove from a project configuration. Understanding the consequences of disabling certain options will allow you to make informed decisions for each one.

It is important to keep in mind that strict typing may have consequences. To effectively deal with the dynamic nature of JavaScript, you will need to have a good understanding of TypeScript beyond simply specifying "number" or "string" after a variable. You will need to be familiar with more complex constructs and the TypeScript-first ecosystem of libraries and tools to more effectively solve type-related issues that will arise.

As a result, writing code may require a little more effort, but based on my experience, this effort is worth it for long-term projects.

I hope you have learned something new from this article. This is the first part of a series. In the next article, we will discuss how to achieve better type safety and code quality by improving the types in TypeScript's standard library. Stay tuned and thanks for reading!

Useful Links

How to Configure Path Aliases in Frontend Projects in the Native Way

Maksim Zemskov — Thu, 04 May 2023 18:59:34 +0000

We’ll take a look at the imports field in package.json and how it can be used to configure path aliases. We’ll also explore how commonly used development tools support this field and determine the optimal configuration for various use cases.

Content

About Path Aliases
The Imports Field
Configuring Path Aliases
Limitations of Node.js
Support for Subpath Imports in TypeScript
Support for Subpath Imports in Code Bundlers
Support for Subpath Imports in Test Runners
Support for Subpath Imports in Code Editors
Recommended Configuration
Conclusion
Useful Links

About Path Aliases

Projects often evolve into complex, nested directory structures. As a result, import paths may become longer and more confusing, which can negatively affect the code's appearance and make it more difficult to understand where imported code originates from.

Using path aliases can solve the problem by allowing the definition of imports that are relative to pre-defined directories. This approach not only resolves issues with understanding import paths, but it also simplifies the process of code movement during refactoring.

// Without Aliases
import { apiClient } from '../../../../shared/api';
import { ProductView } from '../../../../entities/product/components/ProductView';
import { addProductToCart } from '../../../add-to-cart/actions';

// With Aliases
import { apiClient } from '#shared/api';
import { ProductView } from '#entities/product/components/ProductView';
import { addProductToCart } from '#features/add-to-cart/actions';

There are multiple libraries available for configuring path aliases in Node.js, such as alias-hq and tsconfig-paths. However, while looking through the Node.js documentation, I discovered a way to configure path aliases without having to rely on third-party libraries. Moreover, this approach enables the use of aliases without requiring the build step.

In this article, we will discuss Node.js Subpath Imports and how to configure path aliases using it. We will also explore their support in the frontend ecosystem.

The Imports Field

Starting from Node.js v12.19.0, developers can use Subpath Imports to declare path aliases within an npm package. This can be done through the imports field in the package.json file. It is not required to publish the package on npm. Creating a package.json file in any directory is enough. Hence, this method is also suitable for private projects.

💡 Here's an interesting fact: Node.js introduced support for the imports field back in 2020 through the RFC called "Bare Module Specifier Resolution in node.js". While this RFC is mainly recognized for the exports field, which allows the declaration of entry points for npm packages, the exports and imports fields address completely different tasks, even though they have similar names and syntax.

Native support for path aliases has the following advantages in theory:

There is no need to install any third-party libraries.
There is no need to pre-build or process imports on the fly in order to run the code.
Aliases are supported by any Node.js-based tools that use the standard import resolution mechanism.
Code navigation and auto-completion should work in code editors without requiring any extra setup.

I tried to configure path aliases in my projects and tested those statements in practice.

Configuring Path Aliases

As an example, let's consider a project with the following directory structure:

my-awesome-project
├── src/
│   ├── entities/
│   │    └── product/
│   │        └── components/
│   │            └── ProductView.js
│   ├── features/
│   │    └── add-to-cart/
│   │        └── actions/
│   │            └── index.js
│   └── shared/
│       └── api/
│            └── index.js
└── package.json

To configure path aliases, you can add a few lines to package.json as described in the documentation. For instance, if you want to allow imports relative to the src directory, add the following imports field to package.json:

{
    "name": "my-awesome-project",
    "imports": {
        "#*": "./src/*"
    }
}

To use the configured alias, imports can be written like this:

import { apiClient } from '#shared/api';
import { ProductView } from '#entities/product/components/ProductView';
import { addProductToCart } from '#features/add-to-cart/actions';

Starting from the setup phase, we face the first limitation: entries in the imports field must start with the # symbol. This ensures that they are distinguished from package specifiers like @. I believe this limitation is useful because it allows developers to quickly determine when a path alias is used in an import, and where alias configurations can be found.

To add more path aliases for commonly used modules, the imports field can be modified as follows:

{
    "name": "my-awesome-project",
    "imports": {
        "#modules/*": "./path/to/modules/*",
        "#logger": "./src/shared/lib/logger.js",
        "#*": "./src/*"
    }
}

It would be ideal to conclude the article with the phrase "everything else will work out of the box". However, in reality, if you plan to use the imports field, you may face some difficulties.

Limitations of Node.js

If you plan to use path aliases with CommonJS modules, I have bad news for you: the following code will not work.

const { apiClient } = require('#shared/api');
const { ProductView } = require('#entities/product/components/ProductView');
const { addProductToCart } = require('#features/add-to-cart/actions');

When using path aliases in Node.js, you must follow the module resolution rules from the ESM world. This applies to both ES modules and CommonJS modules, and results in two new requirements that must be met:

It is necessary to specify the full path to a file, including the file extension.
It is not allowed to specify a path to a directory and expect to import an index.js file. Instead, the full path to an index.js file needs to be specified.

To enable Node.js to correctly resolve modules, the imports should be corrected as follows:

const { apiClient } = require('#shared/api/index.js');
const { ProductView } = require('#entities/product/components/ProductView.js');
const { addProductToCart } = require('#features/add-to-cart/actions/index.js');

These limitations can lead to issues when configuring the imports field in a project that has many CommonJS modules. However, if you're already using ES modules, then your code meets all the requirements. Furthermore, if you are building code using a bundler, you can bypass these limitations. We will discuss how to do this below.

Support for Subpath Imports in TypeScript

To properly resolve imported modules for type checking, TypeScript needs to support the imports field. This feature is supported starting from version 4.8.1, but only if the Node.js limitations listed above are fulfilled.

To use the imports field for module resolution, a few options must be configured in the tsconfig.json file.

{
    "compilerOptions": {
        /* Specify what module code is generated. */
        "module": "esnext",
        /* Specify how TypeScript looks up a file from a given module specifier. */
        "moduleResolution": "nodenext"
    }
}

This configuration enables the imports field to function in the same way as it does in Node.js. This means that if you forget to include a file extension in a module import, TypeScript will generate an error warning you about it.

// OK
import { apiClient } from '#shared/api/index.js';

// Error: Cannot find module '#src/shared/api/index' or its corresponding type declarations.
import { apiClient } from '#shared/api/index';

// Error: Cannot find module '#src/shared/api' or its corresponding type declarations.
import { apiClient } from '#shared/api';

// Error: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './relative.js'?
import { foo } from './relative';

I did not want to rewrite all the imports, as most of my projects use a bundler to build code, and I never add file extensions when importing modules. To work around this limitation, I found a way to configure the project as follows:

{
    "name": "my-awesome-project",
    "imports": {
        "#*": [
            "./src/*",
            "./src/*.ts",
            "./src/*.tsx",
            "./src/*.js",
            "./src/*.jsx",
            "./src/*/index.ts",
            "./src/*/index.tsx",
            "./src/*/index.js",
            "./src/*/index.jsx"
        ]
    }
}

This configuration allows for the usual way of importing modules without needing to specify extensions. This even works when an import path points to a directory.

// OK
import { apiClient } from '#shared/api/index.js';

// OK
import { apiClient } from '#shared/api/index';

// OK
import { apiClient } from '#shared/api';

// Error: Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './relative.js'?
import { foo } from './relative';

We have one remaining issue that concerns importing using a relative path. This issue is not related to path aliases. TypeScript throws an error because we have configured module resolution to use the nodenext mode. Luckily, a new module resolution mode was added in the recent TypeScript 5.0 release that removes the need to specify the full path inside imports. To enable this mode, a few options must be configured in the tsconfig.json file.

{
    "compilerOptions": {
        /* Specify what module code is generated. */
        "module": "esnext",
        /* Specify how TypeScript looks up a file from a given module specifier. */
        "moduleResolution": "bundler"
    }
}

After completing the setup, imports for relative paths will work as usual.

// OK
import { apiClient } from '#shared/api/index.js';

// OK
import { apiClient } from '#shared/api/index';

// OK
import { apiClient } from '#shared/api';

// OK
import { foo } from './relative';

Now, we can fully utilize path aliases through the imports field without any additional limitations on how to write import paths.

Building Code With TypeScript

When building source code using the tsc compiler, additional configuration may be necessary. One limitation of TypeScript is that a code cannot be built to the CommonJS module format when using the imports field. Therefore, the code must be compiled in ESM format and the type field must be added to package.json to run compiled code in Node.js.

{
    "name": "my-awesome-project",
    "type": "module",
    "imports": {
        "#*": "./src/*"
    }
}

If your code is compiled into a separate directory, such as build/, the module may not be found by Node.js because the path alias would point to the original location, such as src/. To solve this problem, conditional import paths can be used in the package.json file. This allows already built code to be imported from the build/ directory instead of the src/ directory.

{
    "name": "my-awesome-project",
    "type": "module",
    "imports": {
        "#*": {
            "default": "./src/*",
            "production": "./build/*"
        }
    }
}

To use a specific import condition, Node.js should be launched with the --conditions flag.

node --conditions=production build/index.js

Support for Subpath Imports in Code Bundlers

Code bundlers typically use their own module resolution implementation, rather than the one built into Node.js. Therefore, it's important for them to implement support for the imports field. I have tested path aliases with Webpack, Rollup, and Vite in my projects, and am ready to share my findings.

Here is the path alias configuration I used to test the bundlers. I used the same trick as for TypeScript to avoid having to specify the full path to files inside imports.

{
    "name": "my-awesome-project",
    "type": "module",
    "imports": {
        "#*": [
            "./src/*",
            "./src/*.ts",
            "./src/*.tsx",
            "./src/*.js",
            "./src/*.jsx",
            "./src/*/index.ts",
            "./src/*/index.tsx",
            "./src/*/index.js",
            "./src/*/index.jsx"
        ]
    }
}

Webpack

Webpack supports the imports field starting from v5.0. Path aliases work without any additional configuration. Here is the Webpack configuration I used to build a test project with TypeScript:

const config = {
    mode: 'development',
    devtool: false,
    entry: './src/index.ts',
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: ['@babel/preset-typescript'],
                    },
                },
            },
        ],
    },
    resolve: {
        extensions: ['.ts', '.tsx', '.js', '.jsx'],
    },
};

export default config;

Vite

Support for the imports field was added in Vite version 4.2.0. However, an important bug was fixed in version 4.3.3, so it is recommended to use at least this version. In Vite, path aliases work without the need for additional configuration in both dev and build modes. Therefore, I built a test project with a completely empty configuration.

Rollup

Although Rollup is used inside Vite, the imports field does not work out of the box. To enable it, you need to install the @rollup/plugin-node-resolve plugin version 11.1.0 or higher. Here's an example configuration:

import { nodeResolve } from '@rollup/plugin-node-resolve';
import { babel } from '@rollup/plugin-babel';

export default [
    {
        input: 'src/index.ts',
        output: {
            name: 'mylib',
            file: 'build.js',
            format: 'es',
        },
        plugins: [
            nodeResolve({
                extensions: ['.ts', '.tsx', '.js', '.jsx'],
            }),
            babel({
                presets: ['@babel/preset-typescript'],
                extensions: ['.ts', '.tsx', '.js', '.jsx'],
            }),
        ],
    },
];

Unfortunately, with this configuration, path aliases only work within the limitations of Node.js. This means that you must specify the full file path, including the extension. Specifying an array inside the imports field will not bypass this limitation, as Rollup only uses the first path in the array.

I believe it is possible to solve this problem using Rollup plugins, but I have not tried doing so because I primarily use Rollup for small libraries. In my case, it was easier to rewrite import paths throughout the project.

Support for Subpath Imports in Test Runners

Test runners are another group of development tools that heavily depend on the module resolution mechanism. They often use their own implementation of module resolution, similar to code bundlers. As a result, there's a chance that the imports field may not work as expected.

Fortunately, the tools I have tested work well. I tested path aliases with Jest v29.5.0 and Vite v0.30.1. In both cases, the path aliases worked seamlessly without any additional setup or limitations. Jest has had support for the imports field since version v29.4.0. The level of support in Vitest relies solely on the version of Vite, which must be at least v4.2.0.

Support for Subpath Imports in Code Editors

The imports field in popular libraries is currently well-supported. However, what about code editors? I tested code navigation, specifically the "Go to Definition" function, in a project that uses path aliases. It turns out that support for this feature in code editors has some issues.

VS Code

When it comes to VS Code, the version of TypeScript is crucial. The TypeScript Language Server is responsible for analyzing and navigating through JavaScript and TypeScript code. Depending on your settings, VS Code will use either the built-in version of TypeScript or the one installed in your project. I tested the imports field support in VS Code v1.77.3 in combination with TypeScript v5.0.4.

VS Code has the following issues with path aliases:

TypeScript does not use the imports field until the module resolution setting is set to nodenext or bundler. Therefore, to use it in VS Code, you need to specify the module resolution in your project.
IntelliSense does not currently support suggesting import paths using the imports field. There is an open issue for this problem.

To bypass both issues, you can replicate a path alias configuration in the tsconfig.json file. If you are not using TypeScript, you can do the same in jsconfig.json.

// tsconfig.json OR jsconfig.json
{
    "compilerOptions": {
        "baseUrl": "./",
        "paths": {
            "#*": ["./src/*"]
        }
    }
}

// package.json
{
    "name": "my-awesome-project",
    "imports": {
        "#*": "./src/*"
    }
}

WebStorm

Since version 2021.3 (I tested in 2022.3.4), WebStorm supports the imports field. This feature works independently of the TypeScript version, as WebStorm uses its own code analyzer. However, WebStorm has a separate set of issues regarding supporting path aliases:

The editor strictly follows the restrictions imposed by Node.js on the use of path aliases. Code navigation will not work if the file extension is not explicitly specified. The same applies to importing directories with an index.js file.
WebStorm has a bug that prevents the use of an array of paths within the imports field. In this case, code navigation stops working completely.

{
    "name": "my-awesome-project",

    // OK
    "imports": {
        "#*": "./src/*"
    },

    // This breaks code navigation
    "imports": {
        "#*": ["./src/*", "./src/*.ts", "./src/*.tsx"]
    }
}

Luckily, we can use the same trick that solves all the problems in VS Code. Specificaly, we can replicate a path alias configuration in the tsconfig.json or jsconfig.json file. This allows the use of path aliases without any limitations.

Recommended Configuration

Based on my experiments and experience using the imports field in various projects, I've identified the best path alias configurations for different types of projects.

Without TypeScript or a Bundler

This configuration is intended for projects where source code runs in Node.js without requiring additional build steps. To use it, follow these steps:

Configure the imports field in a package.json file. A very basic configuration is sufficient in this case.
In order for code navigation to work in code editors, it is necessary to configure path aliases in a jsconfig.json file.

// jsconfig.json
{
    "compilerOptions": {
        "baseUrl": "./",
        "paths": {
            "#*": ["./src/*"]
        }
    }
}

// package.json
{
    "name": "my-awesome-project",
    "imports": {
        "#*": "./src/*"
    }
}

Building Code Using TypeScript

This configuration should be used for projects where the source code is written in TypeScript and built using the tsc compiler. It is important to configure the following in this configuration:

The imports field in a package.json file. In this case, it is necessary to add conditional path aliases to ensure that Node.js correctly resolves compiled code.
Enabling the ESM package format in a package.json file is necessary because TypeScript can only compile code in ESM format when using the imports field.
In a tsconfig.json file, set the ESM module format and moduleResolution. This will allow TypeScript to suggest forgotten file extensions in imports. If a file extension is not specified, the code will not run in Node.js after compilation.
To fix code navigation in code editors, path aliases must be repeated in a tsconfig.json file.

// tsconfig.json
{
    "compilerOptions": {
        "module": "esnext",
        "moduleResolution": "nodenext",
        "baseUrl": "./",
        "paths": {
            "#*": ["./src/*"]
        },
        "outDir": "./build"
    }
}

// package.json
{
    "name": "my-awesome-project",
    "type": "module",
    "imports": {
        "#*": {
            "default": "./src/*",
            "production": "./build/*"
        }
    }
}

Building Code Using a Bundler

This configuration is intended for projects where source code is bundled. TypeScript is not required in this case. If it is not present, all settings can be set in a jsconfig.json file. The main feature of this configuration is that it allows you to bypass Node.js limitations regarding specifying file extensions in imports.

It is important to configure the following:

Configure the imports field in a package.json file. In this case, you need to add an array of paths to each alias. This will allow a bundler to find the imported module without requiring the file extension to be specified.
To fix code navigation in code editors, you need to repeat path aliases in a tsconfig.json or jsconfig.json file.

// tsconfig.json
{
    "compilerOptions": {
        "baseUrl": "./",
        "paths": {
            "#*": ["./src/*"]
        }
    }
}

// package.json
{
    "name": "my-awesome-project",
    "imports": {
        "#*": [
            "./src/*",
            "./src/*.ts",
            "./src/*.tsx",
            "./src/*.js",
            "./src/*.jsx",
            "./src/*/index.ts",
            "./src/*/index.tsx",
            "./src/*/index.js",
            "./src/*/index.jsx"
        ]
    }
}

Conclusion

Configuring path aliases through the imports field has both pros and cons compared to configuring it through third-party libraries. Although this approach is supported by common development tools (as of April 2023), it also has limitations.

This method offers the following benefits:

Ability to use path aliases without the need to compile or transpile code "on the fly".
Most popular development tools support path aliases without any additional configuration. This has been confirmed in Webpack, Vite, Jest, and Vitest.
This approach promotes configuring path aliases in one predictable location (package.json file).
Configuring path aliases does not require the installation of third-party libraries.

There are, however, temporary disadvantages that will be eliminated as development tools evolve:

Even popular code editors have issues with supporting the imports field. To avoid these issues, you can use the jsconfig.json file. However, this leads to duplication of path alias configuration in two files.
Some development tools may not work with the imports field out of the box. For example, Rollup requires the installation of additional plugins.
Using the imports field in Node.js adds new constraints on import paths. These constraints are the same as those for ES modules, but they can make it more difficult to start using the imports field.
Node.js constraints can result in differences in implementation between Node.js and other development tools. For instance, code bundlers can ignore Node.js constraints. These differences can sometimes complicate configuration, especially when setting up TypeScript.

So, is it worth using the imports field to configure path aliases? I believe that for new projects, yes, this method is worth using instead of third-party libraries.

The imports field has a good chance of becoming a standard way to configure path aliases for many developers in the coming years, as it offers significant advantages compared to traditional configuration methods.

However, if you already have a project with configured path aliases, switching to the imports field will not bring significant benefits.

I hope you have learned something new from this article. Thank you for reading!