DEV Community: Susan Potter

TypeScript's keyof operator and possible uses (Refreshed post, June 2023)

Susan Potter — Tue, 27 Jun 2023 13:35:00 +0000

In this article, I'll take you on a journey through the world of TypeScript's keyof operator and its uses.

Type-safe function parameters

keyof is a nifty operator that lets you dive into the heart of an object type, extracting and manipulating its keys with ease. Imagine dynamically accessing and working with specific properties, performing operations, and crafting utility functions tailored the types properties for added type safety. Say goodbye to boilerplate code for each type and embrace the freedom to create a more generic and reusable solution.

type Person = {
  name: string;
  age: number;
  email: string;
};

function getProperty(obj: Person, key: keyof Person) {
  return obj[key];
}

const person: Person = {
  name: "John",
  age: 91,
  email: "john@example.com",
};

// Below we access the `name` and `age` properties
// programmatically from the keys of the type definition
const name = getProperty(person, "name");
const age = getProperty(person, "age");

console.log(name); // Expected output: "John"
console.log(age); // Expected output: 91

The above runs and typechecks just fine but let's try to pass in the name of a property that does not exist on the Person type:

const emailAddress = getProperty(person, "emailAddress");
// Expected type error:
// Argument of type '"emailAddress"' is not assignable
// to parameter of type 'keyof Person'.

Of course, we return to the well with the correct property to retrieve and able to move past the type error:


const email = getProperty(person, "email");
console.log(email) // Expected output: "john@example.com"

Type-based return types

TypeScript's keyof operator can unlock the secret to type property-based return types.

By combining it with indexed access types ([]), you can create functions that strictly accept or return values based on the keys of an object. No more accidental typos or invalid arguments slipping through the cracks! Whether you're dealing with dynamic configurations or APIs that demand specific property names, keyof has got your back.

type Configuration = {
  apiKey: string;
  apiUrl: string;
  timeout: number;
};

const config: Configuration = {
  apiKey: "abc123",
  apiUrl: "https://example.com/api",
  timeout: 5000,
};

function getConfiguration<T extends keyof Configuration>(key: T): Configuration[T] {
  return config[key];
}

const apiKey: string = getConfiguration("apiKey"); // Type-safe parameter usage
console.log(apiKey); // Output: abc123

const timeout: number = getConfiguration("timeout"); // Type-safe return type
console.log(timeout); // Output: 5000

Key/Type Paired arguments

Brace yourself for an exhilarating journey where static analysis takes the stage. With keyof, the compiler becomes your vigilant guardian, meticulously validating your code to catch any mishaps related to property names and other parameters derived from the prpoerty name. Imagine catching those errors early in the development process, paving the way for rock-solid combinator libraries.

Assume we define a Product type with id, name, and price properties with different associated types.

enum Currency {
  USD,
  EUR,
  JPY,
};

type CurrencyAmount = {
  currency: Currency;
  amount: number;
};

type Product = {
  id: number;
  name: string;
  price: CurrencyAmount;
};

function updateProduct(
    product: Product,
    key: keyof Product,
    value: Product[keyof Product]
  )
{
  return { ...product, key: value };
}
const price: CurrencyAmount = {
  currency: Currency.USD,
  amount: 10
};
const product: Product = {
  id: 1,
  name: "Premium",
  price,
};

Dissecting the TypeScript function updateProduct:

The function updateProduct is declared with the const keyword. It takes three parameters: product, key, and value.
The product parameter is of type Product, which suggests that it expects an object of type Product as an argument.
The key parameter is of type keyof Product. Here, keyof Product represents a union type consisting of all the keys (property names) of the Product type. It means that key can only accept a valid key from the Product object.
The value parameter is of type Product[keyof Product]. It represents the type of the value corresponding to the key in the Product object. This ensures that the value parameter matches the type of the property indicated by the key parameter.
The return type of the updateProduct function is Product, indicating that it will return an object of type Product.
Inside the function body, a new object is created using the spread operator (...product) to copy all the properties of the product parameter.
The key parameter is used as a property name inside square brackets ([key]) to dynamically access the property in the new object.
The value parameter is assigned to the property indicated by the key, effectively updating the corresponding property value.
The updated object is returned as the result of the function.

In short, the updateProduct function takes an object of type Product, a valid property name from Product, and a value matching the type of the indicated property. It will create an object with the updated property value and returns it.

Let's try using the updateProduct to change valid properties with values that have types in the property types of Product:

// Below updates the property dynamically restricted to just
// the type of the keys in the type
const returnedProd1 =
  updateProduct(product, "name", "Professional");
console.log(returnedProd1.name); // Output: "Professional"

