TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.

typescript

course repository: https://github.com/ducin/egghead-typescript/tree/brand-types-value-objects

Maggie Appleton

Choosing the proper types to model your data in complex applications is important. Most of the time you'll reach for primitive types that get the job done well. 

Primitive types have their downsides which we'll explore in this lesson. The main take away here is that when you have different _kinds_ of a primitive type, you can start running into issues when processing that data. For example, an object's 'id' and a property on the object of 'salary' might both be of type `number` but you would never want to add these two values together.  

Understand the Downsides of Overusing Primitive Types

Type Aliases are an easy way to declare that you are treating a primitive type in your application differently in certain instances than others. 

For instance, a `Money` type that is type `string` tells you where ever you are using `Money` to treat the value a certain way even though at the end of the day it is just a string.

Let's explore Type Aliases in this lesson.

Simplify TypeScript code Maintenance with Type Aliases

TypeScript will sometimes display the original Primitive Type rather than the Type Alias that you've set. By appending `& {}` to your Type Alias, you can force TypeScript to display your Alias.

Preserve Displaying TypeScript Type Alias Names

JSDoc allows you to add more context to what is displayed to your type when you hover over a value in your editor. We'll go over a basic use case of adding comments to our Type Alias so those will appear when we hover over them.

Improve Readability by Annotating Types with JSDoc

Using lookups in TypeScript for function parameter type definitions and other places can be useful for values you know might change over time. This will prevent you from having to change the type of the object itself as well as any function or component that needs to receive data about that object.

Provide Single Source of Truth for TypeScript Types using Lookups

Structural typing is when TypeScript looks at the shape of a type when comparing two different types. We can take advantage of this pattern by extending our type alias with a structural type that makes a primitive `number` type incompatible with our alias. 

We'll explore how to work with structural types in this lesson!

Make Primitive Types Incompatible using Typescript Structural Typing

Type Guards are expressions that guarantee the type of a value. In this lesson, we'll create functions that check if the values we pass them are valid types in our system. 

A great example here is with emails. Emails are strings with a very specific set of requirements. The type guard checks those requirements and if they pass then TypeScript will refer to that value as an `Email` instead of a `string` 

Validate Brand Typed Expressions with Custom Type Guards

Type utilities are essentially functions for our types in TypeScript. We'll create a type utility named `Brand` that will accept a primitive type and the name of the brand.

This will allow us to easily create Brand types throughout our application like the following:

```typescript
type Email = Brand<string, "EMAIL">;
type DateString = Brand<string, "DATE_STRING">
```
`Email` and `DateString` are both strings at the end of the day but you cannot assign a `DateString` to an `Email` or visa versa.

Create and Effectively Use TypeScript Brand Types

Value Objects are another pattern in Domain-driven Design that provide more structure around what you can and cannot do with a type. 

In TypeScript we create Value Objects with classes that will define what operations can be performed to the value on the class itself. In this lesson we'll explore how to create a Value Object for our `Money` type.

Restrict Available Operations on Values using Value Objects

Now that you've learned the basic principles of domain driven design, you will need to evaluate your codebase and see what patterns make sense for you. 

Aliases, Brand Types, and Value Objects go a long way to bringing more type-safety to your application while consolidating the sources of truth that your application has.

Evolve your Data Model with Aliases, Brand Types and Value Objects

Explore the capabilities of TypeScript’s type system and learn how to use advanced static types in practice.

Advanced Static Types in TypeScript

Learn the newest language features TypeScript has to offer. Learn how to use optional chaining, const assertions, conditional types, and more!

Advanced TypeScript Fundamentals

Domain Data Modeling using TypeScript Aliases, Brand Types and Value Objects

https://app.egghead.io/api/v1/lessons/typescript-understand-the-downsides-of-overusing-primitive-types/subtitles

