DEV Community: Pouja

Everything about ESM and treeshaking

Pouja — Sat, 12 Jul 2025 20:05:51 +0000

With increasing support of ESM in Typescript 1 2 3 and NodeJS 1 2 3, it becomes easier and easier to write your frontend or backend in ESM format. Using the ESM module system has better support for treeshaking when using esbuild or webpack. Also with complexity rising of your backend and frontend, it is more than ever important to look at your bundle sizes. Even just recently AWS has announced that everyone, not just people using custom runtime environments, has to pay for the INIT Duration, making it also cost effective to have your AWS Lambda functions as small as possible.

I want to bring you through my journey of understanding the difference between CommonJS and ESM and why it allows for better treeshaking.
I will talk briefly about which typescript config rules and eslint rule might help to reduce the bundle. I will explain what does get removed with treeshaking (functions, methods, classes etc.) and what does not get removed and why that is.

Module System
Measuring
CJS to ESM
CJS vs ESM
ESM Dynamic Import
Proper Imports
Barrel Files
Unused Code

TLDR;

Set module and moduleResolution in your TS Config to nodenext
Use .mts as file extensions or set type to module in your nearest package.json
Avoid barrel files or set sideEffects to false in your nearest package.json
Set @typescript-eslint/no-unused-vars to error
Set @typescript-eslint/consistent-type-imports to error
Update your webpack/esbuild config to also read module entry of your npm packages

Module System

To be able to use functions or classes written in one file in another file requires a way of telling how the files should be linked. In the days of gulp/grunt and jquery there was not much choice, we all wrote everything on the window object. Everything was accessible by all objects and functions. We had to use closures to isolate var variables from another and prevent naming collisions. It was basically just one large JavaScript file. Quite a nightmare.

CommonJS

Luckily, people quickly started writing systems to separate them, not only at when you are writing your code but also at runtime. One of the first one and one that still lives to today is CommonJS. Everyone writing in plain NodeJS is probably already familiar with this syntax:

const axios = require('axios');

function getHelloWorld() {
    return axios.get('https://hello.world');
}

module.exports = {
    getHelloWorld,
};

The fact that everything was loaded synchronously, which was not really an issue at that time when writing for servers, it was not really feasible for front-ends. Therefore RequireJS was brought to life. If you ever wondered how it looks, there is an example repository still living. If you are more interested in the history, look up: AMD, UMD, RequireJS.

Small note: I also believe people just wanted to write their own module systems, who can blame their enthusiasm? It was a great module system.

The problem with CommonJS is that the require function is a function.
That means the following is valid:

const fs = require("fs");
const fs1 = require("f" + "s");
const fs2 = require(`${"f"}s`);
const fs3 = require(["f", "s"].join(""));
const modules = { fs: require("fs") };
const fs4 = modules["fs"];

function getFS() {
  function reallyGetIt() {
    return require("fs");
  }
  return reallyGetIt();
}
const fs6 = getFS();

const allTheSame = [fs, fs1, fs2, fs3, fs4, fs6].every((fsModule) => fsModule === require('fs'));
console.log(allTheSame); // true

Please do not do this

This is also why your javascript file is executed when referenced, because NodeJS has to know what it has to import. That is the largest reason why esbuild or webpack can not treeshake properly. Because they can not do any static analysis to create a tree of how your program is linked together. The same principle applies when using module.exports. Where ever you can use an object, you can export your function or variable.

Another reason CommonJS makes it hard but not impossible, is the freedom of how you reference other files or packages.
Given the following code:

require('../libs/manager');

This could either be a ../libs/manager.js file or ../libs/manager/index.js or ../libs/manager/package.json. This freedom was quite useful in the early days of NPM, but it adds too much ambiguity for the developers. There are more "quirks" to CommonJS, if you are interested in more details, a good start would be the NodeJS documentation itself.

ESM

require is not defined within EcmaScript and it is not natively implemented by any browser. It is something of NodeJS itself built upon v8. The same applies for the AMD, UMD and System module syntax. EcmaScript was behind the ecosystem, but that was a great plus because it could look at all the existing module system and draft a better one.

Entering ESM. It has similar syntax to what Typescript does:

import fs from 'fs';

export function readRootPackage() {
    return fs.readFileSync('./package.json', 'utf-8');
}

There is no way to tell if this is ESM or Typescript without looking at the file extension. This also adds to confusion for developers that they are not sure if this will get compiled to a require or the native EcmaScript import operator. The only way you know for sure what the output would be, is by compiling it.

What makes ESM so great that it allows for treeshaking? The import is an operator. Meaning that other rules apply compared to require function of NodeJS. The most important rule is that it only allows static strings:

import fs from 'fs';
import fs1 from 'f' + 's'; // error
import fs2 from ['f' + 's'].join(''); // error
import fs3 from `${"f"}s`; // error
import fs4 from +'fs'; // error
if (process.env) {
  import fs5 from 'fs'; // error
}

async function getFS() {
    return await import('fs'); // allowed
}
const fs6 = await getFS();

console.info(fs === fs6.default); // true