// Yo, inflation is still a thing so increase the price
const newPrice: CurrencyAmount = {
  currency: Currency.USD,
  amount: 12,
};
const returnedProd2 =
  updateProduct(product, "price", newPrice);
console.log(returnedProd2.price); // Output: {
//  "currency": 0,
//  "amount": 12
//}

Above you'll notice we get the expected behavior where the values of the property update as expected. Yet we all know the happy path is not the most interesting, so what happens when we try to update the product value altering a property that doesn't exist in the Product type?

// Failure mode where key given doesn't match underlying type
updateProduct(product, "quantity", 5);
// Type error: Property 'quantity' does not exist in type
// 'keyof Product'

A type error. Music to my ears.

Now we will try the case where the value parameter given doesn't match the type of any of the underlying type's property types:

// Failure mode where value doesn't match underlying
// property type
updateProduct(product, "id", false);
// Type error: Argument of type 'boolean' is not assignable
// to parameter of type 'string | number | CurrencyAmount'.

Perfect another type error.

A use case I'm Partial to!

However, what if we try to update the id property of the product value to a string?

const returnedProd3 = updateProduct(product, "id", "hello world");
console.log(returnedProd3.id); // Expected output: 1
console.debug(returnedProd3); // Expected output: {
//  "id": 1,
//  "name": "Professional",
//  "price": {
//    "currency": 0,
//    "amount": 12
//  }
//}

This is not ideal since it doesn't result in a type error. However, the behavior retains some weak notion of order by ignoring the invalid update to the id property with a string value instead of its expected type number.

Of course, if you are familiar with the Partial<T> type you will know that it offers a more ergonomic way for application developers to provide a partial object with well-typed key-value pairs corresponding to the T type for full coverage. Let's redefine the updateProduct function as follows:

const updateProduct2 = (
    product: Product,
    updates: Partial<Product>,
  ): Product => ({ ...product, ...updates });

Using the new updateProduct function definition that leverages Partial<Product> offers consumers improved developer ergonomics in multiple ways by:

accepting multiple property values to update in one operation
improving type safety

const returnedProd4 = updateProduct2(product, {
  name: "Professional",
  price: newPrice,
});
console.debug(returnedProd4); // Expected output: {
//  "id": 1,
//  "name": "Professional",
//  "price": {
//    "currency": 0,
//    "amount": 12
//  }
//}
console.debug(product); // Expected output: {
//  "id": 1,
//  "name": "Premium",
//  "price": {
//    "currency": 0,
//    "amount": 10
//  }
//}

Above you see that we passed in two properties to be updated in the returned object.

Now we will kick the tires on the type-safety of the new definition:

const returnedProd5 = updateProduct2(product, {
  id: "foobar",
});
console.debug(returnedProd5);
// Type error: Type 'string' is not assignable
// to type 'number'.

Now we get a type error. Success!

Under the hook, Partial<T> is still using the keyof indexed type query operator using something like the following definition:

type Partial<T> = {
  [P in keyof T]?: T[P];
};

For people newer to TypeScript I'll break down the type definition above:

The type Partial<T> is defined. It represents a new type that takes a generic parameter T, which can be any object type.
Inside the curly braces {}, we have a key-value pair syntax that defines the structure of the Partial<T> type.
[P in keyof T] is a mapped type that iterates over each key P in the keys of the T type. keyof T is a utility type in TypeScript that retrieves all the keys of the type T.

The ? postfix modifier indicates that the property is optional. It means that each property of the resulting type Partial<T> may or may not exist in the original type T.

T[P] is the type of the property with the key P in the original type T. It ensures that the value assigned to each property in Partial<T> is of the same type as the corresponding property in T. This is the key reason why we get better type-safety with the definition of updateProduct2 function.

By using this type definition, the Partial<T> type allows you to create a new type that shares the same keys as the original type T, but with all properties marked as optional. This is useful when you want to express that some properties of an object can be assigned undefined or omitted altogether.

With Partial<T>, you hold the key to create a brand new type that mirrors the original, but with the freedom to omit or assign undefined to any property. It's like having a personalized toolkit for crafting the perfect object. Say goodbye to rigid structures and embrace the art of possibility.

Update

June 2023 : Coming soon I will walk through step by step how to use common types in TypeScript that leverage keyof.

Conjuring TypeScript's Magic with Mapped Types

Susan Potter — Fri, 23 Jun 2023 00:00:00 +0000