[00:00] While working in highly complex applications, one of the challenges we can face is choosing the proper types to model our data. Most often, we're fine with using good old primitive values, for instance, representing an employee salary with a number type, especially when we just fetch the data and display it. However, the more
[00:20] we process the data, the more bugs we can introduce values, which represent totally different things, such as employee salary, employee's age, or even employee's ID are of the same type, which is basically the primitive number. Let's see an example. It does make sense to perform an
[00:40] operation on both employee salary and a project's budget since both values relate to the same type of data, which is essentially money. It also does make sense to include the offices, real estate, monthly rental. Still, this is money. However, technically, it's
[01:00] absolutely valid and possible to include things which are totally unrelated, such as employees age. This is all technically number. To make things worse, we can add them, we can multiply, we can square or square root and perform many other operations. At a certain point of complexity,
[01:20] many bugs could be caused because we allow the type system to perform operations on unrelated types, and simply it cannot find out what is meaningful and what is meaningless. Let's also declare a function that is going to find employees by skills. So this
[01:39] function would find employees which include a certain skill. In our domain, the skill is being represented as a primitive type, again, just a string. And let's say that what we are going to return here is an employee. Technically, again, it is valid to search
[01:59] the employees not by a skill, but by something totally unrelated like first name. And this could be a problem if there is a lot of data processing that is related to skills or money or whatever is important in your application. TypeScript enables many techniques to deal with these challenges.

https://app.egghead.io/api/v1/lessons/typescript-understand-the-downsides-of-overusing-primitive-types/transcript

https://app.egghead.io/api/v1/lessons/typescript-simplify-typescript-code-maintenance-with-type-aliases/subtitles

[00:00] Create an alias by simply creating a new type that relates to one of the existing types in TypeScript, such as string or number. Now, analyze the data types and the models that you're working with within your application and try to identify the types of the properties, their representation
[00:20] that might change in the future. In our example, we've got an employee entity and a human resource management application, and each entity has a salary. Right here, right now, the system doesn't differentiate various currencies. But if the business requirement comes to figure out what are the different currencies, what are the different amounts in their
[00:40] exchange rates, this number would have to be changed. So an example of a useful type alias would be simply money which is represented by a number and what is important, we are going to use the type money throughout our entire codebase. And of course we're going to replace the salary number with salary money.
[01:00] It's important to know that applying the type alias doesn't change anything when it comes to type compatibility. So salary used to be a number and after applying the alias, it still is a number. So nothing changes when it comes to type compatibility and any type of completion errors. However, the whole
[01:20] point of creating the type alias is to have one definition that we have to change if the type of the expression would be altered by business requirements. So that if we want to see where is a certain number type being used, then we would see multitude, 100, or even thousands of places where
[01:39] different numbers with different meanings would be found. And that would make changing the type in certain interfaces, types and functions way more difficult. And what we need to do after applying the alias is simply whenever something applies to money, we just consistently
[01:59] use the money type, which we're going to, of course, import. And from now on, we simply stick to all the places which use a certain type alias. We know exactly how many places use the specific alias. We know where they are. We can analyze them
[02:19] and roughly estimate how difficult would it be to alter the type according to business requirements. Another example for a type alias would be the skill of a certain employee. If we take a look at some example data that we've got in our repo, an employee would have skills which are basically some
[02:39] programming skills like MVC data structures, JavaScript, Visual Studio, TypeScript, jQuery, whatever. So right now, they're simply defined as a string. So either an employee has a skill or not. But we can easily imagine that in an HR application, that could evolve into
[02:59] a skill plus the level or number of years of experience in a certain skill. And again, we don't want to have multiple places to update the skill, and we just don't want to use the primitive representation, which is a string. And so we simply create yet another skill type alias,
[03:19] which initially is going to be a string. So initially, this is all our investment, but in a case where we need to modify what is the representation of a skill, we have simply one declaration that we could alter.

https://app.egghead.io/api/v1/lessons/typescript-simplify-typescript-code-maintenance-with-type-aliases/transcript

https://app.egghead.io/api/v1/lessons/typescript-preserve-displaying-typescript-type-alias-names/subtitles