This allows anyone to perform static analysis and build a tree of how the program is linked together. Furthermore, to prevent ambiguity you either reference a package or a file. That is why the file extensions are required. This is also where people get confused when they are writing typescript but they have to use .js file extensions, luckily this is fixed by using nodenext as moduleResolution.

If you are interested in more details about esm:

Detailed explanation written by Dr. Axel Rauschmayer. Also check out his blog, always very well written and comprehensive.
Mozilla explanation on JavaScript imports.
NodeJS documentation
V8 on ESM imports impact on the browser.
Language specification on ESM by ECMAScript.

Measuring

Before we dive in to how much difference it makes between CJS and ESM and how you can transition. It is useful to know how you can measure it.

webpack and esbuild both support emitting a metafile, which contains data which npm packages have been imported, why they are imported and which module system is used to import them. With webpack you can use the --profile flag. With esbuild you can use the --metafile=bundle.meta.json flag or the property {meta: true} that will return the json object containing the meta data, which you can write to the file system yourself.

You can submit the meta file to https://esbuild.github.io/analyze/ and then you will get a visual representation on how everything is bundled.
You can let it mark visually which packages are interpreted as CommonJS and which ones as ESM. This will give you the knowledge if you imported them correctly and if esbuild was able to find the ESM bundle of the npm package.

CJS to ESM

To show you the difference, I have created 2 projects, both have similar code but one is written for CommonJS and the other for ESM. You can clone the repository and play with the different ways of importing a file and see what impact it will make. This should also help you transitioning to ESM by looking at the differences. I believe more in learning by doing than in learning by reading.
So I hope this helps for you.

`esbuild`

Both projects contain a esbuild.config.(m)js file. Depending on your own project, this configuration is in most cases either generated or hidden from you. The most important configurations are:

{
    bundle: true,
    mainFields: ["module", "main"], // Tells which package.json entries it should look for
    platform: "node", // Tells if it should expect window object to be present, or the NodeJS internal packages
    format: "esm", // Tells if the output should be in ESM format or in CommonJS
    metafile: true, // If true, it will return a meta file object
    minify: true, // Will eliminate any unreachable statement, shorten all names and remove all whitespaces where possible
    tsconfig: 'tsconfig.json' // It only reads some properties from the tsconfig, see also TsconfigRaw in main.d.ts of `esbuild`
}

esbuild has its own transpiler, so that is why only some properties are read from the tsconfig. But the exception is when you use a plugin like esbuild-decorator, which does use all the settings from your tsconfig. So you can not just configure your tsconfig to use CommonJS and then tell esbuild to output in ESM, you will most likely get some runtime errors.

The mainFields property is quite important. Only a few modern libraries now output it properly. By properly I mean using the exports field in the package.json, to tell NodeJS module resolver which file it should read depending on if you are using ESM or CommonJS. If we take a look at a part of the package.json of class-validator:

{
  "name": "class-validator",
  "sideEffects": false,
  "main": "./cjs/index.js",
  "module": "./esm5/index.js",
  "es2015": "./esm2015/index.js",
  "typings": "./types/index.d.ts",
}

NodeJS will by default only look at the exports field and if that is not present, which is the case for class-validator, it will use the main field.
So even if you do this:

// index.mjs
import { validate } from 'class-validator';

NodeJS will look at node_modules/class-validator/cjs/index.js even though your file is in .mjs format and even if your package.json you have set type to module. You can still tell esbuild to use the ESM output of class-validator by setting the mainFields property.

Use this information!
When inspecting and investigating your imports and you notice it uses the CommonJS variant of the package, even when they have ESM files. Look at their package.json! If they do not emit any ESM file, your only options are: submitting a pull request or copy the code to your code base.

package.json

The property type in the package.json is set to module for the ESM project and omitted CommonJS project, which defaults to commonjs. You can actually choose how you will mark your project as ESM or CommonJS. When using plain javascript, you either use the .mjs extension for your files or you set the type property in the nearest package.json. You can mix. It is discouraged to use CommonJS files in ESM files, but not the other way around.

If you are using CommonJS and you need to use a package that only has ESM files, you can use the following "hack":

function myFunc() {
  const dynamicImport = new Function('specifier', 'return import(specifier)');
  const TypeDoc = await dynamicImport('typedoc');
}

tsconfig.json

This is the most confusing part. I really had to read through the module page of typescript a couple of times to understand what they are saying. The most important configurations for transition of CJS to ESM are:

{
    "compileOnSave": true,
    "compilerOptions": {
        "moduleResolution": "nodenext", // this tells typescript which algorithm/method it should use to resolve imports
        "module": "NodeNext", // This tells if you are using CommonJS, AMD, System, ESM or a mix of CommonJS and ESM which is nodenext
        "target": "ESNext", // This tells how the output should look like after you have compiled to javascript
    },
}

nodenext basically means that typescript will either resolve the imports by using NodeJS CommonJS module resolution technique or using the new ESM module resolution technique. And it depends on the file extensions, using .mts will tell typescript to use ESM. If you use .ts but the package.json has the property type set to module it will use ESM. In all other cases it will use CommonJS. Although typescript is quite lenient since 5.8.x on which module system it will use, it is best to be consistent.