TypeScript: The Savvy Sidekick of JavaScript
Why Mapped Types Matter
Mapped Types Syntax and Basic Plumbing
1. The Enchanting Syntax: Casting the Spell
2. The Components of Mapped Types: Unmasking the Wizards
A Deeper Dive!
1. Modifying Property Modifiers: Bending the Rules of Nature
2. Transforming Property Types: A Symphony of Type Transformations
Tips, Tricks, and Best Practices: Unleashing the Magic Safely
1. Tips for Working with Mapped Types: Navigating the Magical Realm
2. Best Practices and Guidelines: Taming the Magic for Large-Scale Projects
Wrapping it up

In this article, we’ll take a whirlwind tour through the fascinating world of TypeScript and its type system. Hold onto your hats and get ready to unleash the power of mapped types!

TypeScript: The Savvy Sidekick of JavaScript

Buckle up, folks! TypeScript swoops in like a suave sidekick, adding an extra layer of pizzazz to the world of JavaScript. With TypeScript, you get to catch those pesky bugs before they even think about causing chaos in your code.

It’s time to introduce you to the heroes of our story: mapped types! These are the true sorcerers of TypeScript especially when used in conjunction with keyof and conditional types. They wield the power to transform and shape types with a flick of their magical wands. Mapped types allow you to redefine existing types, making them dance to your tune.

Why Mapped Types Matter: The Plot Thickens

Mapped types give you the power to streamline your code, enhance its clarity, and catch those sneaky bugs before they wreak havoc. They enable you to write robust, maintainable code that makes your fellow developers nod in gratitude (when used just right).

To illustrate the utility of mapped types we will show how to use a mapped type commonly used in TypeScript already: Pick.

Let us start with the trusted Person type example developers overuse ad nauseam to show what it does:

    type Person = {
      name: string;
      age: number;
      address: string;
      email: string;
    };

Sometimes we only want to pass a subset of the Person type’s properties values to functions. In JavaScript we either pass the entire object value regardless or we pass the properties one-by-one as separate arguments.

In TypeScript we can compute a new type that plucks (or “picks”) a specific subset of properties names to collate in one type definition.

In the example below we pluck (or “pick”) the name and age properties from the Person type defined above.

    // Behold, the power of Pick!
    type PersonBasicInfo =
      Pick<Person, 'name' | 'age'>;

The type computed by Pick<Person, 'name' | 'age'> looks like this:

    {
      name: string;
      age: number;
    }

With the power of Pick we summoned the PersonBasicInfo type containing only the name and age properties.

Mapped Types Syntax and Basic Plumbing

It’s time to decode the incantations and unravel the key components that make mapped types spellbinding.

The Enchanting Syntax: Casting the Spell

We define mapped types using angle brackets < > and curly braces { }. Let’s demystify the basic syntax step-by-step:

    type MappedType = {
      [Property in ExistingType]: NewProperty
    };

MappedType
: This is the name you give to your created mapped type. It can be any valid type name you choose.

[Property in ExistingType]
: This is the magical syntax incantation that sets up your mapped type. Property represents each property in the existing type that you want to manipulate. ExistingType is the original type from which you’re deriving the mapped type.

NewProperty
: This is where your creativity comes into play. You define the transformed version of each property in the mapped type.

The Components of Mapped Types: Unmasking the Wizards

Property: The Building Block of Magic

In this example, we’ll transform the properties of an existing type, Person, into optional properties using mapped types:

    type Person = {
      name: string;
      age: number;
      address: string;
    };

    type OptionalPerson = {
      [Property in keyof Person]?: Person[Property]
    };

Person
: Our existing type with properties name, age, and address.

OptionalPerson
: The name of our mapped type. We use the keyof operator to iterate over each property in Person and create optional properties in OptionalPerson.

The resulting type looks like the following:

    type OptionalPerson = {
      name?: string | undefined;
      age?: number | undefined;
      address?: string | undefined;
      email?: string | undefined;
    };

Examples of valid constructions of this type include:

    // Note: Shakespeare doesn't have an email
    const shakespeare: OptionalPerson = {
      name: "William Shakespeare",
      age: 52,
      address: "Stratford-upon-Avon, England",
    };

    // After dying Shakespeare's address changed
    const deathChanges: OptionalPerson = {
      address: "Church of the Holy Trinity, Stratford-upon-Avon",
    };

    const updatedShakespeare: OptionalPerson = {
      ...shakespeare,
      ...deathChanges
    };

ExistingType: The Source of Power

Let’s explore another example that transforms the property types of an existing type:

    type Person = {
      name: string;
      age: number;
    };

    type PersonWithOptionalProps = {
      [Property in keyof Person]: Person[Property] | undefined
    };

Person
: Our existing type with properties name and age.

PersonWithOptionalProps
: Our mapped type that retains the same properties as Person, but with transformed property types. We use the keyof operator to iterate over each property in Person and create a union type with undefined.

