On Unit Testing

Work in Progress.

On Language and Framework Superiority

It’s rather pervasive, especially among members of the web development industry, to consider certain languages, frameworks, and libraries as supreme to others - in some cases going as far as to say that said language, framework, or library is the best in the world.

Such blanket statements are inherently erroneous and speak to the inexperience of the person making the statement.

At the end of the day, all languages, frameworks, libraries, principals, patterns, mechanisms, and architectures are merely tools - they exist solely as a means to an end, as a means to get the job done. Depending on the situation, one tool may be better suited than another to get that job done, but that never implies that said tool is in any manner “supreme” to the other(s) outside of that situation.

It’s important to understand that everything exists within a given context - all that ever succeeded did so within a clearly defined context, and everything that ever failed did so within an equally clearly defined context. Pick the tools that best fit the context within which you wish to use them.

The specific criteria for tool selection that arise out of a given context aren’t always strictly technical in nature - generally, political and logistical considerations have to be factored in, and it’s up to you to decide how to balance the two. The priority of feature completion (time-to-market), the current skills and operating scope of the team, the performance requirements of the solution, the weight assigned to maintainability and the minimization of future technical debt, the community and ecosystem around the tech/tool, and more should go into deciding upon a specific tool, not the preference of the developer or development team.

This sounds rather quite obvious, and, alas, it probably is to most. With that said, I all-too-often see and hear people publicly declare their favorite technologies and tech stacks and state that they use them for every project or every requirement, which is asking for trouble.

Since I often hear this from some members of the web development community, I most generally see JavaScript, Node.js, and MongoDB held up to very high esteem and applied (erroneously) unilaterally across contexts. Just because you can use JavaScript on the front-end and the back-end doesn’t mean you should. That said, it doesn’t mean you shouldn’t either - decide based on the context you’re operating within. Similarly, just because there are methods of programming Microcontrollers with JavaScript doesn’t imply that that’s a good idea either - it just means the possibility exists. The same goes for MongoDB - most domains are inherently relational, and trying to represent such data in a denormalized manner won’t always work out well (not that there aren’t use cases for document storage forms - there are).

Additionally, undue hate, negativity, and insults toward technologies follow naturally (unfortunately) from the designation of other technologies as supreme. For instance, you most often hear people make fun of C#, Java, and PHP as being old, legacy, out of date, reserved only for enterprise use cases, and too hard to work with. None of this is true, and the hilarious thing is that many of the people who make such statements have likely never worked with any of these, and instead merely jump on the bandwagon. The fact of the matter is that C#, Java, and PHP are great languages, have their use cases, and do their jobs very well, just as JavaScript does its job well.

Just like you wouldn’t attempt to use a Phillips screwdriver in all scenarios just because you “prefer” it to flatheads, don’t try to utilize technologies in all situations either. If you have to massage the tool to fit the use case, then the tool isn’t the right tool for the job. Let the needs of the project - both technical and political, your existing experience, the size and maturity of the community and the ecosystem around the tool, and any other relevant criteria govern technology selection. In doing so, you can make decisions through a purely objective lens.

On Coding Against Interfaces and Dependency Injection

This is a quick overview. To learn about Dependency Injection in full, see my article A Practical Introduction to Dependency Injection.

“Dependency Injection” - it sounds complicated. Three natural questions arise - “what’s a dependency?”, “what does it mean for a dependency to be injected?”, “why would I want to inject a dependency?”

If some class A relies on the functionality of a class B, then B is a dependency for A, or, in other words, A holds a dependency on B. Consider a UserService class using the functionality of an EmailSender class. In that case, EmailSender is a dependency for UserService - UserService depends on EmailSender to function correctly.

It’s pretty clear that dependencies are not a rare thing. In fact, it’s common for a class to have many dependencies, and that’s not a bad thing (so long as relevant principles like SRP aren’t violated). The problem, though, comes from how you manage those dependencies. The concept of a dependency introduces the idea of relationships between classes, and relationships can cause different levels of coupling. The two partners of UserService and EmailSender are collaborators - they collaborate together. How said collaborators collaborate determines how much an application will resist change and resist testing.

If UserService instantiates a new EmailSender in its constructor, then calling code for UserService has no control over how the EmailSender is managed, nor can it swap out the EmailSender for a different kind if the business migrates or for a fake in a test case. We can solve this high degree of coupling and invert control back to the caller by only permitting UserService to receive an instance of an EmailSender into its constructor instead, and not create the EmailSender itself.

This, then, answers the second question and third questions - passing an instance of a dependency into a constructor (or through function arguments, we don’t have to restrict ourselves to classes) is what it means to inject that dependency, and the reason we do it is to reduce coupling and give control back to the caller.

The issue that probably comes to mind, at this moment, is if UserService expects the type of the injected dependency to be EmailSender, then we still have high coupling because it means we have to pass an EmailSender in. We can’t pass in a FakeEmailSender. We’ve solved the creation side of things - the lifetime management side, but not the fact the dependency remains too rigid through the type system. This is where interfaces come in.

Consider the notion of powering a toaster. You, the user, need not have any understanding of electronics to figure out how to run current through the toaster and heat the filament. Similarly, you need not worry about the max current that can be pulled through the socket, the voltage potential between live and neutral, what the frequency of the AC current is, what current draw over what time period will cause a breaker to trip, or even what the source of the electricity is.

Really, the only thing you’re concerned about is inserting the plug into the outlet. If the plug doesn’t fit, then you have a problem - maybe you’re trying to use a European plug in a North American outlet and need an adapter (this is a design pattern), but, for the most part, the functionality is plug and play. The electricity source and the individual wires behind that outlet can change as much as it wants, but never will that affect your ability to place the toaster in the outlet so long as the outlet never changes. Another way to look at is you can swap the toaster for another toaster, a microwave, a kettle, or anything without the wall or wall wiring have to change. The outlet is the interface - it’s agnostic to any concrete implementation of electricity or appliance, and it merely defines behavior (current flow) - not concretions, but behavior.

By defining an interface like IEmailSender, you’re freed to create concrete implementations such as SendGridEmailSender : IEmailSender or FakeEmailSender : IEmailSender (that’s SendGridEmailSender implements IEmailSender and FakeEmailSender implements IEmailSender for Java and TypeScript developers) that implement the interface. To implement the interface means to have the behavior as defined in the interface.

Interfaces can go hand in hand with Dependency Injection because now you can depend upon abstractions and not concretions. You can inject some email sender that honors the IEmailSender interface into UserService, and UserService doesn’t need to know what it actually is because it knows what behavior is possible/provided thanks to the interface.

This was a quick overview. To learn about Dependency Injection in full, see my article A Practical Introduction to Dependency Injection](/2020/12/a-practical-introduction-to-dependency-injection/).

On Language Proficiency and the Preservation of Commonalities

Rather recently, I heard someone say that when working with various programming languages, they attempt to maintain and preserve commonalities - “mannerisms” - between those languages. For instance, they stick to classes as much as possible in JavaScript as to maintain a similar feel to Java and C#, and that this helps them easily move between languages rapidly.

This is an atrociously flawed mindset, the implications of which are fairly obvious. If you constrain yourself to utilizing the features shared across all languages, you effectively lock yourself to the least common denominator. There no longer becomes a reason to pick one programming language over another, for all will act just the same to you. The intersection of the set of features between languages will grow ever smaller with the more languages you attempt to add to the mix.

This idea of preserving commonalities is one that I can understand if coming from a new developer. They may not be viewing programming languages and technologies as mere tools quite yet, and they are likely moving between learning different languages with no clear direction, rhyme, or reason. This issue likely stems from a new programmer thinking that the more languages they add to their tool belt, the better a developer they become, when, in fact, the opposite is true. Learning only for the sake of learning, while not a bad thing in and of itself, tends to produce mindsets like these. Instead, a beginner should pick a language based on their interests, excel to a reasonable level of proficiency with that language, and then move on to a new one as required, taking advantage of the full scope of features that each language has to offer as they go.

I’m certainly not saying that learning for the sake of learning is a bad thing, just that having a reason to learn often makes for an easier and more streamlined learning experience. But deciding to learn the basics of Java, then the basics of C#, and then the basics of JavaScript simply makes you a software developer who knows nothing of real substance about 3 different languages when you could instead aim to reach a level of relative proficiency in just one said language, the knowledge of which will be easily transferable to the other two when such a transfer is needed.

That last point is what makes mere surface-level knowledge across an array of languages nowhere near as valuable as proficient-level knowledge of one. With the exception of static and dynamic typing and functional programming, most languages are actually pretty similar to one another, thus even the advanced concepts of a language like C# will prove somewhat helpful if you need to learn Java or JavaScript. Asynchrony, for instance, is a generally language-agnostic concept that is, most unfortunately, often taught within the context of a specific one, but you won’t hear about asynchrony if basic data structures and control flow is the limit to how far you get dividing your time across N languages. If you had stuck with only C#, knowledge of C#’s asynchrony features would serve you well when making the move to JavaScript.

Changelog

February 27, 2021 at 11:47 PM CDT (05:47 AM Zulu):

• Added section On Unit Testing.
• Added section On Language and Framework Superiority.

March 3, 2021 at 12:03 AM CDT (06:04 AM Zulu):

• Added section On Coding Against Interfaces and Dependency Injection.
• Added section On Language Proficiency and the Preservation of Commonalities.

It would make sense, then, to extrapolate this idea and say that comment usage itself is an anti-pattern. But that, for reasons which should be quite obvious, is undeniably false. In fact, the biggest anti-pattern of all is believing that some statement or idea applies to all situations unilaterally, without exception, and without limitation.

While it is true that comments have the risk of becoming stale over time and need to be maintained along with the code, there are, in fact, I believe, a multitude of situations where comment usage is justified, primarily because comments excel greatly at providing information that is not expressible in code.

Sacrifices for Performance

There may be small, rare cases where the performance requirements of an application dictate that readability must be sacrificed to maintain adequate perf. In such cases, comment usage is justified. Indeed, readability should seldom be sacrificed, but at the end of the day, design requirements must be fulfilled. You could have beautifully written and elegant code, but if the system doesn’t work as needed, or if it doesn’t function at the performance level expected, what’s the point?

Workarounds

There are generally cases where one has to take seemingly unjustified actions in code to work around a bug or handle an edge case. It is crucial that this be well documented, thus comment usage is justified (and required), perhaps even linking to relevant issue numbers, if any.

English Explanations

Certain operations may benefit from English explanations - especially paradigms that not all developers are aware of. Functional Reactive Programming, for instance, where the dimension of time is implicit and all data is streamed, might benefit from a brief explanation. With that said, such an explanation need not be first-class in code, but a small one here and there doesn’t necessarily imply issues with expressiveness. If anything, it adds to it. Concepts like these aren’t always intuitive, can’t always be understood no matter how expressive and intension-revealing the code might be (especially if they’re fundamentally implicit, perhaps even philosophical in nature), and a comment is a small price to pay to avoid confusion.

A need for English explanations may also arise out of situations where code is performing operations that are heavily algorithmic or mathematical in nature, such as graphics, audio analysis/FFT, physics, etc. Namely, concepts beyond the scope of most developers who aren’t specialized in the domain.

When Comment Usage isn’t Justified & Why Reliance Should be Placed on Tests

In almost all other cases, comment usage does indeed imply that code should be refactored to express the meaning that once only existed within the comment. During refactoring, the meaning once implied in comments should manifest itself within the code based on proper naming, emphasis on behavior, the Tell Don’t Ask principle, and, crucially, unit tests.

Saying that a unit test only exists to validate a given behavior is equally erroneous as stating that comments are always an anti-pattern. There is another crucial piece of value provided by tests that isn’t always taken advantage of - not only do they verify behavior, they tell stories, they provide insight into logic and the domain.

Test suites should be written such that a developer can gain all the insight he or she needs into the codebase by reading the story that the tests tell, be that through scenarios like Given/When/Then or Arrange/Act/Assert. Writing expressive code in the first place plus having expressive test suites to fill in the gaps should remove both ambiguity and the need for comments entirely except in those cases listed above. Heavy procedural flows generally attract comments, for instance, when they can be perfectly explained in tests.

Conclusion

Everything is situational. Use comments when comments will add value. That’s it. But don’t use them in lieu of or as an excuse for going without expressive code and expressive test suites.

This article was first written for Smashing Magazine on December 30, 2020. You can find it here.

Introduction

The concept of Dependency Injection is, at its core, a fundamentally simple notion. It is, however, commonly presented in a manner alongside the more theoretical concepts of Inversion of Control, Dependency Inversion, the SOLID Principles, and so forth. To make it as easy as possible for you to get started using Dependency Injection and begin reaping its benefits, this article will remain very much on the practical side of the story, depicting examples that show precisely the benefits of its use, in a manner chiefly divorced from the associated theory. We’ll spend only a very little amount of time discussing the academic concepts that surround dependency injection here, for the bulk of that explanation will be reserved for the second article of this series. Indeed, entire books can be and have been written that provide a more in-depth and rigorous treatment of the concepts.

Here, we’ll start with a simple explanation, move to a few more real-world examples, and then discuss some background information. Another article, to follow this one, will discuss how Dependency Injection fits into the overall ecosystem of applying best-practice architectural patterns.

A Simple Explanation

“Dependency Injection” is an overly-complex term for an extremely simple concept. At this point, some wise and reasonable questions would be “how do you define “dependency”?”, “what does it mean for a dependency to be “injected”?”, “can you inject dependencies in different ways?”, “why is this useful?” You might not believe that a term like “Dependency Injection” can be explained in two code snippets and a couple of words, but alas, it can:

The simplest way to explain the concept is to show you. This is not dependency injection:

import { Engine } from './Engine';

class Car {
    private engine: Engine;

    public constructor () {
        this.engine = new Engine();
    }

    public startEngine(): void {
        this.engine.fireCylinders();
    }
}

And this is dependency injection:

import { Engine } from './Engine';

class Car {
    private engine: Engine;

    public constructor (engine: Engine) {
        this.engine = engine;
    }
    