Do not mix! You will get unexpected results when using frameworks that can possibly use different methods to determine ESM vs CommonJS!

You can also set moduleResolution to bundler, but then you have to specify to which specific module system you want your javascript files compiled to. Then it does not matter what file extension you use, it will always output to what ever module system you have picked.

When using nodenext configuration value you can still output to both CommonJS format and ESM format, you only need to change the format property in esbuild and you have to make sure to not set the type property in the package.json file.

If you are not intending on publishing and if all your libraries/framework support ESM, which Jest does do quite well right now, I would recommend to setting the type property to module and use the .mts file extension. You will notice that you have to use .mjs when importing a relative file. Do not worry, you are not importing a javascript file, Typescript will automatically search for any .mts file with the same module name.
It is confusing, people have complained about this behavior, but it is what it is.

CJS vs ESM

Now you know how you can transition, but how much will the difference be?

CommonJS:

ESM:

It is 20x smaller when using the same code.
If you generate the metafiles and upload it to esbuild page, you can reproduce this result:

git clone https://github.com/Pouja/configuring-esm.git
fnm use
cd ts-cjs && npm install && npm run bundle:ts && cd -
cd ts-esm && npm install && npm run bundle:ts && cd -
Open in the browser https://esbuild.github.io/analyze/
Upload the metafile.json in the dist folders

You will notice that the biggest difference comes from libphonenumber-js not being present, because due to ESM, esbuild knows it can remove it from the bundle safely.

ESM Dynamic Import

For the readers that were paying attention, I went through create details saying that using dynamic module names for require is one of the reasons treeshaking is not possible. You could be wondering: "ESM supports await import(moduleName), so how will that work?"
Great question!

ESM does allow the following:

// on-ssm-event.ts
async function handler(event: ProxyApiGatewayEventv2): Promise<any> {
  const { Manager } = await import(event.superUnsafeThis);
}

esbuild will in this case do nothing special. You are responsible yourself to make sure it resolves to something at runtime. If you do expect them to be present when dynamically importing them then you need to reference them somewhere.

There are some other interesting results:

// on-ssm-event.ts
async function handler(event: ProxyApiGatewayEventv2): Promise<any> {
    // esbuild will bundle all files that are reachable from one folder up
    const manager = await import('../' + event.superUnsafeThis);

    // esbuild will bundle both files
    const manager = await import(event.isS3Event ? '../lib/use-s3.js' : '../lib/use-sqs.js');

     // esbuild will bundle all files under the lib folder, not just the s3 and sqs one
    const manager = await import('../lib/' + (event.isS3Event ? 'use-s3.js' : 'use-sqs.js'));
}

You can play around with in the example repository.

Depending on your bundler you might get different results! Analyze the bundle. For example @rollup/plugin-dynamic-imports-vars has different ways it variable imports.

Proper Imports

Even when using CommonJS you can reduce your bundle size by looking at the import statements.

Use import type { MyClass} from './MyClass'; or import { type MyClass} from './MyClass'; if you only use the import as a type. All typescript type and interface do get stripped out by default. But if you use something like typeof MyClass and you do not import it as a type, then esbuild will add that class to your bundle. Using @typescript-eslint/consistent-type-imports allows you to capture most of them. This rule will not work on any file that uses decorators. That is because under the hood the imported value might actually be used when setting the metadata of the decorated property or method.

Eliminate unused imports by detecting unused variables/functions that might use those. You can detect those by using @typescript-eslint/no-unused-vars.

Barrel files

Even with using proper imports, with a barrel file you can still end up with that package or file in your bundle. Why?

First of all, what is a barrel file? When you re-export everything from a folder within a index.ts that is called a barrel file.
An example of this:

// index.ts
export * from './use-cloudwatch';
export * from './use-dynamodb';
export * from './use-lambda';
export * from './use-s3';
export * from './use-sqs';
export * from './use-ssm';
export * from './helpers/index';

All exported values within each of those files are re-exported by index.ts. This makes it easier to import any value of any of the files.
No need to have a long listed import statement like: import { mapToZod } from '../lib/helpers/zod-utilities';, but you can write it as import { mapToZod } from '../lib';.

A lot of blog posts mark barrel files as evil. But it is a bit nuanced. It has impact on two things: runtime and bundle size.

Runtime

As explained in the CommonJS section, each file is executed before imported and wrapped by NodeJS. That means when you import a barrel file, NodeJS will go through each file mentioned there, then it will read each require call, load that file etc. When your program is large enough, or you node_modules folder is large enough, this will impact any framework or library you are using. With ESM you still have the same issue, ECMAScript does not verify if an imported module has side effects or not. It will always evaluate all top level expressions in a module, even if you only import a single function.

Take jest for example, it will go through all those files before it even runs any test function. I have seen cases where it took 20+ seconds before running the first file, even when most files were not even used. But due to extensive usage of barrel files all those files were transpiled and then executed. By eliminating some of those barrel files, I was able to reduce the start time to 5 seconds.