You might be wondering what is the difference between OptionalPerson and PersonWithOptionalProps? Let’s look at the computed type definition:

    type PersonWithOptionalProps = {
        name: string | undefined;
        age: number | undefined;
        address: string | undefined;
        email: string | undefined;
    };

Note that the property names do not have the ? suffix. What does this mean in pracitce? Let’s try to set the type to the object literal set to the shakespeare constant above:

    const shakespeare2: PersonWithOptionalProps = {
      name: "William Shakespeare",
      age: 52,
      address: "Stratford-upon-Avon, England",
    }; // Errors see message below

Now we get an error! Let’s take a look:

    Property 'email' is missing in type
             '{ name: string;
                age: number;
                address: string;
              }'
    but required in type 'PersonWithOptionalProps'.

So what this is saying is that we do need to set the missing email property. To model our requirements, we can set it to undefined to denote that shakespeare2 has no email property value.

    const shakespeare2: PersonWithOptionalProps = {
      name: "William Shakespeare",
      age: 52,
      address: "Stratford-upon-Avon, England",
      email: undefined,
    };

The above now typechecks and the original error applies to any missing property. We needed to explicitly set the missing properties from Person to undefined.

Modifying Properties: Infusing Your Magic

Let’s delve into an example where we omit the modifiers of properties:

    type ReadonlyPerson = {
      readonly name: string,
      readonly age: number,
      readonly address: string,
      readonly email: string,
    };

    type MutablePerson = {
      -readonly [Property in keyof ReadonlyPerson]: ReadonlyPerson[Property]
    };

Person
: Our existing type with properties name and age.

MutablePerson
: Our mapped type that mirrors the properties of Person, but removes the readonly modifier. We use the -readonly syntax to update the property modifiers within the mapped type.

MutablePerson computes to:

    type MutablePerson = {
        name: string;
        age: number;
        address: string;
        email: string;
    };

No readonly, mom!

Adding Properties

Let’s explore one last example to showcase the versatility of mapped types:

    type Circle = {
      radius: number;
    };

    type Cylinder = {
      radius: number;
      height: number;
    };

    type CalculateVolume<T> = {
      [Property in keyof T]: T[Property];
    } & { volume: number };

    function calculateCylinderVolume(
      cylinder: Cylinder
    ): CalculateVolume<Cylinder> {
      const volume =
        Math.PI * cylinder.radius ** 2 * cylinder.height;
      return { ...cylinder, volume };
    }

Circle
: Our existing type representing a circle with a radius property.
Cylinder
: Another existing type representing a cylinder with radius and height properties.
CalculateVolume<T>
: Our mapped type that extends any existing type T. It retains the properties of T and adds a new volume property of type number.
calculateCylinderVolume
: A function that takes a Cylinder object, calculates its volume, and returns a CalculateVolume<Cylinder> object with the original properties of Cylinder and the newly added volume property.

With these examples, you’ve witnessed the magic of mapped types. We have manipulated properties, modified modifiers, transformed property types and added new properties.

A Deeper Dive!

In this section, we explore the mechanics of property transformation and mapped types to reshape our types with a dash of enchantment.

Modifying Property Modifiers: Bending the Rules of Nature

Making Properties Optional: Partial type

Imagine a world where properties have the freedom to choose their destiny, where they can be present or absent at their whim. Enter the wondrous Partial type! Let’s demystify the derivation of Partial from first principles:

    type Partial<T> = {
      [Property in keyof T]?: T[Property]
    };

Partial<T>
: computes a new type that mirrors the original type T, but grants properties the ability to become optional using the ? modifier. It’s like giving properties a ticket to the land of freedom.

Let’s witness the power of Partial in action:

    interface Wizard {
      name: string;
      spells: string[];
    }

    type PartialWizard = Partial<Wizard>;

    const wizard: PartialWizard = {}; // Property "name" and "spells" become optional

PartialWizard
: Our transformed type derived from Wizard using the Partial mapped type. Now, properties like name and spells have the choice to be present or absent, granting flexibility and easing our coding journey.

Making Properties Read-Only: `Readonly` type

In the land of code, where properties roam free, some properties prefer to stand tall and unchangeable, like statues of wisdom. Enter the majestic Readonly type, which bestows the power of immutability upon properties. Let’s unlock the secrets of Readonly:

    type Readonly<T> = {
      readonly [Property in keyof T]: T[Property]
    };

Readonly<T>
: The alchemical mixture that creates a new type with the same properties as the original T, but marked as readonly. It’s like encasing properties in an unbreakable spell, ensuring they remain untouchable.