    public startEngine(): void {
        this.engine.fireCylinders();
    }
}

Done. That’s it. Cool. The end.

What changed? Rather than allow the Car class to instantiate Engine, as it did in the first example, in the second example, Car had an instance of Engine passed in, or injected in, from some higher level of control, to its constructor. That’s it. At its core, this is all dependency injection is - the act of injecting (passing) a dependency into another class or function. Anything else involving the notion of dependency injection is simply a variation on this fundamental and simple concept. Put trivially, dependency injection is a technique whereby an object receives other objects it depends on, called dependencies, rather than creating them itself.

In general, to define what a “dependency” is, if some class A uses the functionality of a class B, then B is a dependency for A, or, in other words, A has a dependency on B. Of course, this isn’t limited to classes and holds for functions too. In this case, the class Car has a dependency on the Engine class, or Engine is a dependency of Car. Dependencies are simply variables, just like most things in programming.

Dependency Injection is widely-used to support many use cases, but perhaps the most blatant of uses is to permit easier testing. In the first example, we can’t easily mock out engine because the Car class instantiates it. The real engine is always being used. But, in the latter case, we have control over the Engine that is used, which means, in a test, we can subclass Engine and override its methods. For example, if we wanted to see what Car.startEngine() does if engine.fireCylinders() throws an error, we could simply create a FakeEngine class, have it extend the Engine class, and then override fireCylinders to make it throw an error. In the test, we can inject that FakeEngine object into the constructor for Car. Since FakeEngine is an Engine by implication of inheritance, the TypeScript type system is satisfied.

I want to make it very, very clear that what you see above is the core notion of dependency injection. A Car, by itself, is not smart enough to know what engine it needs. Only the engineers that construct the car understand the requirements for its engines and wheels. Thus, it makes sense that the people who construct the car provide the specific engine required, rather than letting a Car itself pick whichever engine it wants to use. I use the word “construct” specifically because you construct the car by calling the constructor, which is the place dependencies are injected. If the car also created its own tires in addition to the engine, how do we know that the tires being used are safe to be spun at the max RPM the engine can output? For all these reasons and more, it should make sense, perhaps intuitively, that Car should have nothing to do with deciding what Engine and what Wheels it uses. They should be provided from some higher level of control. In the latter example depicting dependency injection in action, if you imagine Engine to be an abstract class rather than a concrete one, this should make even more sense - the car knows it needs an engine and it knows the engine has to have some basic functionality, but how that engine is managed and what the specific implementation of it is is reserved for being decided and provided by the piece of code that creates (constructs) the car.

A Real-World Example

We’re going to look at a few more practical examples that hopefully help to explain, again intuitively, why dependency injection is useful. Hopefully, by not harping on the theoretical and instead moving straight into applicable concepts, you can more fully see the benefits that dependency injection provides, and the difficulties of life without it. We’ll revert to a slightly more “academic” treatment of the topic later.

We’ll start by constructing our application normally, in a manner highly coupled, without utilizing dependency injection or abstractions, so that we come to see the downsides of this approach and the difficulty it adds to testing. Along the way, we’ll gradually refactor until we rectify all of the issues.

To begin, suppose you’ve been tasked with building two classes - an email provider and a class for a data access layer that needs to be used by some UserService. We’ll start with data access, but both are easily defined:

// UserRepository.ts

import { dbDriver } from 'pg-driver';

export class UserRepository {
    public async addUser(user: User): Promise<void> {
        // ... dbDriver.save(...)
    }

    public async findUserById(id: string): Promise<User> {
        // ... dbDriver.query(...)
    }
    
    public async existsByEmail(email: string): Promise<boolean> {
        // ... dbDriver.save(...)
    }
}

Note: The name “Repository” here comes from the “Repository Pattern”, a method of decoupling your database from your business logic. You can learn more about the Repository Pattern, but for the purposes of this article, you can simply consider it to be some class that encapsulates away your database so that, to business logic, your data storage system is treated as merely an in-memory collection. Explaining the Repository Pattern fully is outside the purview of this article.

This is how we normally expect things to work, and dbDriver is hardcoded within the file.

In your UserService, you’d import the class, instantiate it, and start using it:

import { UserRepository } from './UserRepository.ts';

class UserService {
    private readonly userRepository: UserRepository;
    
    public constructor () {
        // Not dependency injection.
        this.userRepository = new UserRepository();
    }

    public async registerUser(dto: IRegisterUserDto): Promise<void> {
        // User object & validation
        const user = User.fromDto(dto);

        if (await this.userRepository.existsByEmail(dto.email))
            return Promise.reject(new DuplicateEmailError());
            
        // Database persistence
        await this.userRepository.addUser(user);
        
        // Send a welcome email
        // ...
    }

    public async findUserById(id: string): Promise<User> {
        // No need for await here, the promise will be unwrapped by the caller.
        return this.userRepository.findUserById(id);
    }
}

Once again, all remains normal.

A brief aside: A DTO is a Data Transfer Object - it’s an object that acts as a property bag to define a standardized data shape as it moves between two external systems or two layers of an application. You can learn more about DTOs from Martin Fowler’s article on the topic, here. In this case, IRegisterUserDto defines a contract for what the shape of data should be as it comes up from the client. I only have it contain two properties - id and email. You might think it’s peculiar that the DTO we expect from the client to create a new user contains the user’s ID even though we haven’t created a user yet. The ID is a UUID and I allow the client to generate it for a variety of reasons, which are outside the scope of this article. Additionally, the findUserById function should map the User object to a response DTO, but I neglected that for brevity. Finally, in the real world, I wouldn’t have a User domain model contain a fromDto method. That’s not good for domain purity. Once again, its purpose is brevity here.

Next, you want to handle the sending of emails. Once again, as normal, you can simply create an email provider class and import it into your UserService.

// SendGridEmailProvider.ts

import { sendMail } from 'sendgrid';

export class SendGridEmailProvider {
    public async sendWelcomeEmail(to: string): Promise<void> {
        // ... await sendMail(...);
    }
}

Within UserService:

import { UserRepository }  from  './UserRepository.ts';
import { SendGridEmailProvider } from './SendGridEmailProvider.ts';

class UserService {
    private readonly userRepository: UserRepository;
    private readonly sendGridEmailProvider: SendGridEmailProvider;

    public constructor () {
        // Still not doing dependency injection.
        this.userRepository = new UserRepository();
        this.sendGridEmailProvider = new SendGridEmailProvider();
    }

    public async registerUser(dto: IRegisterUserDto): Promise<void> {
        // User object & validation
        const user = User.fromDto(dto);
        
        if (await this.userRepository.existsByEmail(dto.email))
            return Promise.reject(new DuplicateEmailError());
        
        // Database persistence
        await this.userRepository.addUser(user);
        
        // Send welcome email
        await this.sendGridEmailProvider.sendWelcomeEmail(user.email);
    }

    public async findUserById(id: string): Promise<User> {
        return this.userRepository.findUserById(id);
    }
}

We now have a fully working class, and in a world where we don’t care about testability or writing clean code by any manner of the definition at all, and in a world where technical debt is non-existent and pesky program managers don’t set deadlines, this is perfectly fine. Unfortunately, that’s not a world we have the benefit of living in.

What happens when we decide we need to migrate away from SendGrid for emails and use MailChimp instead? Similarly, what happens when we want to unit test our methods - are we going to use the real database in the tests? Worse, are we actually going to send real emails to potentially real email addresses and pay for it too? In the traditional JavaScript ecosystem, the methods of unit testing classes under this configuration are fraught with complexity and over-engineering. People bring in whole entire libraries simply to provide stubbing functionality, which adds all kinds of layers of indirection, and, even worse, can directly couple the tests to the implementation of the system under test, when, in reality, tests should never know how the real system works (this is known as black-box testing). We’ll work to mitigate these issues as we discuss what the actual responsibility of UserService is and apply new techniques of dependency injection.

Consider, for a moment, what a UserService does. The whole point of the existence of UserService is to execute specific use cases involving users - registering them, reading them, updating them, etc. It’s a best practice for classes and functions to have only one responsibility (SRP - the Single Responsibility Principle), and the responsibility of UserService is to handle user-related operations. Why, then, is UserService responsible for controlling the lifetime of UserRepository and SendGridEmailProvider in this example? Imagine if we had some other class used by UserService which opened a long-running connection. Should UserService be responsible for disposing of that connection too? Of course not. All of these dependencies have a lifetime associated with them - they could be singletons, they could be transient and scoped to a specific HTTP Request, etc. The controlling of these lifetimes is well outside the purview of UserService. So, to solve these issues, we’ll inject all of the dependencies in, just like we saw before.

import { UserRepository }  from  './UserRepository.ts';
import { SendGridEmailProvider } from './SendGridEmailProvider.ts';

class UserService {
    private readonly userRepository: UserRepository;
    private readonly sendGridEmailProvider: SendGridEmailProvider;

    public constructor (
        userRepository: UserRepository,
        sendGridEmailProvider: SendGridEmailProvider
    ) {
        // Yay! Dependencies are injected.
        this.userRepository = userRepository;
        this.sendGridEmailProvider = sendGridEmailProvider;
    }

    public async registerUser(dto: IRegisterUserDto): Promise<void> {
        // User object & validation
        const user = User.fromDto(dto);

        if (await this.userRepository.existsByEmail(dto.email))
            return Promise.reject(new DuplicateEmailError());
        
        // Database persistence
        await this.userRepository.addUser(user);
        
        // Send welcome email
        await this.sendGridEmailProvider.sendWelcomeEmail(user.email);
    }

    public async findUserById(id: string): Promise<User> {
        return this.userRepository.findUserById(id);
    }
}

Great - now UserService receives pre-instantiated objects, and whichever piece of code calls and creates a new UserService is the piece of code in charge of controlling the lifetime of the dependencies. We’ve inverted control away from UserService and up to a higher level. If I only wanted to show how we could inject dependencies through the constructor as to explain the basic tenant of dependency injection, I could stop here. There are still some problems from a design perspective, however, which when rectified, will serve to make our use of dependency injection all the more powerful.

Firstly, why does UserService know that we’re using SendGrid for emails? Secondly, both dependencies are on concrete classes - the concrete UserRepository and the concrete SendGridEmailProvider. This relationship is too rigid - we’re stuck having to pass in some object that is a UserRepository and is a SendGridEmailProvider.

This isn’t great because we want UserService to be completely agnostic to the implementation of its dependencies. By having UserService be blind in that manner, we can swap out the implementations without affecting the service at all - this means, if we decide to migrate away from SendGrid and use MailChimp instead, we can do so. It also means if we want to fake out the email provider for tests, we can do that too. What would be useful is if we could define some public interface and force that incoming dependencies abide by that interface, while still having UserService be agnostic to implementation details. Put another way, we need to force UserService to only depend on an abstraction of its dependencies, and not it’s actual concrete dependencies. We can do that through, well, interfaces.

Start by defining an interface for the UserRepository and implement it:

// UserRepository.ts

import { dbDriver } from 'pg-driver';

export interface IUserRepository {
    addUser(user: User): Promise<void>;
    findUserById(id: string): Promise<User>;
    existsByEmail(email: string): Promise<boolean>;
}

export class UserRepository implements IUserRepository {
    public async addUser(user: User): Promise<void> {
        // ... dbDriver.save(...)
    }

    public async findUserById(id: string): Promise<User> {
        // ... dbDriver.query(...)
    }

    public async existsByEmail(email: string): Promise<boolean> {
        // ... dbDriver.save(...)
    }
}

And define one for the email provider, also implementing it:

// IEmailProvider.ts
export interface IEmailProvider {
    sendWelcomeEmail(to: string): Promise<void>;
}

// SendGridEmailProvider.ts
import { sendMail } from 'sendgrid';
import { IEmailProvider } from './IEmailProvider';

export class SendGridEmailProvider implements IEmailProvider {
    public async sendWelcomeEmail(to: string): Promise<void> {
        // ... await sendMail(...);
    }
}

Note: This is the Adapter Pattern from the Gang of Four Design Patterns.

Now, our UserService can depend on the interfaces rather than the concrete implementations of the dependencies:

import { IUserRepository }  from  './UserRepository.ts';
import { IEmailProvider } from './SendGridEmailProvider.ts';

class UserService {
    private readonly userRepository: IUserRepository;
    private readonly emailProvider: IEmailProvider;

    public constructor (
        userRepository: IUserRepository,
        emailProvider: IEmailProvider
    ) {
        // Double yay! Injecting dependencies and coding against interfaces.
        this.userRepository = userRepository;
        this.emailProvider = emailProvider;
    }

    public async registerUser(dto: IRegisterUserDto): Promise<void> {
        // User object & validation
        const user = User.fromDto(dto);

        if (await this.userRepository.existsByEmail(dto.email))
            return Promise.reject(new DuplicateEmailError());
        
        // Database persistence
        await this.userRepository.addUser(user);
        
        // Send welcome email
        await this.emailProvider.sendWelcomeEmail(user.email);
    }

    public async findUserById(id: string): Promise<User> {
        return this.userRepository.findUserById(id);
    }
}

If interfaces are new to you, this might look very, very complex. Indeed, the concept of building loosely coupled software might be new to you too. Think about wall receptacles. You can plug any device into any receptacle so long as the plug fits the outlet. That’s loose coupling in action. Your toaster is not hard-wired into the wall, because if it was, and you decide to upgrade your toaster, you’re out of luck. Instead, outlets are used, and the outlet defines the interface. Similarly, when you plug an electronic device into your wall receptacle, you’re not concerned with the voltage potential, the max current draw, the AC frequency, etc., you just care if the plug fits into the outlet. You could have an electrician come in and change all the wires behind that outlet, and you won’t have any problems plugging in your toaster, so long as that outlet doesn’t change. Further, your electricity source could be switched to come from the city or your own solar panels, and once again, you don’t care as long as you can still plug into that outlet. The interface is the outlet, providing “plug-and-play” functionality. In this example, the wiring in the wall and the electricity source is akin to the dependencies and your toaster is akin to the UserService (it has a dependency on the electricity) - the electricity source can change and the toaster still works fine and need not be touched, because the outlet, acting as the interface, defines the standard means for both to communicate. In fact, you could say that the outlet acts as an “abstraction” of the wall wiring, the circuit breakers, the electrical source, etc.