[00:00] When using type aliases, sometimes TypeScript would explicitly reflect the fact that a certain type alias is being used. But in some cases, such as here when we hover over the property of the employee object, type alias is gone since an alias basically reflects just the original primitive type. So it's basically the same. So in some cases,
[00:20] it just doesn't show the fact. If you want to enforce TypeScript to highlight the fact that a type alias is being used, in case of primitive types, we can simply extend it with an empty object. In case of type compatibility, it doesn't change any rules.
[00:40] But from now on, we can see that not only when displaying the whole object, but also when showing the type of the property, the fact of using type alias is reflected. Extending a primitive type with an empty object type doesn't change the compatibility rules because in JavaScript in the runtime
[01:00] whenever we have a primitive number and for some reason we would like to treat it as if it was an object for instance 5.2 fixed, JavaScript is going to automatically wrap the primitive value into its object equivalent. So all in all, this is still going to be Numbuh though TypeScript is
[01:20] just seeing it in a slightly different way.

https://app.egghead.io/api/v1/lessons/typescript-preserve-displaying-typescript-type-alias-names/transcript

https://app.egghead.io/api/v1/lessons/typescript-improve-readability-by-annotating-types-with-jsdoc/subtitles

[00:00] When creating type aliases provide the JS doc annotations briefly defining what is the purpose of this type. In our case, the money type is intended only for money related values and the skill type represents an employee skill. Whenever anyone hovers over
[00:19] the type, they will see the type's relevant information. This can include links to tasks and documentation, but it can also be information about relations to other types used within the system. Of course, providing JsDoc could be useful in many other situations.

https://app.egghead.io/api/v1/lessons/typescript-improve-readability-by-annotating-types-with-jsdoc/transcript

https://app.egghead.io/api/v1/lessons/typescript-provide-single-source-of-truth-for-typescript-types-using-lookups/subtitles

[00:00] Another technique that can simplify maintenance of our TypeScript code basis in the long run is avoiding copying the types of certain properties of certain entities. So instead of copying, for instance, that ID of an employee type is a number and using explicitly the number type,
[00:19] we're going to look it up. We're going to relate to it directly and explicitly. So for instance, if we have a find employee by ID function, then the ID parameter that could be used is, of course, number because that's the type of the employee's ID property. But if this one changes,
[00:40] then we have a desynchronization between our function and the model definition. So what we want to do instead is basically look it up using the index notation in TypeScript. And whenever the type of the ID changes as we're here changing from
[01:00] number to string, which could happen in a system, for instance, when going to cloud, then all the usages of the ID or all other properties could be automatically reflected. One additional advantage that we gain from this approach is that when we change the shape of the entity type interface that we're working with, and let's
[01:20] say that we rename the ID property that we relate to into, let's say, GUID, then TypeScript would obviously synchronize between our model
[01:40] definition and the way we want to use the model within our functions and methods, such silly mistakes are going to be automatically caught and we're forced to adapt to what our model is. Note that this approach shouldn't be used universally. For instance, there are properties such as the first name and last name, which are
[02:00] strings, and it's really difficult to imagine that a first name would be anything different than a string. So whenever we see a probability that a definition of a certain property could change, this could be useful, but don't apply it everywhere universally.

https://app.egghead.io/api/v1/lessons/typescript-provide-single-source-of-truth-for-typescript-types-using-lookups/transcript

https://app.egghead.io/api/v1/lessons/typescript-make-primitive-types-incompatible-using-typescript-structural-typing/subtitles