Behold the might of Readonly in action:

    interface Potion {
      name: string;
      ingredients: string[];
    };

    const potion: Potion = {
      name: "Elixir of Eternal Youth",
      ingredients: ["Unicorn tears", "Moonlight essence"],
    };

    potion.name = "Forbidden Potion"; // Works
    console.debug(potion.name); // prints "Forbidden Potion"

    type ReadonlyPotion = Readonly<Potion>;

    const ropotion: ReadonlyPotion = {
      name: "Elixir of Eternal Youth",
      ingredients: ["Unicorn tears", "Moonlight essence"],
    };

    ropotion.name = "Forbidden Potion"; // Error! Property "name" is read-only

ReadonlyPotion
: Our transformed type created from Potion using the Readonly mapped type. Now, properties are guarded against any attempts to change them. This ensures their immutability and preserves their original value.

Excluding Properties: `Exclude` type

Sometimes we need to separate the chosen from the unwanted, to exclude certain elements from our type sorcery. Enter the extraordinary Exclude type, capable of removing specific types from a union. Let’s uncover the essence of Exclude:

    type Exclude<T, U> = T extends U ? never : T;

Exclude<T, U>
: The spell that removes types present in U from the union of types T. Like a forcefield that shields our types from unwanted members.

Let’s witness the might of Exclude:

    type Elements = "Fire" | "Water" | "Air" | "Earth";
    type ExcludedElements = Exclude<Elements, "Fire" | "Air">;

    const element: ExcludedElements = "Water"; // Success! Excludes "Fire" and "Air"
    const forbiddenElement: ExcludedElements = "Fire"; // Error! "Fire" is excluded

ExcludedElements
: Our transformed type, derived from Elements using the Exclude mapped type. With the power of Exclude, we’ve excluded the elements “Fire” and “Air” from our new type, allowing only “Water” and “Earth” to remain.

Transforming Property Types: A Symphony of Type Transformations

Modifying Property Types: Pick and Record types

Picture a symphony where notes dance and melodies intertwine. In the world of TypeScript, we have the harmonious Pick and Record types. They pluck or transform property types. Let’s explore their utility:

Pick<T, K>
: computes a new type selecting specific properties K from the original type T.

Record<K, T>
: computes a new type by mapping each property key K to a corresponding property type T.

Let’s review some examples of Pick and Record:

    interface Song {
      title: string;
      artist: string;
      duration: number;
    }

    type SongTitle = Pick<Song, "title">;
    type SongDetails = Record<"title" | "artist", string>;

    // Only "title" property is allowed
    const songTitle: SongTitle = { title: "In the End" };
    // Only "title" and "artist" properties are allowed
    const songDetails: SongDetails = { title: "Bohemian Rhapsody", artist: "Queen" };

SongTitle
: Our transformed type derived from Song using the Pick mapped type. It selects only the title property, allowing us to focus on the song title.

SongDetails
: Our transformed type derived from the key "title" | "artist" and the type string using the Record mapped type. It maps each property key to the type string, creating a type that captures the song title and artist.

Replacing Property Types: Mapped Types with conditional types

Now, we explore how mapped types can work with conditional types to transform property types:

Conditional Types
: A type-level capability to adapt based on conditions. I wrote about conditional types in a previous post, illustrating good and bad examples.

Let’s observe conditional transformations with code examples:

    type Pet = "Cat" | "Dog" | "Bird";
    type Treats<T extends Pet> = T extends "Cat" ? string[] : T extends "Dog" ? number : boolean;

    const catTreats: Treats<"Cat"> = ["Salmon Treats", "Catnip"]; // Array of strings
    const dogTreats: Treats<"Dog"> = 5; // Number
    const birdTreats: Treats<"Bird"> = true; // Boolean

Treats<T>
: Our transformed type, where the property type varies based on the condition in the conditional type. The resulting type adapts to the pet’s type from the input, offering an array of strings for a cat, a number for a dog, and a boolean for a bird.

Above we observed the powers of Pick, Record, and the fusion of mapped types with conditional types. Using these TypeScript capabilities, we can reduce boilerplate and express the problem domain more directly.

So, grab your wands, summon your creativity, and let the transformation of properties and property types begin! But be judicuous.

Tips, Tricks, and Best Practices: Unleashing the Magic Safely

Tips for Working with Mapped Types: Navigating the Magical Realm

As we traverse mapped types, it’s essential to keep a few tips and tricks up our sleeves.