It is a common and well-regarded principle of software design, for the reasons above, to code against interfaces (abstractions) and not implementations, which is what we’ve done here. In doing so, we’re given the freedom to swap out implementations as we please, for those implementations are hidden behind the interface (just like wall wiring is hidden behind the outlet), and so the business logic that uses the dependency never has to change so long as the interface never changes. Remember, UserService only needs to know what functionality is offered by its dependencies, not how that functionality is supported behind the scenes. That’s why using interfaces works.

These two simple changes of utilizing interfaces and injecting dependencies make all the difference in the world when it comes to building loosely coupled software and solves all of the problems we ran into above.

If we decide tomorrow that we want to rely on MailChimp for emails, we simply create a new MailChimp class that honors the IEmailProvider interface and inject it in instead of SendGrid. The actual UserService class never has to change even though we’ve just made a ginormous change to our system by switching to a new email provider. The beauty of these patterns is that UserService remains blissfully unaware of how the dependencies it uses work behind the scenes. The interface serves as the architectural boundary between both components, keeping them appropriately decoupled.

Additionally, when it comes to testing, we can create fakes that abide by the interfaces and inject them instead. Here, you can see a fake repository and a fake email provider.

// Both fakes:
class FakeUserRepository implements IUserRepository {
    private readonly users: User[] = [];

    public async addUser(user: User): Promise<void> {
        this.users.push(user);
    }

    public async findUserById(id: string): Promise<User> {
        const userOrNone = this.users.find(u => u.id === id);

        return userOrNone
            ? Promise.resolve(userOrNone)
            : Promise.reject(new NotFoundError());
    }

    public async existsByEmail(email: string): Promise<boolean> {
        return Boolean(this.users.find(u => u.email === email));
    }

    public getPersistedUserCount = () => this.users.length;
}

class FakeEmailProvider implements IEmailProvider {
    private readonly emailRecipients: string[] = [];

    public async sendWelcomeEmail(to: string): Promise<void> {
        this.emailRecipients.push(to);
    }

    public wasEmailSentToRecipient = (recipient: string) =>
        Boolean(this.emailRecipients.find(r => r === recipient));
}

Notice that both fakes implement the same interfaces that UserService expects its dependencies to honor. Now, we can pass these fakes into UserService instead of the real classes and UserService will be none the wiser, it’ll use them just as if they were the real deal. The reason it can do that is because it knows that all of the methods and properties it wants to use on its dependencies do indeed exist and are indeed accessible (because they implement the interfaces), which is all UserService needs to know (i.e, not how the dependencies work).

We’ll inject these two during tests, and it’ll make the testing process so much easier and so much more straightforward than what you might be used to when dealing with over-the-top mocking and stubbing libraries, working with Jest’s own internal tooling, or trying to monkey-patch.

Here are actual tests using the fakes.

// Fakes
let fakeUserRepository: FakeUserRepository;
let fakeEmailProvider: FakeEmailProvider;

// SUT
let userService: UserService;

// We want to clean out the internal arrays of both fakes 
// before each test.
beforeEach(() => {
    fakeUserRepository = new FakeUserRepository();
    fakeEmailProvider = new FakeEmailProvider();
    
    userService = new UserService(fakeUserRepository, fakeEmailProvider);
});

// A factory to easily create DTOs.
// Here, we have the optional choice of overriding the defaults
// thanks to the built in `Partial` utility type of TypeScript.
function createSeedRegisterUserDto(opts?: Partial<IRegisterUserDto>): IRegisterUserDto {
    return {
        id: 'someId',
        email: 'example@domain.com',
        ...opts
    };
}

test('should correctly persist a user and send an email', async () => {
    // Arrange
    const dto = createSeedRegisterUserDto();

    // Act
    await userService.registerUser(dto);

    // Assert
    const expectedUser = User.fromDto(dto);
    const persistedUser = await fakeUserRepository.findUserById(dto.id);
    
    const wasEmailSent = fakeEmailProvider.wasEmailSentToRecipient(dto.email);

    expect(persistedUser).toEqual(expectedUser);
    expect(wasEmailSent).toBe(true);
});

test('should reject with a DuplicateEmailError if an email already exists', async () => {
    // Arrange
    const existingEmail = 'john.doe@live.com';
    const dto = createSeedRegisterUserDto({ email: existingEmail });
    const existingUser = User.fromDto(dto);
    
    await fakeUserRepository.addUser(existingUser);

    // Act, Assert
    await expect(userService.registerUser(dto))
        .rejects.toBeInstanceOf(DuplicateEmailError);

    expect(fakeUserRepository.getPersistedUserCount()).toBe(1);
});

test('should correctly return a user', async () => {
    // Arrange
    const user = User.fromDto(createSeedRegisterUserDto());
    await fakeUserRepository.addUser(user);

    // Act
    const receivedUser = await userService.findUserById(user.id);

    // Assert
    expect(receivedUser).toEqual(user);
});

You’ll notice a few things here - the hand-written fakes are very simple. There’s no complexity from mocking frameworks which only serve to obfuscate. Everything is hand-rolled and that means there is no magic in the codebase. Asynchronous behavior is faked to match the interfaces. I use async/await in the tests even though all behavior is synchronous because I feel that it more closely matches how I’d expect the operations to work in the real world and because by adding async/await, I can run this same test suite against real implementations too in addition to the fakes, thus handing asynchrony appropriately is required. In fact, in real life, I would most likely not even worry about mocking the database and would instead use a local DB in a Docker container until there were so many tests that I had to mock it away for performance. I could then run the in-memory DB tests after every single change and reserve the real local DB tests for right before committing changes and for on the build server in the CI/CD pipeline.

In the first test, in the “arrange” section, we simply create the DTO. In the “act” section, we call the system under test and execute its behavior. Things get slightly more complex when making assertions. Remember, at this point in the test, we don’t even know if the user was saved correctly. So, we define what we expect a persisted user to look like, and then we call the fake Repository and ask it for a user with the ID we expect. If the UserService didn’t persist the user correctly, this will throw a NotFoundError and the test will fail, otherwise, it will give us back the user. Next, we call the fake email provider and ask it if it recorded sending an email to that user. Finally, we make the assertions with Jest and that concludes the test. It’s expressive and reads just like how the system is actually working. There’s no indirection from mocking libraries and there’s no coupling to the implementation of the UserService.

In the second test, we create an existing user and add it to the repository, then we try to call the service again using a DTO that has already been used to create and persist a user, and we expect that to fail. We also assert that no new data was added to the repository.

For the third test, the “arrange” section now consists of creating a user and persisting it to the fake Repository. Then, we call the SUT, and finally, check if the user that comes back is the one we saved in the repo earlier.

These examples are relatively simple, but when things get more complex, being able to rely on dependency injection and interfaces in this manner keeps your code clean and makes writing tests a joy.

A brief aside on testing: In general, you don’t need to mock out every dependency that the code uses. Many people, erroneously, claim that a “unit” in a “unit test” is one function or one class. That could not be more incorrect. The “unit” is defined as the “unit of functionality” or the “unit of behavior”, not one function or class. So if a unit of behavior uses 5 different classes, you don’t need to mock out all those classes unless they reach outside of the boundary of the module. In this case, I mocked the database and I mocked the email provider because I have no choice. If I don’t want to use a real database and I don’t want to send an email, I have to mock them out. But if I had a bunch more classes that didn’t do anything across the network, I would not mock them because they’re implementation details of the unit of behavior. I could also decide against mocking the database and emails and spin up a real local database and a real SMTP server, both in Docker containers. On the first point, I have no problem using a real database and still calling it a unit test so long as it’s not too slow. Generally, I’d use the real DB first until it became too slow and I had to mock, as discussed above. But, no matter what you do, you have to be pragmatic - sending welcome emails is not a mission-critical operation, thus we don’t need to go that far in terms of SMTP servers in Docker containers. Whenever I do mock, I would be very unlikely to use a mocking framework or try to assert on the number of times called or parameters passed except in very rare cases, because that would couple tests to the implementation of the system under test, and they should be agnostic to those details.

Performing Dependency Injection without Classes and Constructors

So far, throughout the article, we’ve worked exclusively with classes and injected the dependencies through the constructor. If you’re taking a functional approach to development and wish not to use classes, one can still obtain the benefits of dependency injection using function arguments. For example, our UserService class above could be refactored into:

function makeUserService(
    userRepository: IUserRepository,
    emailProvider: IEmailProvider
): IUserService {
    return {
        registerUser: async dto => {
            // ...
        },

        findUserById: id => userRepository.findUserById(id)
    }
}

It’s a factory that receives the dependencies and constructs the service object. We can also inject dependencies into Higher Order Functions. A typical example would be creating an Express Middleware function that gets a UserRepository and an ILogger injected:

function authProvider(userRepository: IUserRepository, logger: ILogger) {
    return async (req: Request, res: Response, next: NextFunction) => {
        // ...
        // Has access to userRepository, logger, req, res, and next.
    }
}

In the first example, I didn’t define the type of dto and id because if we define an interface called IUserService containing the method signatures for the service, then the TS Compiler will infer the types automatically. Similarly, had I defined a function signature for the Express Middleware to be the return type of authProvider, I wouldn’t have had to declare the argument types there either.

If we considered the email provider and the repository to be functional too, and if we injected their specific dependencies as well instead of hard coding them, the root of the application could look like this:

import { sendMail } from 'sendgrid';

async function main() {
    const app = express();
    
    const dbConnection = await connectToDatabase();
    
    // Change emailProvider to `makeMailChimpEmailProvider` whenever we want
    // with no changes made to dependent code.
    const userRepository = makeUserRepository(dbConnection);
    const emailProvider = makeSendGridEmailProvider(sendMail);
    
    const userService = makeUserService(userRepository, emailProvider);

    // Put this into another file. It's a controller action.
    app.post('/login', (req, res) => {
        await userService.registerUser(req.body as IRegisterUserDto);
        return res.send();
    });

    // Put this into another file. It's a controller action.
    app.delete(
        '/me', 
        authProvider(userRepository, emailProvider), 
        (req, res) => { ... }
    );
}

Notice that we fetch the dependencies that we need, like a database connection or third-party library functions, and then we utilize factories to make our first-party dependencies using the third-party ones. We then pass them into the dependent code. Since everything is coded against abstractions, I can swap out either userRepository or emailProvider to be any different function or class with any implementation I want (that still implements the interface correctly) and UserService will just use it with no changes needed, which, once again, is because UserService cares about nothing but the public interface of the dependencies, not how the dependencies work.

As a disclaimer, I want to point out a few things. As stated earlier, this demo was optimized for showing how dependency injection makes life easier, and thus it wasn’t optimized in terms of system design best practices insofar as the patterns surrounding how Repositories and DTOs should technically be used. In real life, one has to deal with managing transactions across repositories and the DTO should generally not be passed into service methods, but rather mapped in the controller to allow the presentation layer to evolve separately from the application layer. The userSerivce.findById method here also neglects to map the User domain object to a DTO, which it should do in real life. None of this affects the DI implementation though, I simply wanted to keep the focus on the benefits of DI itself, not Repository design, Unit of Work management, or DTOs. Finally, although this may look a little like the NestJS framework in terms of the manner of doing things, it’s not, and I actively discourage people from using NestJS for reasons outside the scope of this article.

A Brief Theoretical Overview

All applications are made up of collaborating components, and the manner in which those collaborators collaborate and are managed will decide how much the application will resist refactoring, resist change, and resist testing. Dependency injection mixed with coding against interfaces is a primary method (among others) of reducing the coupling of collaborators within systems, and making them easily swappable. This is the hallmark of a highly cohesive and loosely coupled design.

The individual components that make up applications in non-trivial systems must be decoupled if we want the system to be maintainable, and the way we achieve that level of decoupling, as stated above, is by depending upon abstractions, in this case, interfaces, rather than concrete implementations, and utilizing dependency injection. Doing so provides loose coupling and gives us the freedom of swapping out implementations without needing to make any changes on the side of the dependent component/collaborator and solves the problem that dependent code has no business managing the lifetime of its dependencies and shouldn’t know how to create them or dispose of them.

Despite the simplicity of what we’ve seen thus far, there’s a lot more complexity that surrounds dependency injection.

Injection of dependencies can come in many forms. Constructor Injection is what we have been using here since dependencies are injected into a constructor. There also exists Setter Injection and Interface Injection. In the case of the former, the dependent component will expose a setter method which will be used to inject the dependency - that is, it could expose a method like setUserRepository(userRepository: UserRepository). In the last case, we can define interfaces through which to perform the injection, but I’ll omit the explanation of the last technique here for brevity since we’ll spend more time discussing it and more in the second article of this series.

Because wiring up dependencies manually can be difficult, various IoC Frameworks and Containers exist. These containers store your dependencies and resolve the correct ones at runtime, often through Reflection in languages like C# or Java, exposing various configuration options for dependency lifetime. Despite the benefits that IoC Containers provide, there are cases to be made for moving away from them, and only resolving dependencies manually. To hear more about this, see Greg Young’s 8 Lines of Code talk.

Additionally, DI Frameworks and IoC Containers can provide too many options, and many rely on decorators or attributes to perform techniques such as setter or field injection. I look down on this kind of approach because, if you think about it intuitively, the point of dependency injection is to achieve loose coupling, but if you begin to sprinkle IoC Container-specific decorators all over your business logic, while you may have achieved decoupling from the dependency, you’ve inadvertently coupled yourself to the IoC Container. IoC Containers like Awilix solve this problem since they remain divorced from your application’s business logic.

Conclusion

