DEV Community: Nick Korolev

TypeScript Type for Conditional Parameters with Compile-Time Validation

Nick Korolev — Sun, 26 Feb 2023 12:43:44 +0000

Introduction

Configurable objects are a common pattern in software development, allowing functions and APIs to be customized based on various parameters. However, ensuring that certain parameters are present or absent based on a certain condition can be a challenge. Consider the example of a function that generates SQL queries based on configurable search parameters. Some search parameters may be required for advanced search queries, but not for basic search queries. Without proper type-checking, it's easy to accidentally omit or include required parameters, leading to bugs and maintenance issues down the line.
Fortunately, TypeScript's advanced type system offers a powerful solution to this problem. By leveraging conditional types, mapped types, and intersection types, we can create type, which enforces parameter requirements at compile time based on a certain condition. We can define configurable objects that are both flexible and type-safe, making our code more reliable and easier to maintain. In this article, we'll explore how to use TypeScript's advanced types, and demonstrate its benefits through real-world examples.

TypeScript Advanced Types Overview

Brief overview of the different advanced types in TypeScript (e.g. mapped types, intersection types).

TypeScript's advanced types are a set of features that extend the type system beyond basic types such as strings, numbers, and booleans. These advanced types offer a more powerful way of describing complex types and defining relationships between them.

There are several advanced types in TypeScript, including:

Mapped Types: A type that transforms the properties of an existing type by mapping them to new properties. For example, a type that makes all properties of an existing type optional, or a type that adds a prefix or suffix to all property names.
Intersection Types: A type that combines two or more types into a single type, where the resulting type includes all properties and methods from each of the input types.

These advanced types can be used together to create complex and flexible types that are adapted to specific use cases.

Creating the type

Step-by-step guide to creating the type mapped types and intersection types.

Let's consider the code below. We'll create the type and name this TConditionalParams
To create TConditionalParams, we'll need to use a combination of mapped types, intersection types. Here's a step-by-step guide to creating the type:

Define the ISomeParams interface, which represents a set of optional parameters:

interface ISomeParams {
  param1: string;
  param2: number;
  param3: string;
}

Define the IAlwaysRequiredParams interface, which represents a set of required parameters:

interface IAlwaysRequiredParams {
  requiredParam: number;
}

Define the TWithCheck type, which represents a set of parameters that require ISomeParams and IAlwaysRequiredParams to be present:

type TWithCheck = {
  checkParams: true;
} & IAlwaysRequiredParams & ISomeParams;

Define the TWithoutCheck type, which represents a set of parameters that only require IAlwaysRequiredParams to be present.

type TWithoutCheck = {
  checkParams: false;
} & IAlwaysRequiredParams;

Finally, define the TConditionalParams type as a union of TWithCheck and TWithoutCheck:

export type TConditionalParams =
  | TWithCheck
  | TWithoutCheck;

With this type definition, we can now create type-safe functions and APIs that allow for configurable objects with parameter requirements that are enforced at compile time. In the next section, we'll explore some examples of using the type in practice.

Explanation of how the type enforces parameter requirements at compile time based on a condition.

The condition in TConditionalParams is defined by the checkParams property, which is a boolean that determines whether to enforce additional parameters. When checkParams is true, the object must include all properties from both IAlwaysRequiredParams and ISomeParams. When checkParams is false, the object must include IAlwaysRequiredParams.

Read world example

Types definition:

interface Product {
  price: number;
  category: string;
  rating: number;
  name: string;
  id: number;
}

interface IAdvancesSearchParams {
  price: number;
  category: string;
  rating: number;
}
interface ISearchParams {
  keywords: string;
}
type TAdvancedSearch = {
  useAdvancedSearch: true;
} & IAdvancesSearchParams &
  ISearchParams;
type TBasicSearch = {
  useAdvancedSearch: false;
} & ISearchParams;
type TProductSearchParams = TBasicSearch | TAdvancedSearch;

Function declaration:

function searchProducts(products: Array<Product>, params: TProductSearchParams): Array<Product> {
  const matchingProducts = products.filter(product => product.name.includes(params.keywords));
  if (params.useAdvancedSearch) {
      if (params.price === undefined || params.category === undefined || params.rating === undefined) {
        throw new Error('Missing required parameters!');
      }
      return matchingProducts.filter(
        product =>
          product.price <= params.price && product.category === params.category && product.rating >= params.rating
      );
    }
    return matchingProducts;
  }

Code usage:

// Valid usage: useAdvancedSearch = true
const advancedResults = searchProducts([], {
  useAdvancedSearch: true,
  keywords: 'organic',
  price: 20,
  category: 'produce',
  rating: 4.5,
});
// Returns an array of products that match the advanced search criteria

// Valid usage: useAdvancedSearch = false
const basicResults = searchProducts([], {
  useAdvancedSearch: false,
  keywords: 'organic',
});
// Returns an array of products that match the basic search criteria

// Invalid usage: useAdvancedSearch = false
const invalidResults = searchProducts([], {
  useAdvancedSearch: false,
  keywords: 'organic',
  price: 20,
});
// Complitation error Object literal may only specify known properties, and 'price' does not exist in type 'TBasicSearch'.

// Invalid usage: useAdvancedSearch = true
const invalidResultsWithAdvancedSearch = searchProducts([], {
  useAdvancedSearch: true,
  keywords: 'organic',
  price: 20,
  category: 'produce',
});
// Compilation error Property 'rating' is missing in type '{ useAdvancedSearch: true; keywords: string; price: number; category: string; }' but required in type 'IAdvancesSearchParams'.

Conclusion