If you use your barrel files sparingly or if your program is not large, you are good to go.

Bundle Size

What is considered a side effect?
Take the following file:

// load-dotenv.ts
import dotenv from "dotenv";

dotenv.config();

When you import that file: import './load-dotenv'; it will read out the .env file and update process.env. This is considered a side effect because you are altering the possible execution of the program by just importing the file. You have more examples of side effects:

import 'reflect-metadata'; when you need to use tsyringe, it modifies the global Reflect object. - import 'zone.js'; when you use angular, overwrites all async calls with zones.

There is no sure way that esbuild or webpack can know that it can safely remove files when re-exporting them without giving any hints.
That is why barrel files can increase your bundle size significantly.
Luckily both of them support 1 2 the sideEffects property in the package.json. When set to false it will safely remove any unused re-exported file. But that will also remove load-dotenv.ts! So be careful when using that property. It does not affect any other npm package you are using as a side effect, only the ones in your project.

If it is not possible to set the property sideEffects then you should prevent any re-exporting modules/files. That means no barrel files. That also means no god files. God files is what I refer to values that import everything from everywhere as a single entry point. If you define all your AWS Lambda handlers in one file, that is a god file. If you define all the routes with all the components of your frontend page and do not chunk them, that is a god file.

Alternative: Workspaces

A good solution in a large project is to have pnpm workspaces, where you have internal libraries. Then per library you can mark if all those files that are exported through the package.json file have side effects or not. You can find an example configuration

{
    "name": "@packages/base-models",
    "typesVersions": {
        "*": {
            "./enums/*": [
                "./src/enums/*"
            ],
            "./models/*": [
                "./src/models/*"
            ]
        }
    },
    "exports": {
        "./enums/*": "./src/enums/*",
        "./models/*": "./src/models/*"
    }
}

The exports field allows you to sub categorize your internal library. The wild card * allows any subpath (0 or more levels deep) or any file. If you want to limit it to one depth you have to set the subfolder to null: "./enums/not-this-dir/": null. See official NodeJS documentation on the specifications of exports field.

The typesVersions is only necessary if you use CommonJS as module resolution or if you want typescript to refer to .d.ts files that are not next to your .(m)ts files.

Alternative: TSConfig Paths

Another solution, if you do not use internal libraries through the yarn workspaces or pnpm workspaces, is using tsconfig path. Taking the previous package.json example, you will write it as:

{
  "compilerOptions": {
    "paths": {
      "@packages/base-models/enums/*": ["./src/enums/*"],
      "@packages/base-models/models/*": ["./src/models/*"],
    }
  }
}

Demo

You can play with barrel files in my example project.

Clone the repository
cd barrel-file
npm install
Play with the barrel file, sideEffects property, side effect file load-dotenv.ts
Run nodeesbuild.config.mjs and see the effects.

Unused Code

I have listed several things that esbuild might see as dead code depending on the setup of your project.
But what about unused code even when using ESM and no side effects?

Unused methods and properties of classes will not be treeshaking.
If you use a large npm package within a method, but you actually use the class but not that specific method, you will still end up with that npm package in your bundle.
This is where separation of concerns and cohesion come in.
Make sure to follow that paradigm.

Unused elements in the array.
In most cases this will not impact your bundle much.

Nested unused functions.
Only top level objects, primitives and functions are considered for treeshaking.

Unused properties in objects.
There might be some side effects, so it hard to determine if you can remove that code.

_Unreachable statements when not using minification in webpack or in esbuild. _
If you have functions that are dependent on some build time environment variable, for example if (process.env.NODE_ENV === 'production').
Or another example of this, is having a class that has different methods for different environment (browser or os).
Then make sure to enable minification.
Or you can use labels to achieve similar behavior.

NOTE: There might be bundlers out there that can do better in certain scenarios. That is why measuring is key!

I did try rollup with terser but I saw similar results

Conclusion

I have listed some things to look out for.
This list might not be exhaustive, but the most important thing is: analyze!
Make sure that the bundler you use has a way to convey which files and which npm packages were included.
This blog post should give you enough information to understand then why some files/code/packages were included.
From there you can start eliminating and changing the structure of your code.

Happy hunting and happy coding!
Thank you for reading.

Making lodash function get type safe

Pouja — Mon, 05 Apr 2021 15:34:37 +0000

With the introduction of Typescript 4.1 we can use template literal types for writing our generics. This opens up a whole lot of new applications and better typing, also means they are more complex to read.

In this post I will be going over why and how I implemented the following result:

expectType<RegExp>(get(obj,'deeplvl1[1].deeplvl2.deeplvl3[88].deeplvl4.value'));

Table of Content

Why I needed
The End Result
How It Works
Example
Future Work

Why

Context

In my current project we are using react-final-form to create our forms. In one of our pages we have a huge object (or as we can call it a god object) that is allowed to be edited in several visible sections. This is bad design by nature, but unfortunately this technical debt is too large to currently solve. We wrote several hooks to make our live easier. One of them is:

export function useFormValue<T>(field: string): T {
  const fieldInput = useField(field, {
    subscription: {
      value: true
    }
  });
  return fieldInput.input.value;
}

Which can be used as

export default function DeepNestComponent() {
  const price = useFormValue<number>('customers[3].contract.price');
  return (<div>{price}</div>);
}

This allows us to create deep nested components that can subscribe to form changes of a specific form input and display the value.

The problem

What if the structure of the large object that is being edited changes? We then have to go over all the components and adjust the path. If you have full unit test coverage, a (snapshot) test will probably fail. But I rather have my compiler give me an error than hoping that my unit coverage is sufficient.

The End Result

I ended up writing the following generic

export type ResolveType<ObjectType, Path extends string, OrElse> =
    Path extends keyof ObjectType ? ObjectType[Path] :
    Path extends `${infer LeftSide}.${infer RightSide}` ? LeftSide extends keyof ObjectType ? ResolveType<ObjectType[LeftSide], RightSide, OrElse> : 
    Path extends `${infer LeftSide}[${number}].${infer RightSide}` ? LeftSide extends keyof ObjectType ? ObjectType[LeftSide] extends Array<infer U>? ResolveType<U,RightSide, OrElse> : OrElse : OrElse : OrElse :
    Path extends `${infer LeftSide}[${number}]` ? LeftSide extends keyof ObjectType ? ObjectType[LeftSide] extends Array<infer U> ? U : OrElse : OrElse : OrElse;

Which is uploaded to

Pouja / typescript-deep-path-safe

Collections of generics to make deep nested string paths type safe

And it can be used as:


function get<ObjecType extends object, Path extends string, OrElse extends unknown>(obj:ObjecType, path: Path, orElse?: OrElse): ResolveType<ObjecType, Path, OrElse> {
  return _get(obj, path, orElse);
}

const nested = get(obj, 'my.deep[3].nested', 'orElse');

How it works

My starting point was the implementation of template literal types:

Template literal types and mapped type 'as' clauses #40336

ahejlsberg posted on Aug 31, 2020

This PR implements two new features:

Template literal types, which are a form of string literals with embedded generic placeholders that can be substituted with actual string literals through type instantiation, and
Mapped type as clauses, which provide the ability to transform property names in mapped types.

Template literal types

Template literal types are the type space equivalent of template literal expressions. Similar to template literal expressions, template literal types are enclosed in backtick delimiters and can contain placeholders of the form ${T}, where T is a type that is assignable to string, number, boolean, or bigint. Template literal types provide the ability to concatenate literal strings, convert literals of non-string primitive types to their string representation, and change the capitalization or casing of string literals. Furthermore, through type inference, template literal types provide a simple form of string pattern matching and decomposition.

Template literal types are resolved as follows:

Union types in placeholders are distributed over the template literal type. For example `[${A|B|C}]` resolves to `[${A}]` | `[${B}]` | `[${C}]`. Union types in multiple placeholders resolve to the cross product. For example `[${A|B},${C|D}]` resolves to `[${A},${C}]` | `[${A},${D}]` | `[${B},${C}]` | `[${B},${D}]`.
String, number, boolean, and bigint literal types in placeholders cause the placeholder to be replaced with the string representation of the literal type. For example `[${'abc'}]` resolves to `[abc]` and `[${42}]` resolves to `[42]`.
Any one of the types any, string, number, boolean, or bigint in a placeholder causes the template literal to resolve to type string.
The type never type in a placeholder causes the template literal to resolve to never.

Some examples:

type EventName<T extends string> = `${T}Changed`;
type Concat<S1 extends string, S2 extends string> = `${S1}${S2}`;
type ToString<T extends string | number | boolean | bigint> = `${T}`;
type T0 = EventName<'foo'>;  // 'fooChanged'
type T1 = EventName<'foo' | 'bar' | 'baz'>;  // 'fooChanged' | 'barChanged' | 'bazChanged'
type T2 = Concat<'Hello', 'World'>;  // 'HelloWorld'
type T3 = `${'top' | 'bottom'}-${'left' | 'right'}`;  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
type T4 = ToString<'abc' | 42 | true | -1234n>;  // 'abc' | '42' | 'true' | '-1234'

Beware that the cross product distribution of union types can quickly escalate into very large and costly types. Also note that union types are limited to less than 100,000 constituents, and the following will cause an error:

type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
type Zip = `${Digit}${Digit}${Digit}${Digit}${Digit}`;  // Error

A template literal placeholder may optionally specify an uppercase, lowercase, capitalize, or uncapitalize modifier before the type. This modifier changes the casing of the entire replacement string or the first character of the replacement string. For example:

EDIT: Based on feedback, the casing modifiers have been replaced by intrinsic string types in #40580.

type GetterName<T extends string> = `get${Capitalize<T>}`;
type Cases<T extends string> = `${Uppercase<T>} ${Lowercase<T>} ${Capitalize<T>} ${Uncapitalize<T>}`;
type T10 = GetterName<'foo'>;  // 'getFoo'
type T11 = Cases<'bar'>;  // 'BAR bar Bar bar'
type T12 = Cases<'BAR'>;  // 'BAR bar BAR bAR'