This article served to depict only a very practical example of dependency injection in use and mostly neglected the theoretical attributes. I did it this way in order to make it easier to understand what dependency injection is at its core in a manner divorced from the rest of the complexity that people usually associate with the concept. In the second article of this series, we’ll take a much, much more in-depth look, including at:

• The difference between Dependency Injection and Dependency Inversion and Inversion of Control
• Dependency Injection anti-patterns
• IoC Container anti-patterns
• The role of IoC Containers
• The different types of dependency lifetimes
• How IoC Containers are designed
• Dependency Injection with React
• Advanced testing scenarios
• And more

This article was first written for Smashing Magazine on October 10th, 2020. You can find it here.

Introduction

In this article, we’ll be learning the concept of Generics in TypeScript and examining how Generics can be used to write modular, decoupled, and reusable code. Along the way, we’ll briefly discuss how they fit into better testing patterns, approaches to error handling, and domain/data-access separation.

A Real-World Example

I want to enter into the world of Generics not by explaining what they are, but rather by providing an intuitive example for why they are useful. Suppose you’ve been tasked with building a feature-rich dynamic list. You could call it an array, an ArrayList, a List, a std::vector, or whatever, depending upon your language background. Perhaps this data structure must have in-built or swappable buffer systems as well (like a circular buffer insertion option). It will be a wrapper around the normal JavaScript array so that we can work with our structure instead of plain arrays.

The immediate issue you’ll come across is that of constraints imposed by the type system. You can’t, at this point, accept any type you want into a function or method in a nice clean way (we’ll revisit this statement later).

The only obvious solution is to replicate our data structure for all different types:

const intList = IntegerList.create();
intList.add(4);

const stringList = StringList.create();
stringList.add('hello');

const userList = UserList.create();
userList.add(new User('Jamie'));

The .create() syntax here might look arbitrary, and indeed, new SomethingList() would be more straight-forward, but you’ll see why we use this static factory method later. Internally, the create method calls the constructor.

This is terrible. We have a lot of logic within this collection structure, and we’re blatantly duplicating it to support different use cases, completely breaking the DRY Principle in the process. When we decide to change our implementation, we’ll have to manually propagate/reflect those changes across all structures and types we support, including user-defined types, as in the latter example above. Suppose the collection structure itself was 100 lines long - it would be a nightmare to maintain multiple different implementations where the only difference between them is types.

An immediate solution that might come to mind, especially if you have an OOP mindset, is to consider a root “supertype”, if you will. In C#, for example, there consists a type by the name of object, and object is an alias for the System.Object class. In C#’s type system, all types, be they predefined or user-defined and be they reference types or value types, inherit either directly or indirectly from System.Object. This means that any value can be assigned to a variable of type object (without getting into stack/heap and boxing/unboxing semantics).

In this case, our issue appears solved. We can just use a type like any and that will allow us to store anything we want within our collection without having to duplicate the structure, and indeed, that’s very true:

const intList = AnyList.create();
intList.add(4);

const stringList = AnyList.create();
stringList.add('hello');

const userList = AnyList.create();
userList.add(new User('Jamie'));

Let’s look at the actual implementation of our list using any:

class AnyList {
    private values: any[] = [];

    private constructor (values: any[]) {
        this.values = values;

        // Some more construction work.
    }

    public add(value: any): void {
        this.values.push(value);
    }

    public where(predicate: (value: any) => boolean): AnyList {
        return AnyList.from(this.values.filter(predicate));
    }

    public select(selector: (value: any) => any): AnyList {
        return AnyList.from(this.values.map(selector));
    }

    public toArray(): any[] {
        return this.values;
    }

    public static from(values: any[]): AnyList {
        // Perhaps we perform some logic here.
        // ...
    
        return new AnyList(values);
    }

    public static create(values?: any[]): AnyList {
        return new AnyList(values ?? []);
    }

    // Other collection functions.
    // ...
}

All the methods are relatively simple, but we’ll start with the constructor. Its visibility is private, for we’ll assume that our list is complex and we wish to disallow arbitrary construction. We also may want to perform logic prior to construction, so for these reasons, and to keep the constructor pure, we delegate these concerns to static factory/helper methods, which is considered a good practice.

The static methods from and create are provided. The method from accepts an array of values, performs custom logic, and then uses them to construct the list. The create static method takes an optional array of values for in the event that we want to seed our list with initial data. The “nullish coalescing operator” (??) is used to construct the list with an empty array in the event that one is not provided. If the left side of the operand is null or undefined, we’ll fall back to the right side, for in this case, values is optional, and thus may be undefined. You can learn more about nullish coalescing at the relevant TypeScript documentation page.

I’ve also added a select and a where method. These methods just wrap JavaScript’s map and filter respectively. select permits us to project an array of elements into a new form based on the provided selector function, and where permits us to filter out certain elements based on the provided predicate function. The toArray method simply converts the list to an array by returning the array reference we hold internally.

Finally, suppose that the User class contains a getName method which returns a name and also accepts a name as its first and only constructor argument.

Note: Some readers will recognize Where and Select from C#’s LINQ, but keep in mind, I’m trying to keep this simple, thus I’m not worried about laziness or deferred execution. Those are optimizations that could and should be made in real life.

Further, as an interesting note, I want to discuss the meaning of “predicate”. In Discrete Mathematics and Propositional Logic, we have the concept of a “proposition”. A proposition is some statement that can be considered true or false, such as “four is divisible by two”. A “predicate” is a proposition that contains one or more variables, thus the truthfulness of the proposition depends upon that of those variables. You can think about it like a function, such as P(x) = x is divisible by two, for we need to know the value of x to determine if the statement is true or false. You can learn more about predicate logic here.

There are a few issues that are going to arise from the use of any. The TypeScript compiler knows nothing about the elements inside the list/internal array, thus it won’t provide any help inside of where or select or when adding elements:

// Providing seed data.
const userList = AnyList.create([new User('Jamie')]);

// This is fine and expected.
userList.add(new User('Tom'));
userList.add(new User('Alice'));

// This is an acceptable input to the TS Compiler,
// but it's not what we want. We'll definitely
// be surprised later to find strings in a list
// of users.
userList.add('Hello, World!');

// Also acceptable. We have a large tuple
// at this point rather than a homogeneous array.
userList.add(0);

// This compiles just fine despite the spelling mistake (extra 's'):
// The type of `users` is any.
const users = userList.where(user => user.getNames() === 'Jamie');

// Property `ssn` doesn't even exist on a `user`, yet it compiles.
users.toArray()[0].ssn = '000000000';

// `usersWithId` is, again, just `any`.
const usersWithId = userList.select(user => ({
    id: newUuid(),
    name: user.getName()
}));

// Oops, it's "id" not "ID", but TS doesn't help us. 
// We compile just fine.
console.log(usersWithId.toArray()[0].ID);

Since TypeScript only knows that the type of all array elements is any, it can’t help us at compile time with the non-existent properties or the getNames function that doesn’t even exist, thus this code will result in multiple unexpected runtime errors.

To be honest, things are beginning to look quite dismal. We tried implementing our data structure for each concrete type we wished to support, but we quickly realized that that was not in any way maintainable. Then, we thought we were getting somewhere by using any, which is analogous to depending upon a root supertype in an inheritance chain from which all types derive, but we concluded that we lose type-safety with that method. What’s the solution, then?

It turns out that, at the beginning of the article, I lied (kind of):

“You can’t, at this point, accept any type you want into a function or method in a nice clean way.”

You actually can, and that’s where Generics come in. Notice I said “at this point”, for I was assuming we didn’t know about Generics at that point in the article.

I’ll start by showing the full implementation of our List structure with Generics, and then we’ll take a step back, discuss what they actually are, and determine their syntax more formally. I’ve named it TypedList to differentiate from our earlier AnyList:

class TypedList<T> {
    private values: T[] = [];

    private constructor (values: T[]) {
        this.values = values;
    }

    public add(value: T): void {
        this.values.push(value);
    }

    public where(predicate: (value: T) => boolean): TypedList<T> {
        return TypedList.from<T>(this.values.filter(predicate));
    }

    public select<U>(selector: (value: T) => U): TypedList<U> {
        return TypedList.from<U>(this.values.map(selector));
    }

    public toArray(): T[] {
        return this.values;
    }

    public static from<U>(values: U[]): TypedList<U> {
        // Perhaps we perform some logic here.
        // ...
    
        return new TypedList<U>(values);
    }

    public static create<U>(values?: U[]): TypedList<U> {
        return new TypedList<U>(values ?? []);
    }

    // Other collection functions.
    // ..
}

Let’s try making the same mistakes as earlier once again:

// Here's the magic. `TypedList` will operate on objects
// of type `User` due to the `<User>` syntax.
const userList = TypedList.create<User>([new User('Jamie')]);

// The compiler expects this.
userList.add(new User('Tom'));
userList.add(new User('Alice'));

// Argument of type '0' is not assignable to parameter 
// of type 'User'. ts(2345)
userList.add(0);

// Property 'getNames' does not exist on type 'User'. 
// Did you mean 'getName'? ts(2551)
// Note: TypeScript infers the type of `users` to be
// `TypedList<User>`
const users = userList.where(user => user.getNames() === 'Jamie');

// Property 'ssn' does not exist on type 'User'. ts(2339)
users.toArray()[0].ssn = '000000000';

// TypeScript infers `usersWithId` to be of type
// `TypedList<{ id: string, name: string }>
const usersWithId = userList.select(user => ({
    id: newUuid(),
    name: user.getName()
}));

// Property 'ID' does not exist on type '{ id: string; name: string; }'. 
// Did you mean 'id'? ts(2551)
console.log(usersWithId.toArray()[0].ID)

As you can see, the TypeScript compiler is actively aiding us with type-safety. All of those comments are errors I receive from the compiler when attempting to compile this code. Generics have permitted us to specify a type that we wish to permit our list to operate on, and from that, TypeScript can tell the types of everything, all the way down to the properties of individual objects within the array.

The types we provide can be as simple or complex as we want them to be. Here, you can see we can pass both primitives and complex interfaces. We could also pass other arrays, or classes, or anything:

const numberList = TypedList.create<number>();
numberList.add(4);

const stringList = TypedList.create<string>();
stringList.add('Hello, World!');

// Example of a complex type
interface IAircraft {
    apuStatus: ApuStatus;
    inboardOneRPM: number;
    altimeter: number;
    tcasAlert: boolean;

    pushBackAndStart(): Promise<void>;
    ilsCaptureGlidescope(): boolean;
    getFuelStats(): IFuelStats;
    getTCASHistory(): ITCASHistory;
}

const aircraftList = TypedList.create<IAircraft>();
aircraftList.add(/* ... */);

// Aggregate and generate report:
const stats = aircraftList.select(a => ({
    ...a.getFuelStats(),
    ...a.getTCASHistory()
}));

The peculiar uses of T and U and <T> and <U> in the TypedList<T> implementation are examples of Generics in action. Having fulfilled our directive of constructing a type-safe collection structure, we’ll leave this example behind for now, and we’ll return to it once we understand what Generics actually are, how they work, and their syntax. When I’m learning a new concept, I always like to begin by seeing a complex example of the concept in use, so that when I start learning the basics, I can make connections between the basic topics and the existing example I have in my head.

What are Generics?

A simple manner by which to understand Generics is to consider them as relatively analogous to placeholders or variables but for types. That’s not to say that you can perform the same operations upon a generic type placeholder as you can a variable, but a generic type variable could be thought of as some placeholder that represents a concrete type that will be used in the future. That is, using Generics is a method of writing programs in terms of types that are to be specified at a later point in time. The reason why this is useful is because it allows us to build data structures that are reusable across the different types they operate upon (or type-agnostic).

That’s not particularly the best of explanations, so to put it in more simple terms, as we’ve seen, it is common in programming that we might need to build a function/class/data structure that will operate upon a certain type, but it is equally common that such a data structure needs to work across a variety of different types as well. If we were stuck in a position where we had to statically declare the concrete type upon which a data structure would operate at the time when we design the data structure (at compile time), we’d very quickly find that we need to rebuild those structures in an almost-exactly-the-same-manner for every type we wish to support, as we saw in the examples above.

Generics help us to solve this problem by permitting us to defer the requirement for a concrete type until it is actually known.

Generics in TypeScript

We now have somewhat of an organic idea for why Generics are useful and we’ve seen a slightly complicated example of them in practice. For most, the TypedList<T> implementation probably already makes a lot of sense, especially if you come from a statically-typed language background, but I can remember having a difficult time understanding the concept when I was first learning, thus I want to build up to that example by starting with simple functions. Concepts related to abstraction in software can be notoriously difficult to internalize, so if the notion of Generics has not quite clicked yet, that’s completely fine, and hopefully, by this article’s closing, the idea will be at least somewhat intuitive.

To build up to being able to understand that example, let’s work up from simple functions. We’ll start with the “Identity Function”, which is what most articles, including the TypeScript documentation itself, like to use.

An “Identity Function”, in mathematics, is a function that maps its input directly to its output, such as f(x) = x. What you put in is what you get out. We can represent that, in JavaScript, as:

function identity(input) {
    return input;
}

Or, more tersely:

const identity = input => input;

Trying to port this to TypeScript brings back the same type system issues we saw before. The solutions are typing with any, which we know is seldom a good idea, duplicating/overloading the function for each type (breaks DRY), or using Generics.

With the latter option, we can represent the function as follows:

// ES5 Function
function identity<T>(input: T): T {
    return input;
}

// Arrow Function
const identity = <T>(input: T): T => input;

console.log(identity<number>(5));       // 5
console.log(identity<string>('hello')); // hello

The <T> syntax here declares this function as Generic. Just like a function allows us to pass an arbitrary input parameter into its argument list, with a Generic function, we can pass an arbitrary type parameter as well.

The <T> part of the signature of identity<T>(input: T): T and <T>(input: T): T in both cases declares that the function in question will accept one generic type parameter named T. Just like how variables can be of any name, so can our Generic placeholders, but it’s a convention to use a capital letter “T” (“T” for “Type”) and to move down the alphabet as needed. Remember, T is a type, so we also state that we will accept one function argument of name input with a type of T and that our function will return a type of T. That’s all the signature is saying. Try letting T = string in your head - replace all the Ts with string in those signatures. See how nothing all that magical is going on? See how similar it is to the non-generic way you use functions every day?