Consider performance implications:
- Mind the size and complexity of your types.
- Large mappings can lead to longer compile times and increased memory usage.
- Strike a balance between expressiveness and performance for optimal code execution.
Beware of limitations and pitfalls:
- Mapped types cannot create new properties that don’t exist in the original type.
- Complex mappings or recursive transformations may result in convoluted and hard-to-read code.
- Stay vigilant and explore alternative strategies when faced with these challenges.
Master complex mappings and type inference challenges:
- Embrace utility types like keyof and conditional types.
- Harness their power to navigate intricate mappings and overcome type inference hurdles.
- Experiment, iterate, and tap into the vast resources of the TypeScript documentation and developer communities.

With these suggestions, you can leverage TypeScript’s mapped types while avoiding common pitfalls.

Best Practices and Guidelines: Taming the Magic for Large-Scale Projects

To tame the magic of mapped types in large projects, follow these best practices:

Organize and maintain mapped types:
- Group related types together.
- Create dedicated type files.
- Provide clear documentation.

This fosters maintainability and enables effective use by fellow wizards.

Ensure type safety and compatibility:
- Use type guards and strict null checks.
- Perform thorough testing.

Validate the safety and compatibility of your mapped types. Integrate comprehensive yet meaningful tests to check their usage is as expected.

Leverage mapped types for clarity and maintainability:
- Create reusable abstractions.
- Enforce consistent patterns.
- Reduce duplication.
- Avoid reinventing mapped types already provided by TypeScript.

Harness mapped types to enhance code readability and simplify maintenance tasks.

Wrapping it up

Throughout this article we embarked on a wild ride through the enchanted land of mapped types in TypeScript. We’ve seen their transformative abilities, from modifying property modifiers to reshaping property types. We’ve explored tips, tricks, and better practices for mapped types.

Unleash your imagination and continue exploring the enormous possibilities that mapped types offer. Yet avoid reinventing constructs as TypeScript already defines utility types for common uses.

Wield the magic of mapped types with care, always striving for clarity, maintainability, and type safety but do not overuse. Your future teammates will thank you later.

Using Conditional Types in TypeScript

Susan Potter — Wed, 31 May 2023 00:00:00 +0000

A High-Level Understanding
When to use Conditional Types
But wait, we didn’t use UpdateObject<T, U> anywhere
Embrace the Power of Conditional Types but only when you really need to! :)

Welcome, fellow developer. Today we embark on a [hopefully] helpful journey into the world of conditional types via TypeScript! I hope to impress upon you how we can levereage conditional types to offer improved type safety especially in cases where the type of an associated piece of data can be computed from the type of the original data that is polymorphic in nature.

A High-Level Understanding

Conditional types are like shape-shifters, capable of dynamically transforming and adapting types based on varying conditions. They bestow upon the developer the gift of creating flexible type mappings without compromising on how well-typed our definitions are, thus empowering our code with expressiveness and resilience.

In this introductory section I will show the mechanics of how to describe conditional types in TypeScript itself even if the examples are trivial and not useful so that I am not distracted explaining the syntax in more useful and involved examples later on.

    import { option } from 'https://cdn.skypack.dev/fp-ts?dts';

Here I am just importing the Option<T> parameterized type from my trusted friend fp-ts,
a library I tend to use in TypeScript codebases when I am able. If you are unfamiliar with this type think of this as an alternative way of encoding a nullable value in a more type safe way.

    type NumberValidator = {
      minValue: option.Option<number>;
      maxValue: option.Option<number>;
    };

    type StringValidator = {
      minLength: option.Option<number>;
      maxLength: option.Option<number>;
      contains: option.Option<RegExp>;
      matches: option.Option<RegExp>;
    };

    type NoopValidator = {};

We start of by defining the type NumberValidator, which represents a validator for numeric values, and the StringValidator type, which is a validator for string values. Both types have specific properties that define their validation rules.

The NumberValidator type has minValue and maxValue properties, each wrapped in an Option<number> type from fp-ts. These options can hold either a number value or no value at all.

the StringValidator type has minLength, maxLength, contains, and matches properties, all wrapped in Option<T> types. These options allow us to define constraints such as minimum and maximum lengths, required patterns, and more.

We also have a NoopValidator type, which represents a validator that doesn’t perform any specific validations. It’s essentially an empty object, signaling that no validation rules are applicable.

    const slugValidator: Validator<string> = {
      minLength: option.some(1),
      maxLength: option.some(10),
      matches: option.some(/^[a-z\-]+$/),
      contains: option.none,
    };

    const titleValidator: Validator<string> = {
      minLength: option.some(1),
      maxLength: option.some(64),
      matches: option.none,
      contains: option.none,
    };

    // age validator for purchasing alcohol in any sane country
    const ageValidator: Validator<number> = {
      minValue: option.some(18),
      maxValue: option.some(149),
    };