Template literal types are all assignable to and subtypes of string. Furthermore, a template literal type `${T}` is assignable to and a subtype of a template literal type `${C}`, where C is a string literal type constraint of T. For example:

function test<T extends 'foo' | 'bar'>(name: `get${Capitalize<T>}`) {
    let s1: string = name;
    let s2: 'getFoo' | 'getBar' = name;
}

Type inference supports inferring from a string literal type to a template literal type. For inference to succeed the starting and ending literal character spans (if any) of the target must exactly match the starting and ending spans of the source. Inference proceeds by matching each placeholder to a substring in the source from left to right: A placeholder followed by a literal character span is matched by inferring zero or more characters from the source until the first occurrence of that literal character span in the source. A placeholder immediately followed by another placeholder is matched by inferring a single character from the source.

Some examples:

type MatchPair<S extends string> = S extends `[${infer A},${infer B}]` ? [A, B] : unknown;

type T20 = MatchPair<'[1,2]'>;  // ['1', '2']
type T21 = MatchPair<'[foo,bar]'>;  // ['foo', 'bar']
type T22 = MatchPair<' [1,2]'>;  // unknown
type T23 = MatchPair<'[123]'>;  // unknown
type T24 = MatchPair<'[1,2,3,4]'>;  // ['1', '2,3,4']

type FirstTwoAndRest<S extends string> = S extends `${infer A}${infer B}${infer R}` ? [`${A}${B}`, R] : unknown;

type T25 = FirstTwoAndRest<'abcde'>;  // ['ab', 'cde']
type T26 = FirstTwoAndRest<'ab'>;  // ['ab', '']
type T27 = FirstTwoAndRest<'a'>;  // unknown

Template literal types can be combined with recursive conditional types to write Join and Split types that iterate over repeated patterns.

type Join<T extends unknown[], D extends string> =
    T extends [] ? '' :
    T extends [string | number | boolean | bigint] ? `${T[0]}` :
    T extends [string | number | boolean | bigint, ...infer U] ? `${T[0]}${D}${Join<U, D>}` :
    string;
type T30 = Join<[1, 2, 3, 4], '.'>;  // '1.2.3.4'
type T31 = Join<['foo', 'bar', 'baz'], '-'>;  // 'foo-bar-baz'
type T32 = Join<[], '.'>;  // ''

type Split<S extends string, D extends string> =
    string extends S ? string[] :
    S extends '' ? [] :
    S extends `${infer T}${D}${infer U}` ? [T, ...Split<U, D>] :
    [S];

type T40 = Split<'foo', '.'>;  // ['foo']
type T41 = Split<'foo.bar.baz', '.'>;  // ['foo', 'bar', 'baz']
type T42 = Split<'foo.bar', ''>;  // ['f', 'o', 'o', '.', 'b', 'a', 'r']
type T43 = Split<any, '.'>;  // string[]

The recursive inference capabilities can for example be used to strongly type functions that access properties using "dotted paths", and pattern that is sometimes used in JavaScript frameworks.

type PropType<T, Path extends string> =
    string extends Path ? unknown :
    Path extends keyof T ? T[Path] :
    Path extends `${infer K}.${infer R}` ? K extends keyof T ? PropType<T[K], R> : unknown :
    unknown;

declare function getPropValue<T, P extends string>(obj: T, path: P): PropType<T, P>;
declare const s: string;

const obj = { a: { b: {c: 42, d: 'hello' }}};
getPropValue(obj, 'a');  // { b: {c: number, d: string } }
getPropValue(obj, 'a.b');  // {c: number, d: string }
getPropValue(obj, 'a.b.d');  // string
getPropValue(obj, 'a.b.x');  // unknown
getPropValue(obj, s);  // unknown

Mapped type `as` clauses

With this PR, mapped types support an optional as clause through which a transformation of the generated property names can be specified:

{ [P in K as N]: X }

where N must be a type that is assignable to string | number | symbol. Typically, N is a type that transforms P, such as a template literal type that uses P in a placeholder. For example:

type Getters<T> = { [P in keyof T & string as `get${Capitalize<P>}`]: () => T[P] };
type T50 = Getters<{ foo: string, bar: number }>;  // { getFoo: () => string, getBar: () => number }

Above, a keyof T & string intersection is required because keyof T could contain symbol types that cannot be transformed using template literal types.

When the type specified in an as clause resolves to never, no property is generated for that key. Thus, an as clause can be used as a filter:

type Methods<T> = { [P in keyof T as T[P] extends Function ? P : never]: T[P] };
type T60 = Methods<{ foo(): number, bar: boolean }>;  // { foo(): number }

When the type specified in an as clause resolves to a union of literal types, multiple properties with the same type are generated:

type DoubleProp<T> = { [P in keyof T & string as `${P}1` | `${P}2`]: T[P] }
type T70 = DoubleProp<{ a: string, b: number }>;  // { a1: string, a2: string, b1: number, b2: number }