[00:00] We can slightly modify the way TypeScript evaluates type compatibility across various types using TypeScript structural typing characteristics. That means if we want to change the type compatibility, we need to change the shape of a certain type by, for instance, extending the primitive with
[00:19] properties. At first, this could sound slightly strange, but we have already mentioned that a primitive is going to be boxed automatically wrapped into an object if only JavaScript requires that. The whole point of what we're doing is that this information, this additional property is going to be
[00:39] compile time only. This is not going to exist during JavaScript's run time. So just to illustrate how it works, let's declare 2 variables. 1 is going to be of type money, m for money. And let's also declare the n, which stands for number. What we want to
[00:59] see is whether we can assign one to the other and whether it works or not. So we can see that money can be assigned into number, but not the other way around. Why is that? Each expression of type money satisfies 2 conditions. 1st, it's number primitive. 2nd, it
[01:18] includes a property type of some unknown value, whatever. But on the other hand, number satisfies only one condition, which is basically being a number. So when we have a variable of type, an expression of type, money, then the requirement of being simply a number is
[01:38] satisfied. Well, it additionally has some additional properties, but it's not relevant. The only thing that is required, and it's being a primitive, is satisfied so that it works. On the other hand, when we want to assign anything into the money type, then 2 conditions need to be satisfied. Both being the primitive and having the
[01:58] additional property. And our number primitive satisfies the first condition, but it doesn't satisfy the other condition. In other words, we can think of types as being contracts, including 1 or more different conditions to be met. And this is how TypeScript evaluates type compatibility.
[02:18] Now, it would be possible theoretically to add this type property with the unknown value into a certain object. So just to make it slightly more bulletproof, let's just provide it with a unique symbol so that it would be impossible from the outside to provide exactly
[02:38] this symbol, this is because of how symbols work, and TypeScript requires us to annotate the type property with a read only modifier, so So just for the sake of correctness, let's annotate the type with a read only. But what is important is that we have made our type alias to
[02:58] be compatible only one way. So that each money is a number, but not each number is a valid money value. So what can we do with such money type? Well, we can do the arithmetic operations such as add equals, and here we can
[03:18] add m plus m. We can clearly see this is just a number since m itself is a number. We can also subtract and multiply, etcetera, etcetera. So we can see that due to the fact that money is a number, all of these work. However, if we want to create a money
[03:38] expression, we cannot just assign anything because we're not sure whether this number value relates to money. We need to check it somehow. Generally, there are 2 directions in which we can deal with that. One would be to simply brute force the compiler by saying, hey, compiler, Don't treat
[03:58] this expression as you would normally infer it to be the primitive number. Please subtype it so that it's not only a number, but it also includes one additional property. So this as money could also be wrapped into a function that accepts an argument, which is a
[04:17] number, and essentially, it's going to do the very same thing, just we wrap it with a function so that whenever we want to modify the way that we verify whether something is money or not, this is essentially being wrapped in a function that we're going to reuse, but still there is no
[04:37] check. However, there is a better way to deal with this.

https://app.egghead.io/api/v1/lessons/typescript-make-primitive-types-incompatible-using-typescript-structural-typing/transcript

https://app.egghead.io/api/v1/lessons/typescript-validate-brand-typed-expressions-with-custom-type-guards/subtitles

[00:00] A slightly better way to verify whether a regular number expression could be treated as money or first and foremost, how can we even create the valid expression of type money is to replace the type assertion and change the as money function into becoming
[00:20] a custom type guard. So we're going to include some validation logic into the ismoney function, and this is the main advantage. So in a very simple scenario, we could basically check whether argument is non negative. The whole point is that first, we have to check whether the
[00:39] conditions that we have defined are met. So, essentially, what we're going to do is to have a candidate. So there is a number that maybe it is money, maybe not. We'll see. And we're just creating an if statement to check whether this candidate is money or not.
[00:59] So before walking into the if statement, all we know about the end to expression is that it is of type number. However, if we walk into the truthy branch of the if statement, then we can see that yes, the conditions have been met. In various cases, this validation logic could be more or less complex. So let's take a look
[01:19] at one more example. Our employee entity includes an email property of type string, but we know that not all valid strings are also valid emails. So it's logically kind of incorrect to define that each string could be an email. So for this reason, let's
[01:39] create one more type, which is email a certain subtype of a string. And let's create a similar function is email, which is going to verify whether the candidate is a valid email. Only meaningful candidates for emails are obviously strings. And
[01:59] let's say that in this case, we're going to use a super complex email regex that we're going to test against our expression. So using this is email type guard, we're going to verify whether an email candidate which is, let's say,
[02:19] thomas at duching.dev is going to be a valid email. So if it does pass this reg x expression, which we're going to see right now, we would verify whether this is a valid email or not. What is important and what is
[02:38] an additional advantage is that if in our code base, in our memory, we keep the information that something that has already passed the validation is not just a regular string, but it is already an email, then we don't have to redo the validation. Like, we don't have to repeat it over and over
[02:58] again because on the type level, we can include the information that yes, this string primitive has already passed this. So our multiple functions or methods that require a certain email, not just a string, but email to be passed, they do not need to repeat the validation. What we
[03:18] need now is to create a more convenient way to create our special types for email and money and essentially to create brand types as money is a brand of number and email is a brand of string.