Next up we define two instances of Validator<string>: slugValidator and titleValidator. These objects use the Validator type we defined later to determine their structure based on the type argument provided.

The slugValidator object specifies some validation rules for a string field.

The titleValidator object, on the other hand, focuses on validating a string field for a title. It requires a minimum length of 1, a maximum length of 64, and doesn’t have any pattern-based constraints.

Lastly, we encounter an age validator object – ageValidator. It’s specifically designed to validate numeric values, representing the age of an individual for purchasing alcohol in a sane country (we like sanity!). This validator sets a minimum age of 18 and a maximum age of 149, making sure we don’t encounter any age-related shenanigans.

    type Field = number | string | unknown;
    type Validator<T extends Field> = T extends number
      ? NumberValidator
      : (T extends string ? StringValidator : NoopValidator);

To wrap up the initial example we define a type alias called Field that can be either a number, a string, or an unknown type. Then, we define the Validator type, which takes a generic argument T extending Field.

Here’s where the conditional magic comes into play: using the extends keyword, we check if T extends number. If it does, the type becomes NumberValidator. If T extends string, the type becomes StringValidator. And if none of the conditions match, we fall back to NoopValidator. Notice the familiar ternary operator syntax for conditional values in this type expression.

In essence, these mechanics allow us to dynamically determine the structure and properties of the validator object based on the type we provide. It’s like having different validator configurations tailored to the type of data we’re validating – an incredibly powerful technique!

When to use Conditional Types

Picture this: you’re tasked with updating different types of objects, but here’s the catch—you don’t know which type or fields of the type. This exactly where conditional types come to the rescue, swooping in like a superhero to save the day.

Yes, perhaps this is a little contrived to show the power of conditional types mixed with keyof for a more involved example I covered how to use keyof in TypeScript in a previous post.

Now, let me take you on a journey through the magical realm of TypeScript, where we’ll witness firsthand how conditional types can boost your code’s type safety and eliminate those dreadful runtime bugs for a situation like this.

First things first, what are conditional types? Think of them as intelligent type definitions that adapt based on conditions. They allow us to model complex scenarios, such as handling updates to objects with unknown fields, with elegance and precision.

Imagine you have a function called updateObject that takes an original object and an updates object. Traditionally, without conditional types, you might write something like this:

    function updateObject(original: any, updates: any): any {
      return { ...original, ...updates };
    }

Sure, it gets the job done, but it’s like playing with fire. It’s untyped, leaving you vulnerable to runtime bugs that may lurk in the shadows. Spelling mistakes, non-existent fields—these errors can easily slip through the cracks, only to haunt you later.

Also, if you have read my previous post on the differences between any versus unknown in TypeScript you will know any typing should only be done as a last resort in TypeScript.

Fear not, reader! Conditional types are here to save us from this chaos. Let’s dive into the code and see how we can level up our type safety game.

We’ll start by defining a conditional type called UpdateObject. Brace yourself for the magic:

    type UpdateObject<T, U> = {
      [K in keyof T]: K extends keyof U ? U[K] : T[K];
    };

Let’s break the above down. The UpdateObject type takes two generic parameters, T and U, representing the original object and the updates object, respectively. Now, pay close attention to the square brackets [K in keyof T].

This snippet introduces a loop that iterates over each property K in T, which is the key type of the original object. But here comes the real beauty—the conditional statement: K extends keyof U ? U[K] : T[K].

This line of code works its magic by checking if K exists in the keys of U, our updates object. If it does, TypeScript gracefully assigns the type of U[K] to the property in the resulting object. However, if the property doesn’t exist in U, it falls back to the type of T[K], ensuring we maintain the original value.

Now that we have our powerful UpdateObject type, let’s put it into action by revamping our updateObject function:

    function updateObject<
        T,
        U extends Partial<T>
      >(original: T, updates: U): T {
        return { ...original, ...updates };
    }

Bear with me, folks—we’re almost there! The updateObject function now receives two parameters: original, representing the original object, and updates, holding our updates object. But what’s this <T, U extends Partial<T>> magic?

Here, we’re using TypeScript’s generic parameters to ensure type safety. T represents the original object’s type, while U extends Partial<T>. This ensures that the updates object can only contain a subset of properties from the original object, avoiding unexpected additions.

With our revamped function in place, we can now unleash the power of TypeScript’s type system to catch bugs at compile-time, rather than chasing them through the treacherous land of runtime.

Let’s say we have a Person type:

    type Person = {
      name: string;
      age: number;
      address: string;
    };

Using our updated function, we can confidently update a Person object, knowing that TypeScript will guard us against any mishaps:

    const person: Person = {
      name: 'Alice',
      age: 25,
      address: '123 Main St'
    };

    const updatedPerson = updateObject(person, {
      age: 26,
      address: '456 Elm St'
    });