Keep in mind what you already know about TypeScript and function signatures. All we’re saying is that T is an arbitrary type that the user will provide when calling the function, just like input is an arbitrary value that the user will provide when calling the function. In this case, input must be whatever that type T is when the function is called in the future.

Next, in the “future”, in the two log statements, we “pass in” the concrete type we wish to use, just like we do a variable. Notice the switch in verbiage here - in the initial form of <T> signature, when declaring our function, it is generic - that is, it works on generic types, or types to be specified later. That’s because we don’t know what type the caller will wish to use when we actually write the function. But, when the caller calls the function, he/she knows exactly what type(s) they want to work with, which are string and number in this case.

You can imagine the idea of having a log function declared this way in a third-party library - the library author has no idea what types the developers who use the lib will want to use, so they make the function generic, essentially deferring the need for concrete types until they are actually known.

I want to stress that you should think of this process in a similar fashion that you do the notion of passing a variable to a function for the purposes of gaining a more intuitive understanding. All we’re doing now is passing a type too.

At the point where we called the function with the number parameter, the original signature, for all intents and purposes, could be thought of as identity(input: number): number. And, at the point where we called the function with the string parameter, again, the original signature might just as well have been identity(input: string): string. You can imagine that, when making the call, every generic T gets replaced with the concrete type you provide at that moment.

Exploring Generic Syntax

There are different syntaxes and semantics for specifying generics in the context of ES5 Functions, Arrow Functions, Type Aliases, Interfaces, and Classes. We’ll explore those differences in this section.

Exploring Generic Syntax - Functions

You’ve seen a few examples of generic functions by now, but it’s important to note that a generic function can accept more than one generic type parameter, just like it can variables. You could choose to ask for one, or two, or three, or however many types you want, all separated by commas (again, just like input arguments).

This function accepts three input types and randomly returns one of them:

function randomValue<T, U, V>(
    one: T, 
    two: U, 
    three: V
): T | U | V  {
    // This is a tuple if you're not familiar.
    const options: [T, U, V] = [
        one,
        two,
        three
    ];

    const rndNum = getRndNumInInclusiveRange(0, 2);

    return options[rndNum];
}

// Calling the function.
// `value` has type `string | number | IAircraft`
const value = randomValue<
    string,
    number,
    IAircraft
>(
    myString,
    myNumber,
    myAircraft
);

You can also see that the syntax is slightly different depending on whether we use an ES5 Function or an Arrow Function, but both declare the type parameters in the signature:

const randomValue = <T, U, V>(
    one: T, 
    two: U, 
    three: V
): T | U | V => {
    // This is a tuple if you're not familiar.
    const options: [T, U, V] = [
        one,
        two,
        three
    ];

    const rndNum = getRndNumInInclusiveRange(0, 2);

    return options[rndNum];
}

Keep in mind that there is no “uniqueness constraint” forced on the types - you could pass in any combination you wish, such as two strings and a number, for instance. Additionally, just like the input arguments are “in scope” for the body of the function, so are the generic type parameters. The former example demonstrates that we have full access to T, U, and V from within the body of the function, and we used them to declare a local 3-tuple.

You can imagine that these generics operate over a certain “context” or within a certain “lifetime”, and that depends on where they’re declared. Generics on functions are in scope within the function signature and body (and closures created by nested functions), while generics declared on a class or interface or type alias are in scope for all members of the class or interface or type alias.

The notion of generics on functions is not limited to “free functions” or “floating functions” (functions not attached to an object or class, a C++ term), but they can also be used on functions attached to other structures, too.

We can place that randomValue in a class and we can call it just the same:

class Utils {
    public randomValue<T, U, V>(
        one: T, 
        two: U, 
        three: V
    ): T | U | V {
        // ...
    }

    // Or, as an arrow function:
    public randomValue = <T, U, V>(
        one: T, 
        two: U, 
        three: V
    ): T | U | V => {
        // ...
    }
}

We could also place a definition within an interface:

interface IUtils {
    randomValue<T, U, V>(
        one: T,
        two: U,
        three: V
    ): T | U | V;
}

Or within a type alias:

type Utils = {
    randomValue<T, U, V>(
        one: T,
        two: U,
        three: V
    ): T | U | V;
}

Just like before, these generic type parameters are “in scope” for that particular function - they are not class, or interface, or type alias-wide. They live only within the particular function upon which they’re specified. To share a generic type across all members of a structure, you must annotate the structure’s name itself, as we’ll see below.

Exploring Generic Syntax - Type Aliases

With Type Aliases, the generic syntax is used on the alias’s name.

For instance, some “action” function that accepts a value, possibly mutates that value, but returns void could be written as:

type Action<T> = (val: T) => void;

This should be familiar to C# developers who understand the Action delegate.

Or, a callback function that accepts both an error and a value could be declared as such:

type CallbackFunction<T> = (err: Error, data: T) => void;

const usersApi = {
    get(uri: string, cb: CallbackFunction<User>) {
        /// ...
    }
}

With our knowledge of function generics, we could go further and make the function on the API object generic too:

type CallbackFunction<T> = (err: Error, data: T) => void;

const api = {
    // `T` is available for use within this function.
    get<T>(uri: string, cb: CallbackFunction<T>) {
        /// ...
    }
}

Now, we’re saying that the get function accepts some generic type parameter, and whatever that is, CallbackFunction receives it. We’ve essentially “passed” the T that goes into get as the T for CallbackFunction. Perhaps this would make more sense if we change the names:

type CallbackFunction<TData> = (err: Error, data: TData) => void;

const api = {
    get<TResponse>(uri: string, cb: CallbackFunction<TResponse>) {
        // ...
    }
}

Prefixing type params with T is merely a convention, just like prefixing interfaces with I or member variables with _. What you can see here is that CallbackFunction accepts some type (TData) which represents the data payload available to the function, while get accepts a type parameter that represents the HTTP Response data type/shape (TResponse). The HTTP Client (api), similar to Axios, uses whatever that TResponse is as the TData for CallbackFunction. This allows the API caller to select the data type they’ll be receiving back from the API (suppose somewhere else in the pipeline we have middleware that parses the JSON into a DTO).

If we wanted to take this a little further, we could modify the generic type parameters on CallbackFunction to accept a custom error type as well:

type CallbackFunction<TData, TError> = (err: TError, data: TData) => void;

And, just like you can make function arguments optional, you can with type parameters too. In the event that the user does not provide an error type, we’ll set it to the error constructor by default:

type CallbackFunction<TData, TError = Error> = (err: TError, data: TData) => void;

With this, we can now specify a callback function type in multiple ways:

const apiOne = {
    // `Error` is used by default for `CallbackFunction`.
    get<TResponse>(uri: string, cb: CallbackFunction<TResponse>) {
        // ...
    }
};

apiOne.get<string>('uri', (err: Error, data: string) => {
    // ...
});

const apiTwo = {
    // Override the default and use `HttpError` instead.
    get<TResponse>(uri: string, cb: CallbackFunction<TResponse, HttpError>) {
        // ...
    }
};

apiTwo.get<string>('uri', (err: HttpError, data: string) => {
    // ...
});

This idea of default parameters is acceptable across functions, classes, interfaces, etc. - it’s not just limited to type aliases. In all the examples we’ve seen so far, we could have assigned any type parameter we wanted to a default value. Type Aliases, just like functions, can take as many generic type parameters as you wish.

Exploring Generic Syntax - Interfaces

As you’ve seen, a generic type parameter can be provided to a function on an interface:

interface IUselessFunctions {
    // Not generic
    printHelloWorld();

    // Generic
    identity<T>(t: T): T;
}

In this case, T lives only for the identity function as its input and return type.

We can also make a type parameter available to all members of an interface, just like with classes and type aliases, by specifying that the interface itself accepts a generic. We’ll talk about the Repository Pattern a little later when we discuss more complex use cases for generics, so it’s alright if you’ve never heard of it. The Repository Pattern permits us to abstract away our data storage as to make business logic persistence-agnostic. If you wished to create a generic repository interface that operated on unknown entity types, we could type it as follows:

interface IRepository<T> {
    add(entity: T): Promise<void>;
    findById(id: string): Promise<T>;
    updateById(id: string, updated: T): Promise<void>;
    removeById(id: string): Promise<void>;
}

There are many different thoughts around Repositories, from Martin Fowler’s definition to the DDD Aggregate definition. I’m merely attempting to show a use case for generics, so I’m not too concerned with being fully correct implementation-wise. There’s definitely something to be said for not using generic repositories, but we’ll talk about that later.

As you can see here, IRepository is an interface that contains methods for storing and retrieving data. It operates on some generic type parameter named T, and T is used as input to add and updateById, as well as the promise resolution result of findById.

Keep in mind that there’s a very big difference between accepting a generic type parameter on the interface name as opposed to allowing each function itself to accept a generic type parameter. The former, as we’ve done here, ensures that each function within the interface operates on the same type T. That is, for an IRepository<User>, every method that uses T in the interface is now working on User objects. With the latter method, each function would be allowed to work with whatever type it wants. It would be very peculiar to only be able to add Users to the Repository but be able to receive Policies or Orders back, for instance, which is the potential situation we’d find ourselves in if we couldn’t enforce that the type is uniform across all methods.

A given interface can contain not only a shared type, but also types unique to its members. For instance, if we wanted to mimic an array, we could type an interface like this:

interface IArray<T> {
    forEach(func: (elem: T, index: number) => void): this;
    map<U>(func: (elem: T, index: number) => U): IArray<U>;
}

In this case, both forEach and map have access to T from the interface name. As stated, you can imagine that T is in scope for all members of the interface. Despite that, nothing stops individual functions within from accepting their own type parameters as well. The map function does, with U. Now, map has access to both T and U. We had to name the parameter a different letter, like U, because T is already taken and we don’t want a naming collision. Quite like its name, map will “map” elements of type T within the array to new elements of type U. It maps Ts to Us. The return value of this function is the interface itself, now operating on the new type U, so that we can somewhat mimic JavaScript’s fluent chainable syntax for arrays.

We’ll see an example of the power of Generics and Interfaces shortly when we implement the Repository Pattern and discuss Dependency Injection. Once again, we can accept as many generic parameters as well as select one or more default parameters stacked at the end of an interface.

Exploring Generic Syntax - Classes

Much the same as we can pass a generic type parameter to a type alias, function, or interface, we can pass one or more to a class as well. Upon doing so, that type parameter will be accessible to all members of that class as well as extended base classes or implemented interfaces.

Let’s build another collection class, but a little simpler than TypedList above, so that we can see the interop between generic types, interfaces, and members. We’ll see an example of passing a type to a base class and interface inheritance a little later.

Our collection will merely support basic CRUD functions in addition to a map and forEach method.

class Collection<T> {
    private elements: T[] = [];

    constructor (elements: T[] = []) {
        this.elements = elements;
    }
	
	add(elem: T): void {
		this.elements.push(elem);
	}
	
	contains(elem: T): boolean {
		return this.elements.includes(elem);
	}
	
	remove(elem: T): void {
		this.elements = this.elements.filter(existing => existing !== elem);
	}
	
	forEach(func: (elem: T, index: number) => void): void {
		return this.elements.forEach(func);
	}
	
	map<U>(func: (elem: T, index: number) => U): Collection<U> {
	    return new Collection<U>(this.elements.map(func));
	}
}

const stringCollection = new Collection<string>();
stringCollection.add('Hello, World!');

const numberCollection = new Collection<number>();
numberCollection.add(3.14159);

const aircraftCollection = new Collection<IAircraft>();
aircraftCollection.add(myAircraft);

Let’s discuss what’s going on here. The Collection class accepts one generic type parameter named T. That type becomes accessible to all members of the class. We use it to define a private array of type T[], which we could also have denoted in the form Array<T> (See? Generics again for normal TS array typing). Further, most member functions utilize that T in some way, such as by controlling the types that are added and removed or checking if the collection contains an element.

Finally, as we’ve seen before, the map method requires its own generic type parameter. We need to define in the signature of map that some type T is mapped to some type U through a callback function, thus we need a U. That U is unique to that function in particular, which means we could have another function in that class that also accepts some type named U, and that’d be fine, because those types are only “in scope” for their functions and not shared across them, thus there are no naming collisions. What we can’t do is have another function that accepts a generic parameter named T, for that’d conflict with the T from the class signature.

You can see that when we call the constructor, we pass in the type we want to work with (that is, what type each element of the internal array will be). In the calling code at the bottom of the example, we work with strings, numbers, and IAircrafts.

How could we make this work with an interface? What if we have different collection interfaces that we might want to swap out or inject into calling code? To get that level of reduced coupling (low coupling and high cohesion is what we should always aim for), we’ll need to depend on an abstraction. Generally, that abstraction will be an interface, but it could also be an abstract class.

Our collection interface will need to be generic, so let’s define it:

interface ICollection<T> {
    add(t: T): void;
    contains(t: T): boolean;
    remove(t: T): void;
    forEach(func: (elem: T, index: number) => void): void;
    map<U>(func: (elem: T, index: number) => U): ICollection<U>;
}

Now, let’s suppose we have different kinds of collections. We could have an in-memory collection, one that stores data on disk, one that uses a database, etc. By having an interface, the dependent code can depend upon the abstraction, permitting us to swap out different implementations without affecting the existing code. Here is the in-memory collection.

class InMemoryCollection<T> implements ICollection<T> {
    private elements: T[] = [];

    constructor (elements: T[] = []) {
        this.elements = elements;
    }
	
	add(elem: T): void {
		this.elements.push(elem);
	}
	
	contains(elem: T): boolean {
		return this.elements.includes(elem);
	}
	
	remove(elem: T): void {
		this.elements = this.elements.filter(existing => existing !== elem);
	}
	