In this article, we've explored how to use TypeScript's advanced types to create the type that enforces parameter requirements at compile time based on a certain condition. With this type, we can define configurable objects that are both flexible and type-safe, improving the reliability and maintainability of our code.
By leveraging mapped types and intersection types, we can create complex and flexible types that are adapted to specific use cases. Using these types, we can enforce parameter requirements at compile time, preventing runtime errors caused by missing or extra parameters. This makes our code more reliable and easier to maintain, especially as our codebase grows in complexity.

Encapsulating Third-Party Libraries for Improved Code Organization and Maintenance

Nick Korolev — Sat, 25 Feb 2023 22:38:25 +0000

Introduction

In today’s fast-paced software development landscape, the use of third-party libraries has become a common practice to speed up the development process. Libraries like day.js, big.js, and moment.js provide a wealth of functionalities that can save a lot of time and effort when developing applications. However, importing these libraries directly into your client code may not always be the best idea.

While it may seem convenient at first, importing libraries directly into your client code can lead to a number of challenges, including difficulties in changing libraries, lack of testability, and poor code organization. To address these issues, it’s essential to encapsulate third-party libraries by creating a separate class and importing the library into this class. This allows you to easily change libraries and write unit tests for the specific functionality you need, while also improving code organization and maintenance.

In this article, we will explore the drawbacks of directly importing third-party libraries into client code and the benefits of encapsulating them. We will also look at how to implement this encapsulation in your own projects.

The drawbacks of importing libraries directly into client code

Difficulty in changing libraries

One of the main drawbacks of importing libraries directly into client code is the difficulty in changing libraries. If a library you have imported directly becomes outdated or you want to switch to a different library, it can be challenging to make the change in your codebase. This is because the library is tightly coupled with the rest of your code and the change can have unintended consequences that affect other parts of your application.

Lack of testability

Another drawback of importing libraries directly into client code is the lack of testability. When a library is imported directly, it can be difficult to write unit tests for the specific functionality you need. This can result in a less reliable and less maintainable codebase, as changes to the library can have unintended consequences on the rest of your application.

By encapsulating the library into a separate class, you can write unit tests for the specific functionality you need, and make changes to the library with confidence, knowing that the impact on the rest of your codebase will be minimized.

The benefits of encapsulating third-party libraries

Improved code organization and maintenance

One of the main benefits of encapsulating third-party libraries is improved code organization and maintenance. By creating a separate class for the library, you can keep the library’s code separate from the rest of your codebase. This makes it easier to understand the structure of your code and to maintain it over time. Additionally, by encapsulating the library, you can abstract away the implementation details and provide a more intuitive and organized API for your code to use. This can lead to a cleaner and more maintainable codebase that is easier to work with.

Improved flexibility and portability

Another benefit of encapsulating third-party libraries is improved flexibility and portability. By abstracting away the implementation details of the library into a separate class, you can more easily switch to a different library if needed. This can be especially useful if a library becomes outdated or if you find a better alternative. Additionally, by encapsulating the library, you can make it easier to reuse your code in different projects or to port it to different platforms. This can save time and effort in the long run and make your code more valuable and reusable.

Improved testing and debugging

Another benefit of encapsulating third-party libraries is improved testing and debugging. By encapsulating the library, you can create unit tests for the library’s behavior and easily isolate and debug issues that arise. This can save time and effort compared to trying to test the library directly, and can lead to a more robust and reliable codebase. Additionally, encapsulating the library can make it easier to simulate different scenarios and edge cases during testing, further improving the quality of your code.

Implementing the encapsulation

Implementing the encapsulation of a third-party library is straightforward and can be done in a few steps. First, you need to create a new class that will act as a wrapper for the library. In this class, you should define all of the methods that you need from the library, and implement them using the library’s API. You should also consider any additional functionality that you might need, such as error handling or default values for certain arguments.

Next, you should import the library into your new class and initialize it. Then, you can write unit tests for the class to ensure that it behaves as expected and covers all of the scenarios that you need. Finally, you can import the new class into your client code, and use its methods in place of direct calls to the library.

By following these steps, you can easily encapsulate a third-party library and enjoy the benefits that this approach offers. Whether you’re working on a new project or adding a library to an existing one, implementing the encapsulation is a simple and effective way to improve the quality and maintainability of your code.

Here’s an example:

import Big from 'big.js';

class MoneyService {
  private value: Big;

  constructor(value: string) {
    this.value = new Big(value);
  }

  public add(value: string): MoneyService {
    this.value = this.value.plus(value);
    return this;
  }
  public subtract(value: string): MoneyService {
    this.value = this.value.minus(value);
    return this;
  }
  public multiply(value: string): MoneyService {
    this.value = this.value.times(value);
    return this;
  }
  public divide(value: string): MoneyService {
    this.value = this.value.div(value);
    return this;
  }
  public toString(): string {
    return this.value.toString();
  }
}

With this implementation, you can use the MoneyService class to perform arithmetic operations on financial values, and the big.js library is encapsulated within the class. This makes it easier to switch to a different library or write unit tests for your financial calculations, as the implementation details are hidden within the MoneyService class.

Conclusion

In this article, we discussed the drawbacks of importing external libraries like directly into client code. We also talked about the benefits of encapsulating the library into a class, like the MoneyService class we implemented. By doing so, we can better manage dependencies, simplify code maintenance, and improve testability. Encapsulating libraries in a service class is a best practice that can greatly improve code quality and make it easier to work with third-party libraries in a scalable and maintainable manner. So, next time you work with a third-party library, consider encapsulating it in a service class for a better development experience.

Additionally, taking the next step and exploring Dependency Injection is also a great way to further encapsulate and manage code. By using Dependency Injection, you can achieve a higher level of decoupling between components and make it easier to maintain your codebase in the long run.