Trying to pass a partial object for the updates with a misspelled attribute will now result in a type error. Like the following:

    const updatedPerson2: Person =
      updateObject(person, { adress: 232, });

This will produce the type error:

    Argument of type '{ adress: number; }' is not assignable
      to parameter of type 'Partial<Person>'.
      Object literal may only specify known properties, but
      'adress' does not exist in type 'Partial<Person>'.
      Did you mean to write 'address'?

Boom! With TypeScript’s watchful eye, any misspelled field names or attempts to update non-existent fields will be caught right at compile-time. No more runtime surprises, my friends!

But wait, we didn’t use `UpdateObject<T, U>` anywhere

Good eye, reader. This was pointed out to me after I published a draft for people to review. I realized in the second case the Partial<T> type was all the magic this case needed. No need to get fancy with conditional types.

So, dear developers, embrace the power of TypeScript and awe inspiring types like Partial<T>. Say goodbye to the unpredictable world of runtime bugs, and stride confidently towards a future of reliable and type-safe code.

Embrace the Power of Conditional Types but only when you really need to! :)

Well the moral of this story is that next time I will not sit on a half finished blog post for so long such that I lose all my train of thought on the more “motivating” example to use such that it is essentially an invalid example for what I wished to demonstrate.

Forgive me, reader and take care until next time where we explore mapped types and even combine it with conditional types that we just explored here.

DEV Community: Susan Potter

TypeScript's keyof operator and possible uses (Refreshed post, June 2023)

Type-safe function parameters

Type-based return types

Key/Type Paired arguments

A use case I'm Partial to!

Update

Conjuring TypeScript's Magic with Mapped Types

Table of Contents

TypeScript: The Savvy Sidekick of JavaScript

Why Mapped Types Matter: The Plot Thickens

Mapped Types Syntax and Basic Plumbing

The Enchanting Syntax: Casting the Spell

The Components of Mapped Types: Unmasking the Wizards

Property: The Building Block of Magic

ExistingType: The Source of Power

Modifying Properties: Infusing Your Magic

Adding Properties

A Deeper Dive!

Modifying Property Modifiers: Bending the Rules of Nature

Making Properties Optional: Partial type

Making Properties Read-Only: `Readonly` type

Excluding Properties: `Exclude` type

Transforming Property Types: A Symphony of Type Transformations

Modifying Property Types: Pick and Record types

Replacing Property Types: Mapped Types with conditional types

Tips, Tricks, and Best Practices: Unleashing the Magic Safely

Tips for Working with Mapped Types: Navigating the Magical Realm

Best Practices and Guidelines: Taming the Magic for Large-Scale Projects

Wrapping it up

Using Conditional Types in TypeScript

Table of Contents

A High-Level Understanding

When to use Conditional Types

But wait, we didn’t use `UpdateObject<T, U>` anywhere

Embrace the Power of Conditional Types but only when you really need to! :)

DEV Community: Susan Potter

TypeScript's keyof operator and possible uses (Refreshed post, June 2023)

Type-safe function parameters

Type-based return types

Key/Type Paired arguments

A use case I'm Partial to!

Update

Conjuring TypeScript's Magic with Mapped Types

Table of Contents

TypeScript: The Savvy Sidekick of JavaScript

Why Mapped Types Matter: The Plot Thickens

Mapped Types Syntax and Basic Plumbing

The Enchanting Syntax: Casting the Spell

The Components of Mapped Types: Unmasking the Wizards

Property: The Building Block of Magic

ExistingType: The Source of Power

Modifying Properties: Infusing Your Magic

Adding Properties

A Deeper Dive!

Modifying Property Modifiers: Bending the Rules of Nature

Making Properties Optional: Partial type

Making Properties Read-Only: Readonly type

Excluding Properties: Exclude type

Transforming Property Types: A Symphony of Type Transformations

Modifying Property Types: Pick and Record types

Replacing Property Types: Mapped Types with conditional types

Tips, Tricks, and Best Practices: Unleashing the Magic Safely

Tips for Working with Mapped Types: Navigating the Magical Realm

Best Practices and Guidelines: Taming the Magic for Large-Scale Projects

Wrapping it up

Using Conditional Types in TypeScript

Table of Contents

A High-Level Understanding

When to use Conditional Types

But wait, we didn’t use UpdateObject<T, U> anywhere

Embrace the Power of Conditional Types but only when you really need to! :)

Making Properties Read-Only: `Readonly` type

Excluding Properties: `Exclude` type

But wait, we didn’t use `UpdateObject<T, U>` anywhere