Fixes #12754.

Playground: https://www.typescriptlang.org/play?ts=4.1.0-pr-40336-88

View on GitHub

Where already a start was made which works with only objects without arrays.

But I want to go over step by step in how it works and how I extend it.

Single Nested Object

To make it easier to reason with generics, I will view them as functions. Example type ResolveType<ObjectType extends object, Path extends string, OrElse> is function called ResolveType which accepts 3 arguments. First argument should be of (sub)type object, second argument must be a string and the third argument is of type any.

Our function must return type of the single level nested path or if it does not exists then return the third argument. In pseudo code it will look like:

function ResolveType(obj:Object, path:String, orElse:any) {
 if(path exists in obj) return type of obj[path]
 else return orElse;
}

To retrieve all the keys of a object we can use keyof operator. To check if type a is of type b we can use the extends operator. This covers our if condition. The if-else equivalent in generics are ternary statements. We then get the following result:

export type ResolveType1<ObjectType, Path extends string, OrElse> =
    Path extends keyof ObjectType ? ObjectType[Path] : OrElse;

Unlimited Nested Objects

Now we must use the new template literal types of Typescript, introduced in 4.1. This allows us, as I call it, to do pattern matching. Furthermore because nested objects can be nested more than 10 levels deep, we have to either loop or recursively call our generic type resolver. In 4.1 they also introduced Recursive Conditional Types which allows us to recursively walk through all the nested levels of our object.

Our pseudo code will look like:

function ResolveType(obj:Object, path:String, orElse:any) {
 if(path exists in obj) return type of obj[path]
 else if(path can be splitted between '.') {
   if(leftside of '.' is a key of obj) {
     return ResolveType(obj[leftSide], rightSide, orElse);
   }
 }
 return orElse;
}

First condition can be written as

Path extends `${string}.${string}`

But we don't want to just check if the path matches the pattern, but we also want to use the matched string. This can be achieved with the infer keyword, which is not documented in detail in the handbook of Typescript. Our condition becomes

Path extends `${infer LeftSide}.${infer RightSide}`

The last condition we have to check is the same we already covered for single level nested objects.

Typescript doesn't support a AND operator in generics, so we have to used nested ternary.

Our function becomes:

export type ResolveType<ObjectType, Path extends string, OrElse> =
    Path extends keyof ObjectType ? ObjectType[Path] :
    Path extends `${infer LeftSide}.${infer RightSide}` ? LeftSide extends keyof ObjectType ? ResolveType<ObjectType[LeftSide], RightSide, OrElse> : OrElse : OrElse;

Arrays

The pattern of arrays are as followed: nested[3] which is the simple variant. Our pseudo code becomes:

function ResolveType(obj:Object, path:String, orElse:any) {
 if(path exists in obj) return type of obj[path]
 else if(path can be splitted between '.') {
   if(leftside of '.' is a key of obj) {
     return ResolveType(obj[leftSide], rightSide, orElse);
   }
 } else if(path matches with pattern 'string.[number]') {
   if(leftside of [number] is a key of obj) {
     if(obj[leftside] is type of array) {
       return type of array
     }
   }
 }
 return orElse;
}

Array notation can be pattern matched with ${infer LeftSide}[${number}]. We are just matching if a number is being used, since we can not infer the size of an array are compile time. If you use an index outside of the range you will get a Index Out of Bounds Exception, which is the only downside of the constructed generic.

We can also use the infer key word to infer the type of array we are using: Array<infer U>. Typescript will then infer the type of the array.

We then get the following function:

export type ResolveType<ObjectType, Path extends string, OrElse> =
    Path extends keyof ObjectType ? ObjectType[Path] :
    Path extends `${infer LeftSide}.${infer RightSide}` ? LeftSide extends keyof ObjectType ? ResolveType<ObjectType[LeftSide], RightSide, OrElse> : OrElse :
    Path extends `${infer LeftSide}[${number}]` ? LeftSide extends keyof ObjectType ? ObjectType[LeftSide] extends Array<infer U> ? U : OrElse : OrElse : OrElse;

Nested arrays

We can now match the following constructions:

expectType<number>(get(obj, 'nested.a'));
expectType<string>(get(obj, 'normal'));
expectType<number>(get(obj,'nested.a'));
expectType<boolean>(get(obj,'nested.b.c'));
expectType<number[]>(get(obj,'arr'));
expectType<number>(get(obj,'arr[13]'));
expectType<string[]>(get(obj,'anothernested.deep'));

I am using the following library for testing my types:

tsdjs / tsd

Check TypeScript type definitions

But we can not match for example arr[13].length because we only check for the pattern string[number]. We need to match for string[number].string and infer the types. But arr[13].length will match with our second condition in our pseudo code:

if(path can be splitted between '.')

So in our else statement of the second condition we have to check if it matches the pattern string[number].string. And then recursively call our function with the right side of the dot. Our pseudo code becomes:

function ResolveType(obj:Object, path:String, orElse:any) {
 if(path exists in obj) return type of obj[path]
 else if(path can be splitted between '.') {
   if(leftside of '.' is a key of obj) {
     return ResolveType(obj[leftSide], rightSide, orElse);
   } else if(path contains pattern 'string[number].string') {
     if(leftSide of [number] is a key of obj) {
       if(obj[leftSide] is an array) {
         return ResolveType(type of array, rightSide, orElse)
       }
     }
   }
 } else if(path matches with pattern 'string.[number]') {
   if(leftSide of [number] is a key of obj) {
     if(obj[leftSide] is type of array) {
       return type of array
     }
   }
 }
 return orElse;
}

As you can see the added if-else condition is similar to last one, except we recursively walk through the right side of the dot.

Combining everything until now we get the final result:

export type ResolveType<ObjectType, Path extends string, OrElse> =
    Path extends keyof ObjectType ? ObjectType[Path] :
    Path extends `${infer LeftSide}.${infer RightSide}` ? LeftSide extends keyof ObjectType ? ResolveType<ObjectType[LeftSide], RightSide, OrElse> : 
    Path extends `${infer LeftSide}[${number}].${infer RightSide}` ? LeftSide extends keyof ObjectType ? ObjectType[LeftSide] extends Array<infer U>? ResolveType<U,RightSide, OrElse> : OrElse : OrElse : OrElse :
    Path extends `${infer LeftSide}[${number}]` ? LeftSide extends keyof ObjectType ? ObjectType[LeftSide] extends Array<infer U> ? U : OrElse : OrElse : OrElse;

Example

Lets take the lodash get example and step by step walk through how the generic will be called and how it will resolve:

const barLength = get(obj,'foo.bar[3].length', -1);

We will assume that obj is of type FooBar and the path is valid. The generic will then be called with ResolveType<FooBar, 'foo.bar[3].length', number)

foo.bar[333].length matches the pattern string.string, Typescript will infer the following values leftSide=foo and rightSide=bar[333].length
foo is a key of FooBar, lets assume that FooBar['foo'] is of type Foo.
ResolveType will be called with ResolveType<Foo, 'bar[3].length', number>
bar[3].length matches the pattern string.string, Typescript will infer the following values leftSide=bar[3] and rightSide=length
bar[3] is not a key of Foo
bar[3].length matches the pattern string[number].string, Typescript will infer the following values leftSide=bar and rightSide=length
bar is a key of Foo
Foo['bar'] is an array of type Bar
ResolveType will be called with ResolveType<Bar, 'length', number>
length is a key of bar since bar is a string
ResolveType returns the type number

Future Work

Publishing

Currently you can copy the type from this article or from my repository:

Pouja / typescript-deep-path-safe

Collections of generics to make deep nested string paths type safe

Type safe paths

Collections of generics to make deep nested string paths type safe.

ResolveType

It accepts 3 arguments:

The object type
The string path
The type to return if it fails to resolve

Usage

For example you can augment the lodash get:

import { get as _get } from 'lodash';

function get<ObjecType extends object, Path extends string, OrElse extends unknown>(obj:ObjecType, path: Path, orElse?: OrElse): ResolveType<ObjecType, Path, OrElse> {
  return _get(obj, path, orElse);
}

get(obj,'deeplvl1[1].deeplvl2.deeplvl3[88].deeplvl4.value');

Or for react-final-form:

// file: form-value-hook.tsx
export function useFormValue<Path extends string>(field: Path): ResolveType<YourFormType, Path, unknown> {
  const fieldInput = useField(field, {
    subscription: {

…

View on GitHub

I hope in the near future to publish it to NPM so you can install it (when I figure out how).

Autocomplete

I want to look into making generic type where is accepts variable list of function arguments to determine the type. This allows you to use auto completion of typescript itself.
The end result should look like:

get(obj, 'orElse', 'lvl1path', 3, 'lvl2path', '[your cursor]

Where in the last argument you will get the autocomplete of Typescript for the type obj.lvl1path[3].lvl2path.

DEV Community: Pouja

Everything about ESM and treeshaking

Table of Contents

TLDR;

Module System

CommonJS

ESM

Measuring

CJS to ESM

esbuild

package.json

tsconfig.json

CJS vs ESM

ESM Dynamic Import

Proper Imports

Barrel files

Runtime

Bundle Size

Alternative: Workspaces

Alternative: TSConfig Paths

Demo

Unused Code

Conclusion

Making lodash function get type safe

Table of Content

Why

Context

The problem

The End Result

Pouja / typescript-deep-path-safe

Collections of generics to make deep nested string paths type safe

How it works

Template literal types and mapped type 'as' clauses #40336

Template literal types

Mapped type as clauses

Single Nested Object

Unlimited Nested Objects

Arrays

Nested arrays

tsdjs / tsd

Check TypeScript type definitions

Example

Future Work

Publishing

Pouja / typescript-deep-path-safe

Collections of generics to make deep nested string paths type safe

Type safe paths

ResolveType

Usage

Autocomplete

`esbuild`

Mapped type `as` clauses