	forEach(func: (elem: T, index: number) => void): void {
		return this.elements.forEach(func);
	}
	
	map<U>(func: (elem: T, index: number) => U): ICollection<U> {
	    return new InMemoryCollection<U>(this.elements.map(func));
	}
}

The interface describes the public-facing methods and properties that our class is required to implement, expecting you to pass in a concrete type that those methods will operate upon. However, at the time of defining the class, we still don’t know what type the API caller will wish to use. Thus, we make the class generic too - that is, InMemoryCollection expects to receive some generic type T, and whatever it is, it’s immediately passed to the interface, and the interface methods are implemented using that type.

Calling code can now depend on the interface:

// Using type annotation to be explicit for the purposes of the
// tutorial.
const userCollection: ICollection<User> = new InMemoryCollection<User>();

function manageUsers(userCollection: ICollection<User>) {
    userCollection.add(new User());
}

With this, any kind of collection can be passed into the manageUsers function as long as it satisfies the interface. This is useful for testing scenarios - rather than dealing with over-the-top mocking libraries, in unit and integration test scenarios, I can replace my SqlServerCollection<T> (for example) with InMemoryCollection<T> instead and perform state-based assertions instead of interaction-based assertions. This setup makes my tests agnostic to implementation details, which means they are, in turn, less likely to break when refactoring the SUT.

At this point, we should have worked up to the point where we can understand that first TypedList<T> example. Here it is again:

class TypedList<T> {
    private values: T[] = [];

    private constructor (values: T[]) {
        this.values = values;
    }

    public add(value: T): void {
        this.values.push(value);
    }

    public where(predicate: (value: T) => boolean): TypedList<T> {
        return TypedList.from<T>(this.values.filter(predicate));
    }

    public select<U>(selector: (value: T) => U): TypedList<U> {
        return TypedList.from<U>(this.values.map(selector));
    }

    public toArray(): T[] {
        return this.values;
    }

    public static from<U>(values: U[]): TypedList<U> {
        // Perhaps we perform some logic here.
        // ...
    
        return new TypedList<U>(values);
    }

    public static create<U>(values?: U[]): TypedList<U> {
        return new TypedList<U>(values ?? []);
    }

    // Other collection functions.
    // ..
}

The class itself accepts a generic type parameter named T, and all members of the class are provided access to it. The instance method select and the two static methods from and create, which are builders, accept their own generic type parameter named U.

The create static method permits the construction of a list with optional seed data. It accepts some type named U to be the type of every element in the list as well as an optional array of U elements, typed as U[]. When it calls the list’s constructor with new, it passes that type U as the generic parameter to TypedList. This creates a new list where the type of every element is U. It is exactly the same as how we could call the constructor of our collection class earlier with new Collection<SomeType>(). The only difference is that the generic type is now passing through the create method rather than being provided and used at the top-level.

I want to make sure this is really, really clear. I’ve stated a few times that we can think about passing around types in a similar way that we do variables. It should already be quite intuitive that we can pass a variable through as many layers of indirection as we please. Forget generics and types for a moment and think about an example of the form:

class MyClass {
    private constructor (t: number) {}
    
    public static create(u: number) {
        return new MyClass(u);
    }
}

const myClass = MyClass.create(2.17);

This is very similar to what is happening with the more-involved example, the difference being that we’re working on generic type parameters, not variables. Here, 2.17 becomes the u in create, which ultimately becomes the t in the private constructor.

In the case of generics:

class MyClass<T> {
    private constructor () {}
    
    public static create<U>() {
        return new MyClass<U>();
    }
}

const myClass = MyClass.create<number>();

The U passed to create is ultimately passed in as the T for MyClass<T>. When calling create, we provided number as U, thus now U = number. We put that U (which, again, is just number) into the T for MyClass<T>, so that MyClass<T> effectively becomes MyClass<number>. The benefit of generics is that we’re opened up to be able to work with types in this abstract and high-level fashion, similar to how we can normal variables.

The from method constructs a new list that operates on an array of elements of type U. It uses that type U, just like create, to construct a new instance of the TypedList class, now passing in that type U for T.

The where instance method performs a filtering operation based upon a predicate function. There’s no mapping happening, thus the types of all elements remain the same throughout. The filter method available on JavaScript’s array returns a new array of values, which we pass into the from method. So, to be clear, after we filter out the values that don’t satisfy the predicate function, we get an array back containing the elements that do. All those elements are still of type T, which is the original type that the caller passed to create when the list was first created. Those filtered elements get given to the from method, which in turn creates a new list containing all those values, still using that original type T. The reason why we return a new instance of the TypedList class is to be able to chain new method calls onto the return result. This adds an element of “immutability” to our list.

Hopefully, this all provides you with a more intuitive example of generics in practice, and their reason for existence. Next, we’ll look at a few of the more advanced topics.

Generic Type Inference

Throughout this article, in all cases where we’ve used generics, we’ve explicitly defined the type we’re operating on. It’s important to note that in most cases, we do not have to explicitly define the type parameter we pass in, for TypeScript can infer the type based on usage.

If I have some function that returns a random number, and I pass the return result of that function to identity from earlier without specifying the type parameter, it will be inferred automatically as number:

// `value` is inferred as type `number`.
const value = identity(getRandomNumber());

To demonstrate type inference, I’ve removed all the technically extraneous type annotations from our TypedList structure earlier, and you can see, from the pictures below, that TSC still infers all types correctly:

TypedList without extraneous type declarations:

class TypedList<T> {
    private values: T[] = [];

    private constructor (values: T[]) {
        this.values = values;
    }

    public add(value: T) {
        this.values.push(value);
    }

    public where(predicate: (value: T) => boolean) {
        return TypedList.from(this.values.filter(predicate));
    }

    public select<U>(selector: (value: T) => U) {
        return TypedList.from(this.values.map(selector));
    }

    public toArray() {
        return this.values;
    }

    public static from<U>(values: U[]) {
        // Perhaps we perform some logic here.
        // ...
    
        return new TypedList(values);
    }

    public static create<U>(values?: U[]) {
        return new TypedList(values ?? []);
    }

    // Other collection functions.
    // ..
}

Based on function return values and based on the input types passed into from and the constructor, TSC understands all type information. On the image below, I’ve stitched multiple images together which shows Visual Studio’s Code TypeScript’s Language Extension (and thus the compiler) inferring all the types:

Generic Constraints

Sometimes, we want to put a constraint around a generic type. Perhaps we can’t support every type in existence, but we can support a subset of them. Let’s say we want to build a function that returns the length of some collection. As seen above, we could have many different types of arrays/collections, from the default JavaScript Array to our custom ones. How do we let our function know that some generic type has a length property attached to it? Similarly, how do restrict the concrete types we pass into the function to those that contain the data we need? An example such as this one, for instance, would not work:

function getLength<T>(collection: T): number {
    // Error. TS does not know that a type T contains a `length` property.
    return collection.length;
}

The answer is to utilize Generic Constraints. We can define an interface that describes the properties we need:

interface IHasLength {
    length: number;
}

Now, when defining our generic function, we can constrain the generic type to be one that extends that interface:

function getLength<T extends IHasLength>(collection: T): number {
    // Restricting `collection` to be a type that contains
    // everything within the `IHasLength` interface.
    return collection.length;
}

Real-World Examples

In the next couple of sections, we’ll discuss some real-world examples of generics that create more elegant and easy-to-reason-about code. We’ve seen a lot of trivial examples, but I want to discuss some approaches to error handling, data access patterns, and front-end React state/props.

Real-World Examples - Approaches to Error Handling

JavaScript contains a first-class mechanism for handling errors, as do most programming languages - try/catch. Despite that, I’m not a very big fan of how it looks when used. That’s not to say I don’t use the mechanism, I do, but I tend to try and hide it as much as I can. By abstracting try/catch away, I can also reuse error handling logic across likely-to-fail operations.

Suppose we’re building some Data Access Layer. This is a layer of the application that wraps the persistence logic for dealing with the data storage method. If we’re performing database operations, and if that database is used across a network, particular DB-specific errors and transient exceptions are likely to occur. Part of the reason for having a dedicated Data Access Layer is to abstract away the database from the business logic. Due to that, we can’t be having such DB-specific errors being thrown up the stack and out of this layer. We need to wrap them first.

Let’s look at a typical implementation that would use try/catch:

async function queryUser(userID: string): Promise<User> {
    try {
        const dbUser = await db.raw(`
            SELECT * FROM users WHERE user_id = ?
        `, [userID]);
        
        return mapper.toDomain(dbUser);
    } catch (e) {
        switch (true) {
            case e instanceof DbErrorOne:
                return Promise.reject(new WrapperErrorOne());
            case e instanceof DbErrorTwo:
                return Promise.reject(new WrapperErrorTwo());
            case e instanceof NetworkError:
                return Promise.reject(new TransientException());
            default:
                return Promise.reject(new UnknownError());
        }
    }
}

Switching over true is just a trick to be able to use the switch case statements for my error checking logic as opposed to having to declare a chain of if/else if.

If we have multiple such functions, we have to replicate this error-wrapping logic, which is a very bad practice. It looks quite good for one function, but it’ll be a nightmare with many. To abstract away this logic, we can wrap it in a custom error handling function that will pass through the result, but catch and wrap any errors should they be thrown:

async function withErrorHandling<T>(
    dalOperation: () => Promise<T>
): Promise<T> {
    try {
        // This unwraps the promise and returns the type `T`.
        return await dalOperation();
    } catch (e) {
        switch (true) {
            case e instanceof DbErrorOne:
                return Promise.reject(new WrapperErrorOne());
            case e instanceof DbErrorTwo:
                return Promise.reject(new WrapperErrorTwo());
            case e instanceof NetworkError:
                return Promise.reject(new TransientException());
            default:
                return Promise.reject(new UnknownError());
        }
    }
}

To ensure this makes sense, we have a function entitled withErrorHandling that accepts some generic type parameter T. This T represents the type of the successful resolution value of the promise we expect returned from the dalOperation callback function. Usually, since we’re just returning the return result of the async dalOperation function, we wouldn’t need to await it for that would wrap the function in a second extraneous promise, and we could leave the awaiting to the calling code. In this case, we need to catch any errors, thus await is required.

We can now use this function to wrap our DAL operations from earlier:

async function queryUser(userID: string) {
    return withErrorHandling<User>(async () => {
        const dbUser = await db.raw(`
            SELECT * FROM users WHERE user_id = ?
        `, [userID]);
        
        return mapper.toDomain(dbUser);
    });
}

And there we go. We have a type-safe and error-safe function user query function.

Additionally, as you saw earlier, if the TypeScript Compiler has enough information to infer the types implicitly, you don’t have to explicitly pass them. In this case, TSC knows that the return result of the function is what the generic type is. Thus, if mapper.toDomain(user) returned a type of User, you wouldn’t need to pass the type in at all:

async function queryUser(userID: string) {
    return withErrorHandling(async () => {
        const dbUser = await db.raw(`
            SELECT * FROM users WHERE user_id = ?
        `, [userID]);
        
        return mapper.toDomain(user);
    });
}

Another approach to error handling that I tend to like is that of Monadic Types. The Either Monad is an algebraic data type of the form Either<T, U>, where T can represent an error type, and U can represent a failure type. Using Monadic Types hearkens to functional programming, and a major benefit is that errors become type-safe - a normal function signature doesn’t tell the API caller anything about what errors that function might throw. Suppose we throw a NotFound error from inside queryUser. A signature of queryUser(userID: string): Promise<User> doesn’t tell us anything about that. But, a signature like queryUser(userID: string): Promise<Either<NotFound, User>> absolutely does. I won’t explain how monads like the Either Monad work in this article because they can be quite complex, and there are a variety of methods they must have to be considered monadic, such as mapping/binding. If you’d like to learn more about them, I’d recommend two of Scott Wlaschin’s NDC talks, here and here, as well as Daniel Chamber’s talk here. This site as well these blog posts may be useful too.

Real-World Examples - Repository Pattern

Let’s take a look at another use case where Generics might be helpful. Most back-end systems are required to interface with a database in some manner - this could be a relational database like PostgreSQL, a document database like MongoDB, or perhaps even a graph database, such as Neo4j.

Since, as developers, we should aim for lowly coupled and highly cohesive designs, it would be a fair argument to consider what the ramifications of migrating database systems might be. It would also be fair to consider that different data access needs might prefer different data access approaches (this starts to get into CQRS a little bit, which is a pattern for separating reads and writes. See Martin Fowler’s post and the MSDN listing if you wish to learn more. The books “Implementing Domain Driven Design” by Vaughn Vernon and “Patterns, Principles, and Practices of Domain-Driven Design” by Scott Millet are good reads as well). We should also consider automated testing. The majority of tutorials that explain the building of back-end systems with Node.js intermingle data access code with business logic with routing. That is, they tend to use MongoDB with the Mongoose ODM, taking an Active Record approach, and not having a clean separation of concerns. Such techniques are frowned upon in large applications, for the moment you decide you’d like to migrate one database system for another, or the moment you realize that you’d prefer a different approach to data access, etc., you have to rip out that old data access code, replace it with new code, and hope you didn’t introduce any bugs to routing and business logic along the way.

Sure, you might argue that unit and integration tests will prevent regressions, but if those tests find themselves coupled and dependent upon implementation details to which they should be agnostic, they too will likely break in the process.

A common approach to solve this issue is the Repository Pattern. It says that to calling code, we should allow our data access layer to mimic a mere in-memory collection of objects or domain entities. In this way, we can let the business drive the design rather than the database (data model). For large applications, an architectural pattern called Domain-Driven Design becomes useful. Repositories, in the Repository Pattern, are components, most commonly classes, that encapsulate and hold internal all the logic to access data sources. With this, we can centralize data access code to one layer, making it easily testable and easily reusable. Further, we can place a mapping layer in between, permitting us to map database-agnostic domain models to a series of one-to-one table mappings. Each function available on the Repository could optionally use a different data access method if you so choose.