https://app.egghead.io/api/v1/lessons/typescript-validate-brand-typed-expressions-with-custom-type-guards/transcript

https://app.egghead.io/api/v1/lessons/typescript-create-and-effectively-use-typescript-brand-types/subtitles

[00:00] In order to create brand types, first, let's create the brand type utility, which will accept 2 type parameters. First is the base type, which is going to be the type that we're extending. So number in case of money and string in case of email. The second type parameter is the
[00:19] brand name, which will allow us to create multiple brands of number, multiple brands of string, making them incompatible between each other. So having these two type parameters, we can start and extend the base type the same way as we did already.
[00:39] And here we would also create a read only property. However, this time, we don't want to make it publicly visible. What is the name of the property? Just to make it even more bulletproof, we're going to put a JavaScript symbol over here. So for this reason, let's just declare one more symbol, which
[00:59] we're going to call, let's say, brand underscore type, which is going to be a unique symbol. So anybody who doesn't have access to this unique symbol will be unable to not only modify, but also read the value over here. So behind this brand type
[01:19] symbol key of the object, what we're going to put here is the brand name. So let's now update the declaration of our money, alias, which is going to be brand and the base type is, of course, number and the brand name is money. Let's also update the
[01:39] email to be the brand of string of type email. An important aspect of the declaration of the brand type utility is that the name of the brand becomes part of the type. In other words, when we take a look at the email brand, we can see that this is not
[01:59] just a string, but this is a very specific string. This is the name of the brand. This will help us to create multiple brands of the same base to be incompatible between each other. And so we would create a date string, which could be also a formatted version of a certain string. So let's just make it
[02:19] date string. So we can see that the email includes a certain value under the brand type symbol and the date string includes a different value over here. So essentially on the structural typing level, these structures are different, so they are
[02:38] essentially incompatible. So let's see this in action. If we declare a const email, which is of the email brand, and we declare the date string, which is of the date string brand, and we will just replace these with let
[02:58] so that we can check whether they are compatible when trying to assign one to the other, we will see that both are not compatible because the shape of the object, the shape of the brand over here is different. So in order to create a brand type, you can
[03:18] just create the brand using the type utility, and you don't need to know all the specific details of the brand type utility declaration.

https://app.egghead.io/api/v1/lessons/typescript-create-and-effectively-use-typescript-brand-types/transcript

https://app.egghead.io/api/v1/lessons/typescript-restrict-available-operations-on-values-using-value-objects/subtitles

[00:00] Brand types have one significant limitation and that is we can perform all operations that are available for the base type of a brand. So in case of the money brand, the base type is number so we can perform all operations on money that are available for numbers. And that doesn't always make
[00:20] sense. So in case of adding, the question is, can we add money to money? Yes. It makes sense. Can we subtract? Yes. It makes sense. But it doesn't really make sense to multiply money because there is nothing like squared dollar. And at the same time, if we want to have a square root,
[00:40] this doesn't necessarily make sense to have a square root of a dollar. Like there is a dollar, but there is no square root of a dollar. So if we want to limit not only the type compatibility, but also the allowed operations on a certain type of the data model, then we can evolve the type into
[00:59] a value object. Most often, a value object is going to be an instance of a class that will explicitly list what are the available operations on a certain type of the value. So we can have the add and multiply from the previous example. So what we can do is we can add, let's say, $10
[01:19] to another $10. Obviously, that's a valid operation, so we add money to another money, But we cannot multiply $10 by another $10 because there is nothing like 100 square dollars. So what we can do is we can multiply $10 by a factor that is basically example slightly more interesting, let's also include the fact that each
[01:39] money could be of a different currency. So the currency could be either American dollar or euro. And let's also create
[01:59] a constructor, which is going to include creating the private properties. So value is going to be the number. So let's also rephrase it to amount. And the other property could be the currency itself. So we have private currency, which is of
[02:19] type currency, and let's just fix this syntax error. So our constructor is essentially empty, it just assigns the two properties. And when we add money, it is possible to add dollars to dollars, but it's not possible to directly add dollars to
[02:39] Euro. So what we can also include here, and this is the best place for this if statement, not in our constructors, not in our components or whatever framework we are working with, but essentially it is the model which should guarantee and check the rules whether they are satisfied. So we can check whether
[02:59] that this dot currency is essentially the same as the another money's currency. So if it is different than another currency, then what we do is basically we throw a new error saying that 2 different currencies cannot be added. So cannot
[03:18] add different currencies. And again, whenever we want to run this add operation, we don't need to check this condition outside of the class. This is the one of the biggest advantages of value objects. However, if this requirement is satisfied, then we can just
[03:38] return new instance. So new money where this dot amount is being added to another dot amount. And since the currency is the same, then we basically take the currency from this. In case of multiply, we don't have to check the currency since there is just one
[03:58] money and a factor. So we'll basically return new money where we multiply this dot amount by what the factor is, and we just reuse the this dot currency. Let's also make sure that the validation logic that we've had in the previous example
[04:18] is going to be satisfied. So if we allow the money value object constructor to be called publicly, then it would be possible to pass any number value. And we would like to include the validation within the class so that it would be impossible to create invalid
[04:38] value of the amount. So for this reason, we're going to expose a static constructing method and to make the constructor itself to be private. And since the constructor is private, we will add the static, let's just call it from, and we would have that value
[04:57] amount, which is a number and currency, which is going to define the currency of the amount. And let's just return obviously the new money with the amount and currency, but the place for actually making sure that all the
[05:17] business rules are being checked within the static from method. So if amount is negative, then this is going to be impossible. So basically, if this rule is not held, then we're going to throw new error, impossible
[05:37] to create money with negative value. Of course, this is just an example. But again, we want to make sure that all the business rules are placed within the value object class. Right. Negative. Now let's see our money value
[05:57] object in action. First, let's export the class and let's get rid of the money brand type. Let's import the money value object. So the way we're going to instantiate it is going to be the money dot
[06:16] from. And let's say that we would create 99 dot99 American dollars. And we can see that there is no compatibility between the number primitive and money. This is because money doesn't extend the number primitive or the number prototype in
[06:36] any way. Hence, both types are incompatible. It is not possible to use the native addition operator, and obviously, it's also impossible to use the subtraction, multiplication, or doing any kind of other arithmetic operations. So what we can do in order to add is we
[06:56] can basically run the method, which is m dot add. And here we can add another money, whatever that is. So that would be basically yet another money value object. Or if you want to do a multiplication, what we can do is we can multiply by factors. So if we had 99 dot 99,
[07:16] then it would be basically multiplied. That would be yet one more money value object. And now since we have moved the validation rules into the static from method, we can safely remove the type guard, and we can also remove checking
[07:36] the rules of the values since they have been already checked while creation. There is way more when it comes to value objects. For instance, they should always be immutable so that they can be shared across the system and they can never represent entities and hence they can never include IDs.
[07:56] Because as the name suggests, they can only represent values and they can be part of other entities. But that's something you can learn from domain driven design.

https://app.egghead.io/api/v1/lessons/typescript-restrict-available-operations-on-values-using-value-objects/transcript

https://app.egghead.io/api/v1/lessons/typescript-evolve-your-data-model-with-aliases-brand-types-and-value-objects/subtitles

[00:00] When designing data model for your domain, start with identifying the pieces that could change in the future. Create appropriate type aliases for them and use them consistently. In the worst case scenario, if they don't change in the future, you have just created one additional line of code. However,
[00:19] if they do change, you'll have one single source of truth, one place to change, and you can either reduce the type compatibility across the types and other primitives, or if you want to additionally limit the available operations, then you can evolve a brand type into a value
[00:39] object.

https://app.egghead.io/api/v1/lessons/typescript-evolve-your-data-model-with-aliases-brand-types-and-value-objects/transcript

Domain Data Modeling using TypeScript Aliases, Brand Types and Value Objects

Tomasz Ducin

You might also like these resources:

Advanced Static Types in TypeScript

Advanced TypeScript Fundamentals

Credits

Course Content

You might also like these resources:

Advanced Static Types in TypeScript

Advanced TypeScript Fundamentals