There are many different approaches and semantics to Repositories, Units of Work, database transactions across tables, etc. Since this is an article about Generics, I don’t want to get into the weeds too much, thus I’ll illustrate a simple example here, but it’s important to note that different applications have different needs. A Repository for DDD Aggregates would be quite different than what we’re doing here, for instance. How I portray the Repository implementations here is not how I implement them in real projects, for there is a lot of missing functionality and less-than-desired architectural practices in use.

Let’s suppose we have Users and Tasks as domain models. These could just be POTOs - Plain-Old TypeScript Objects. There is no notion of a database baked into them, thus, you wouldn’t call User.save(), for instance, as you would using Mongoose. Using the Repository Pattern, we might persist a user or delete a task from our business logic as follows:

// Querying the DB for a User by their ID.
const user: User = await userRepository.findById(userID);

// Deleting a Task by its ID.
await taskRepository.deleteById(taskID);

// Deleting a Task by its owner's ID.
await taskRepository.deleteByUserId(userID);

Clearly, you can see how all the messy and transient data access logic is hidden behind this repository facade/abstraction, making business logic agnostic to persistence concerns.

Let’s start by building a few simple domain models. These are the models that the application code will interact with. They are anemic here but would hold their own logic to satisfy business invariants in the real-world, that is, they wouldn’t be mere data bags.

interface IHasIdentity {
    id: string;
}

class User implements IHasIdentity {
    public constructor (
        private readonly _id: string,
        private readonly _username: string
    ) {}

    public get id() { return this._id; }
    public get username() { return this._username; }
}

class Task implements IHasIdentity {
    public constructor (
        private readonly _id: string,
        private readonly _title: string
    ) {}

    public get id() { return this._id; }
    public get title() { return this._title; }
}

You’ll see in a moment why we extract identity typing information to an interface. This method of defining domain models and passing everything through the constructor is not how I’d do it in the real world. Additionally, relying on an abstract domain model class would have been more preferable than the interface to get the id implementation for free.

For the Repository, since, in this case, we expect that many of the same persistence mechanisms will be shared across different domain models, we can abstract our Repository methods to a generic interface:

interface IRepository<T> {
    add(entity: T): Promise<void>;
    findById(id: string): Promise<T>;
    updateById(id: string, updated: T): Promise<void>;
    deleteById(id: string): Promise<void>;
    existsById(id: string): Promise<boolean>;
}

We could go further and create a Generic Repository too to reduce duplication. For brevity, I won’t do that here, and I should note that Generic Repository interfaces such as this one and Generic Repositories, in general, tend to be frowned upon, for you might have certain entities which are read-only, or write-only, or which can’t be deleted, etc. It depends on the application. Also, we don’t have a notion of a “unit of work” in order to share a transaction across tables, a feature I would implement in the real world, but, again, since this is a small demo, I don’t want to get too technical.

Let’s start by implementing our UserRepository. I’ll define an IUserRepository interface which holds methods specific to users, thus permitting calling code to depend on that abstraction when we dependency inject the concrete implementations:

interface IUserRepository extends IRepository<User> {
    existsByUsername(username: string): Promise<boolean>;
}

class UserRepository implements IUserRepository {
    // There are 6 methods to implement here all using the 
    // concrete type of `User` - Five from IRepository<User>
    // and the one above.
}

The Task Repository would be similar but would contain different methods as the application sees fit.

Here, we’re defining an interface that extends a generic one, thus we have to pass the concrete type we’re working on. As you can see from both interfaces, we have the notion that we send these POTO domain models in and we get them out. The calling code has no idea what the underlying persistence mechanism is, and that’s the point.

The next consideration to make is that depending on the data access method we choose, we’ll have to handle database-specific errors. We could place Mongoose or the Knex Query Builder behind this Repository, for example, and in that case, we’ll have to handle those specific errors - we don’t want them to bubble up to business logic for that would break separation of concerns and introduce a larger degree of coupling.

Let’s define a Base Repository for the data access methods we wish to use that can handle errors for us:

class BaseKnexRepository {
    // A constructor.
    
     /**
     * Wraps a likely to fail database operation within a function that handles errors by catching
     * them and wrapping them in a domain-safe error.
     * 
     * @param dalOp The operation to perform upon the database. 
     */
    public async withErrorHandling<T>(dalOp: () => Promise<T>) {
        try {
            return await dalOp();
        } catch (e) {
            // Use a proper logger:
            console.error(e);
            
            // Handle errors properly here.
        }
    }
}

Now, we can extend this Base Class in the Repository and access that Generic method:

interface IUserRepository extends IRepository<User> {
    existsByUsername(username: string): Promise<boolean>;
}

class UserRepository extends BaseKnexRepository implements IUserRepository {
    private readonly dbContext: Knex | Knex.Transaction;
    
    public constructor (private knexInstance: Knex | Knex.Transaction) {
        super();
        this.dbContext = knexInstance;
    }
    
    // Example `findById` implementation:
    public async findById(id: string): Promise<User> {
        return this.withErrorHandling<User>(async () => {
            const dbUser = await this.dbContext<DbUser>()
                .select()
                .where({ user_id: id })
                .first();
                
            // Maps type DbUser to User    
            return mapper.toDomain(dbUser);
        });
    }
    
    // There are 5 methods to implement here all using the 
    // concrete type of `User`.
}

Notice that our function retrieves a DbUser from the database and maps it to a User domain model before returning it. This is the Data Mapper pattern and it’s crucial to maintaining separation of concerns. DbUser is a one-to-one mapping to the database table - it’s the data model that the Repository operates upon - and is thus highly dependent on the data storage technology used. For this reason, DbUsers will never leave the Repository and will be mapped to a User domain model before being returned. I didn’t show the DbUser implementation, but it could just be a simple class or interface.

Thus far, using the Repository Pattern, powered by Generics, we’ve managed to abstract away data access concerns into small units as well as maintain type-safety and re-usability.

Finally, for the purposes of Unit and Integration Testing, let’s say that we’ll keep an in-memory repository implementation so that in a test environment, we can inject that repository, and perform state-based assertions on disk rather than mocking with a mocking framework. This method forces everything to rely on the public-facing interfaces rather than permitting tests to be coupled to implementation details. Since the only differences between each repository are the methods they choose to add under the ISomethingRepository interface, we can build a generic in-memory repository and extend that within type-specific implementations:

class InMemoryRepository<T extends IHasIdentity> implements IRepository<T> {
    protected entities: T[] = [];
    
    public findById(id: string): Promise<T> {
        const entityOrNone = this.entities.find(entity => entity.id === id);

        return entityOrNone 
            ? Promise.resolve(entityOrNone)
            : Promise.reject(new NotFound());
    }
    
    // Implement the rest of the IRepository<T> methods here.
}

The purpose of this base class is to perform all the logic for handling in-memory storage so that we don’t have to duplicate it within in-memory test repositories. Due to methods like findById, this repository has to have an understanding that entities contain an id field, which is why the generic constraint on the IHasIdentity interface is necessary. We saw this interface before - it’s what our domain models implemented.

With this, when it comes to building the in-memory user or task repository, we can just extend this class and get most of the methods implemented automatically:

class InMemoryUserRepository extends InMemoryRepository<User> {
    public async existsByUsername(username: string): Promise<boolean> {
        const userOrNone = this.entities.find(entity => entity.username === username);
        return Boolean(userOrNone);

        // or, return !!userOrNone;
    }
    
    // And that's it here. InMemoryRepository implements the rest.
}

Here, our InMemoryRepository needs to know that entities have fields such as id and username, thus we pass User as the generic parameter. User already implements IHasIdentity, so the generic constraint is satisfied, and we also state that we have a username property too.

Now, when we wish to use these repositories from the Business Logic Layer, it’s quite simple:

class UserService {
    public constructor (
        private readonly userRepository: IUserRepository,
        private readonly emailService: IEmailService
    ) {}

    public async createUser(dto: ICreateUserDTO) {
        // Validate the DTO:
        // ...
        
        // Create a User Domain Model from the DTO
        const user = userFactory(dto);

        // Persist the Entity
        await this.userRepository.add(user);
 
        // Send a welcome email
        await this.emailService.sendWelcomeEmail(user);
    }
}

(Note that in a real application, we’d probably move the call to emailService to a job queue as to not add latency to the request and in the hopes of being able to perform idempotent retries on failures (- not that email sending is particularly idempotent in the first place). Further, passing the whole user object to the service is questionable too. The other issue to note is that we could find ourselves in a position here where the server crashes after the user is persisted but before the email is sent. There are mitigation patterns to prevent this, but for the purposes of pragmatism, human intervention with proper logging will probably work just fine).

And there we go - using the Repository Pattern with the power of Generics, we’ve completely decoupled our DAL from our BLL and have managed to interface with our repository in a type-safe manner. We’ve also developed a way to rapidly construct equally type-safe in-memory repositories for the purposes of unit and integration testing, permitting true black-box and implementation-agnostic tests. None of this would have been possible without Generic types.

As a disclaimer, I want to once again note that this Repository implementation is lacking in a lot. I wanted to keep the example simple since the focus is the utilization of generics, which is why I didn’t handle the duplication or worry about transactions. Decent repository implementations would take an article all by themselves to explain fully and correctly, and the implementation details change depending on whether you’re doing N-Tier Architecture or DDD. That means that if you wish to use the Repository Pattern, you should not look at my implementation here as in any way a best practice.

Real-World Examples - React State & Props

The state, ref, etc., hooks for React Functional Components are Generic too. If I have an interface containing properties for Tasks, and I want to hold a collection of them in a React Component, I could do so as follows:

import React, { useState } from 'react';

export const MyComponent: React.FC = () => {
    // An empty array of tasks as the initial state:
    const [tasks, setTasks] = useState<Task[]>([]);
    
    // A counter:
    // Notice, type of `number` is inferred automatically.
    const [counter, setCounter] = useState(0);
    
    return (
        <div>
            <h3>Counter Value: {counter}</h3>
            <ul>
                {
                    tasks.map(task => (
                        <li key={task.id}>
                            <TaskItem {...task}/>
                        </li>
                    ))
                }
            </ul>
        </div>
    );
};

Additionally, if we want to pass a series of props into our function, we can use the generic React.FC<T> type and get access to props:

import React from 'react';

interface IProps {
    id: string;
    title: string;
    description: string;
}

export const TaskItem: React.FC<IProps> = (props) => {
    return (
        <div>
            <h3>{props.title}</h3>
            <p>{props.description}</p>
        </div>
    );
};

The type of props is inferred automatically to be IProps by the TS Compiler.

Conclusion

In this article, we’ve seen many different examples of Generics and their use cases, from simple collections, to error handling approaches, to data access layer isolation, etc. In the simplest of terms, Generics permit us to build data structures without needing to know the concrete time upon which they will operate at compile-time. Hopefully, this helps to open up the subject a little more, make the notion of Generics a little bit more intuitive, and bring across their true power.

$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$

A code example:

int main(int argc, char *argv[]) 
{
	int count = 0;
	int max = argv[1];

	for (int i = 1; i <= max; i++) 
	{
		count += i;
	}
	
	std::cout << "Sum: " << count << std::endl;
}

Product $\prod_{i=a}^{b} f(i)$ inside text.

A chemical formula:

$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$

A little bit more complex:

$\ce{Zn^2+ <=>[+ 2OH-][+ 2H+] $\underset{\text{amphoteres Hydroxid}}{\ce{Zn(OH)2 v}}$ <=>[+ 2OH-][+ 2H+] $\underset{\text{Hydroxozikat}}{\ce{[Zn(OH)4]^2-}}$}$

This is fun.

This article was first written for Smashing Magazine on November 22nd, 2019. You can find it here.

This article is the second part in a series, with part one located here, which provided basic and (hopefully) intuitive insight into Node.js, ES6+ JavaScript, Callback Functions, Arrow Functions, APIs, the HTTP Protocol, JSON, MongoDB, and more.

In this article, we’ll build upon the skills we attained in the previous one, learning how to implement and deploy a MongoDB Database for storing user booklist information, build an API with Node.js and the Express Web Application framework to expose that database and perform CRUD Operations upon it, and more. Along the way, we’ll discuss ES6 Object Destructuring, ES6 Object Shorthand, the Async/Await syntax, the Spread Operator, and we’ll take a brief look at CORS, the Same Origin Policy, and more. In a later article, we’ll refactor our codebase as to separate concerns by utilizing three-layer architecture and achieving Inversion of Control via Dependency Injection, we’ll perform JSON Web Token and Firebase Authentication based security and access control, learn how to securely store passwords, and employ AWS Simple Storage Service to store user avatars with Node.js Buffers and Streams - all the while utilizing PostgreSQL for data persistence. Along the way, we will re-write our codebase from the ground up in TypeScript as to examine Classical OOP concepts - like Polymorphism, Inheritance, Composition, etc., and even design patterns like Factories and Adapters.

A Word of Warning

There is a problem with the majority of articles discussing Node.js out there today. Most of them, not all of them, go no further than depicting how to setup Express Routing, integrate Mongoose, and perhaps utilize JSON Web Token Authentication. The problem is, they don’t talk about architecture, or security best practices, or about clean coding principles, or ACID Compliance, Relational Databases, Fifth Normal Form, the CAP Theorem, Transactions, etc. It’s either assumed that you know about all of that coming in, or that you won’t be building projects large or popular enough to warrant that aforementioned knowledge. There appear to be a few different types of Node developers - among others, some are new to programming in general, and others come from a long history of enterprise development with C# and the .NET Framework or the Java Spring Framework. The majority of articles cater to the former group. In this article, I’m going to do exactly what I just said that too many articles are doing, but in a follow up article, we are going to refactor our codebase entirely, permitting me to explain principles such as Dependency Injection, Three-Layer Architecture (Controller/Service/Repository), Data Mapping and Active Record, design patterns, unit, integration, and mutation testing, SOLID Principles, Unit of Work, coding against interfaces, security best practices like HSTS, CSRF, NoSQL and SQL Injection Prevention, etc. We will also migrate from MongoDB to PostgreSQL, using the simple query builder Knex instead of an ORM - permitting us to build our own data access infrastructure and to get close up and personal with the Structured Query Language, the different types of relations (One-to-One, Many-to-Many, etc.), and more. This article, then, should appeal to beginners, but the next few should cater to more intermediate developers looking to improve their architecture.

In this one, we are only going to worry about persisting book data. We won’t handle user authentication, password hashing, architecture, or anything complex like that. All of that will come in the next and future articles. For now, and very basically, we’ll just build a method by which to permit a client to communicate with our web server via the HTTP Protocol as to save book information in a database. I’ve intentionally kept it extremely simple and perhaps not all that practical here because this article, in and of itself, is extremely long, for I have taken the liberty of deviating to discuss supplemental topics. Thus, we will progressively improve the quality and complexity of the API over this series, but again, because I’m considering this as one of your first introductions to Express, I’m intentionally keeping things extremely simple.

ES6 Object Destructuring

ES6 Object Destructuring, or Destructuring Assignment Syntax, is a method by which to extract or unpack values from arrays or objects into their own variables. We’ll start with object properties and then discuss array elements.

const person = {
    name: 'Richard P. Feynman',
    occupation: 'Theoretical Physicist' 
};

// Log properties:
console.log('Name:', person.name); 
console.log('Occupation:', person.occupation); 

Such an operation is quite primitive, but it can be somewhat of a hassle considering we have to keep referencing person.something everywhere. Suppose there were 10 other places throughout our code where we had to do that - it would get quite arduous quite fast. A method of brevity would be to assign these values to their own variables.

const person = {
    name: 'Richard P. Feynman',
    occupation: 'Theoretical Physicist' 
};

const personName = person.name;
const personOccupation = person.occupation;

// Log properties:
console.log('Name:', personName); 
console.log('Occupation:', personOccupation); 

Perhaps this looks reasonable, but what if we had 10 other properties nested on the person object as well? That would be many needless lines just to assign values to variables - at which point we’re in danger because if object properties are mutated, our variables won’t reflect that change (remember, only references to the object are immutable with const assignment, not the object’s properties), so basically, we can no longer keep “state” (and I’m using that word loosely) in sync. Pass by reference vs pass by value might come into play here, but I don’t want to stray too far from the scope of this section.

ES6 Object Destructing basically lets us do this:

const person = {
    name: 'Richard P. Feynman',
    occupation: 'Theoretical Physicist' 
};

// This is new. It's called Object Destructuring.
const { name, occupation } = person;

// Log properties:
console.log('Name:', name); 
console.log('Occupation:', occupation); 

We are not creating a new object/object literal, we are unpacking the name and occupation properties from the original object and putting them into their own variables of the same name. The names we use have to match the property names that we wish to extract.

Again, the syntax const { a, b } = someObject; is specifically saying that we expect some property a and some property b to exist within someObject (i.e, someObject could be { a: 'dataA', b: 'dataB' }, for example) and that we want to place whatever the values are of those keys/properties within const variables of the same name. That’s why the syntax above would provide us with two variables const a = someObject.a and const b = someObject.b .

What that means is that there are two sides to Object Destructuring. The “Template” side and the “Source” side, where the const { a, b } side (the left-hand side) is the template and the someObject side (the right-hand side) is the source side - which makes sense - we are defining a structure or “template” on the left that mirrors the data on “source” side.

Again, just to make this clear, here are a few examples:

// ----- Destructure from Object Variable with const ----- //
const objOne = {
    a: 'dataA', 
    b: 'dataB'
};

// Destructure
const { a, b } = objOne;

console.log(a); // dataA
console.log(b); // dataB

// ----- Destructure from Object Variable with let ----- //
let objTwo = {
    c: 'dataC', 
    d: 'dataD'
};

// Destructure
let { c, d } = objTwo;

console.log(c); // dataC
console.log(d); // dataD

// Destructure from Object Literal with const ----- //
const { e, f } = { e: 'dataE', f: 'dataF' }; // <-- Destructure

console.log(e); // dataE
console.log(f); // dataF

// Destructure from Object Literal with let ----- //
let { g, h } = { g: 'dataG', h: 'dataH' }; // <-- Destructure

console.log(g); // dataG
console.log(h); // dataH 

In the case of nested properties, mirror the same structure in your destructing assignment:

const person = {
    name:  'Richard P. Feynman',
    occupation: {
        type:  'Theoretical Physicist',
        location: {
            lat:  1,
            lng:  2
        }
    }
};

// Attempt one:
const { name, occupation } = person;

console.log(name); // Richard P. Feynman
console.log(occupation); // The entire `occupation` object.

// Attempt two:
const { occupation: { type, location } } = person;

console.log(type); // Theoretical Physicist
console.log(location) // The entire `location` object.

// Attempt three:
const { occupation: {  location: { lat, lng } } } = person;

console.log(lat); // 1
console.log(lng); // 2

As you can see, the properties you decide to pull off are optional, and to unpack nested properties, simply mirror the structure of the original object (the source) in the template side of your destructuring syntax. If you attempt to destructure a property that does not exist on the original object, that value will be undefined.

We can additionally destructure a variable without first declaring it - assignment without declaration - using the following syntax:

let name, occupation;

const person = {
    name: 'Richard P. Feynman',
    occupation: 'Theoretical Physicist' 
};

;({ name, occupation } = person);

console.log(name); // Richard P. Feynman
console.log(occupation); // Theoretical Physicist

We precede the expression with a semicolon as to ensure we don’t accidentally create an IIFE (Immediately Invoked Function Expression) with a function on a previous line (if one such function exists), and the parentheses around the assignment statement are required as to stop JavaScript from treating your left-hand (template) side as a block.

A very common use case of destructuring exists within function arguments:

const config = {
    baseUrl: '<baseURL>',
    awsBucket: '<bucket>',
    secret: '<secret-key>' // <- Make this an env var.
};

// Destructures `baseUrl` and `awsBucket` off `config`.
const performOperation = ({ baseUrl, awsBucket }) => {
    fetch(baseUrl).then(() => console.log('Done'));
    console.log(awsBucket); // <bucket>
};

performOperation(config);

As you can see, we could have just used the normal destructuring syntax we are now used to inside of the function, like this:

const config = {
    baseUrl: '<baseURL>',
    awsBucket: '<bucket>',
    secret: '<secret-key>' // <- Make this an env var.
};

const performOperation = someConfig => {
    const { baseUrl, awsBucket } = someConfig;
    fetch(baseUrl).then(() => console.log('Done'));
    console.log(awsBucket); // <bucket>
};

performOperation(config);

But placing said syntax inside the function signature performs destructuring automatically and saves us a line.

A real-world use case of this is in React Functional Components for props:

import React from 'react';

// Destructure `titleText` and `secondaryText` from `props`.
export default ({ titleText, secondaryText }) => (
    <div>
        <h1>{titleText}</h1>
        <h3>{secondaryText}</h3>
    </div>
);

As opposed to:

import React from 'react';

export default props => (
    <div>
        <h1>{props.titleText}</h1>
        <h3>{props.secondaryText}</h3>
    </div>
);

In both cases, we can set default values to the properties as well:

const personOne = {
    name:  'User One',
    password:  'BCrypt Hash'
};

const personTwo = {
    password:  'BCrypt Hash'
};

const createUser = ({ name = 'Anonymous', password }) => {
    if (!password) throw  new  Error('InvalidArgumentException');
    
    console.log(name);
    console.log(password);
    
    return {
        id: Math.random().toString(36) // <--- Should follow RFC 4122 Spec in real app.
                .substring(2, 15) + Math.random()
                .toString(36).substring(2, 15),
        name: name,        // <-- We'll discuss this next.
        password: password // <-- We'll discuss this next.
    };
}

createUser(personOne); // User One, BCrypt Hash
createUser(personTwo); // Anonymous, BCrypt Hash

As you can see, in the event that name is not present when destructured, we provide it a default value. We can do this with the previous syntax as well:

const { a, b, c = 'Default' } = { a: 'dataA', b: 'dataB' };
console.log(a); // dataA
console.log(b); // dataB
console.log(c); // Default

Arrays can be destructured as too:

const myArr = [4, 3];

// Destructuring happens here.
const [valOne, valTwo] = myArr;

console.log(valOne); // 4
console.log(valTwo); // 3

// ----- Destructuring without assignment: ----- //
let a, b;

// Destructuring happens here.
;([a, b] = [10, 2]);

console.log(a + b); // 12

A practical reason for array destructuring occurs with React Hooks. (And there are many other reasons, I’m just using React as an example).

import React, { useState } from "react";

export default () => {
  const [buttonText, setButtonText] = useState("Default");

  return (
    <button onClick={() => setButtonText("Toggled")}>
      {buttonText}
    </button>
  );
}

Notice useState is being destructured off the export, and the array functions/values are being destructured off the useState hook. Again, don’t worry if the above doesn’t make sense - you’d have to understand React - and I’m merely using it as an example.

While there is more to ES6 Object Destructuring, I’ll cover one more topic here: Destructuring Renaming, which is useful to prevent scope collisions or variable shadows, etc. Suppose we want to destructure a property called name from an object called person, but there is already a variable by the name of name in scope. We can rename on the fly with a colon:

// JS Destructuring Naming Collision Example:
const name = 'Jamie Corkhill';

const person = {
    name: 'Alan Touring'
};

// Rename `name` from `person` to `personName` after destructuring.
const { name: personName } = person;

console.log(name); // Jamie Corkhill <-- As expected.
console.log(personName); // Alan Touring <-- Variable was renamed.

Finally, we can set default values with renaming too:

const name = 'Jamie Corkhill';

const person = {
    location: 'New York City, United States'
};

const { name: personName = 'Anonymous', location } = person;

console.log(name); // Jamie Corkhill
console.log(personName); // Anonymous
console.log(location); // New York City, United States

As you can see, in this case, name from person (person.name) will be renamed to personName and set to the default value of Anonymous if non-existent.

And of course, the same can be performed in function signatures:

const personOne = {
    name:  'User One',
    password:  'BCrypt Hash'
};

const personTwo = {
    password:  'BCrypt Hash'
};

const  createUser  = ({  name: personName =  'Anonymous', password }) => {
    if (!password) throw  new  Error('InvalidArgumentException');
    console.log(personName);
    console.log(password);

    return {
        id: Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
        name: personName,
        password: password // <-- We'll discuss this next.
    };
}

createUser(personOne); // User One, BCrypt Hash
createUser(personTwo); // Anonymous, BCrypt Hash

ES6 Object Shorthand

Suppose you have the following factory: (we’ll cover factories later)

const createPersonFactory = (name, location, position) => ({
    name: name,
    location: location,
    position: position
});

One might use this factory to create a person object, as follows. Also, note that the factory is implicitly returning an object, evident by the parentheses around the brackets of the Arrow Function.

const person = createPersonFactory('Jamie', 'Texas', 'Developer');
console.log(person); // { ... }

That’s what we already know from the ES5 Object Literal Syntax. Notice, however, in the factory function, that the value of each property is the same name as the property identifier (key) itself. That is - location: location or name: name. It turned out that that was a pretty common occurrence with JS developers.

With the shorthand syntax from ES6, we may achieve the same result by rewriting the factory as follows:

const createPersonFactory = (name, location, position) => ({
    name,
    location,
    position
});

const person = createPersonFactory('Jamie', 'Texas', 'Developer');
console.log(person);

Producing the output:

{ name: 'Jamie', location: 'Texas', position: 'Developer' }

It’s important to realize that we can only use this shorthand when the object we wish to create is being dynamically created based on variables, where the variable names are the same as the names of the properties to which we want the variables assigned.

This same syntax works with object values:

const createPersonFactory = (name, location, position, extra) => ({
    name,
    location,
    position,
    extra        // <- right here. 
});

const extra = {
    interests: [
        'Mathematics',
        'Quantum Mechanics',
        'Spacecraft Launch Systems'
    ],
    favoriteLanguages: [
        'JavaScript',
        'C#'
    ]
};

const person = createPersonFactory('Jamie', 'Texas', 'Developer', extra);
console.log(person);

Producing the output:

{ 
    name: 'Jamie',
    location: 'Texas',
    position: 'Developer',
    extra: { 
        interests: [ 
            'Mathematics',
            'Quantum Mechanics',
            'Spacecraft Launch Systems' 
        ],
        favoriteLanguages: [ 'JavaScript', 'C#' ]
     } 
}

As a final example, this works with object literals as well:

const id = '314159265358979';
const name = 'Archimedes of Syracuse';
const location = 'Syracuse';

const greatMathematician = {
    id,
    name,
    location
};

ES6 Spread Operator (…)

The Spread Operator permits us to do a variety of things, some of which we’ll discuss here.

Firstly, we can spread out properties from one object on to another object:

const myObjOne = { a: 'a', b: 'b' };
const myObjTwo = { ...myObjOne }:

This has the effect of placing all properties on myObjOne onto myObjTwo, such that myObjTwo is now { a: 'a', b: 'b' }. We can use this method to override previous properties. Suppose a user wants to update their account:

const user = {
    name: 'John Doe', 
    email: 'john@domain.com',
    password: '<hash>',
    bio: 'Lorem ipsum'
};

const updates = {
    password: '<new-hash>',
    bio: 'Ipsum lorem',
    email: 'j@domain.com'
};

const updatedUser = {
    ...user,    // <- original
    ...updates  // <- updates
};

console.log(updatedUser);

/*
 {
     name: 'John Doe',
     email: 'j@domain.com',    // Updated
     password: '<new-hash>',   // Updated
     bio: 'Ipsum lorem'
 }
 */

The same can be performed with arrays:

const apollo13Astronauts = ['Jim', 'Jack', 'Fred'];
const apollo11Astronauts = ['Neil', 'Buz', 'Michael'];

const unionOfAstronauts = [...apollo13Astronauts, ...apollo11Astronauts];

console.log(unionOfAstronauts);
// ['Jim', 'Jack', 'Fred', 'Neil', 'Buz, 'Michael'];