Forem: Maciej Smoliński

Building type utils - deriving interfaces from union types in TypeScript

Maciej Smoliński — Sun, 29 May 2022 23:06:48 +0000

In this post, we're going to build small, generic type utils in TypeScript.

To work with a real use case, we're going to transform a non-generic code from my previous post into a generic type utility, that could work with more input types, and thus be more reusable.

type Dispatcher = {
  [Message in Action as Message['type']]: Message extends { payload: any }
    ? (payload: Message['payload']) => void
    : () => void;
};

Non-generic code, hard to re-use ⤴

There are many ways to achieve this goal. We're going to pick a fancy one, leveraging template literals, and type inference to provide a nice development experience:

type Dispatcher =
  ValuesAsCallbacks<UnionToKeyValue<Action, 'type:payload'>>;

Reusable, generic type utilities ⤴

Now, let's see how to build that 🤔

A two-step process

First, let's break down the process of turning one type into another. We'll look into the implementation and more detailed explanation in the next section.

1️⃣ Union to Key-Value

First, we're turning union into a key-value interface by providing a colon-delimited string literal, defining the property to be used as a key and the property to be used as a value. In case the property is missing on an item from the union, we're going to represent this fact with the never type:

type Action =
  | { type: 'reset' }
  | { type: 'setValue'; payload: string }
  | { type: 'setSelection'; payload: [number, number] | null }
  | { type: 'trimWhitespace'; payload: 'leading'|'trailing'|'both' };

type IntermediateResult = UnionToKeyValue<Action, 'type:payload'>;
         ▲
┌───────────────────────────────────────────────────────────────────┐
│ type IntermediateResult = {                                       │
│   reset: never;                                                   │
│   setValue: string;                                               │
│   setSelection: [number, number] | null;                          │
│   trimWhitespace: 'leading'|'trailing'|'both';                    │
│ }                                                                 │
└───────────────────────────────────────────────────────────────────┘

Can you already see how that is going to turn into an interface with callbacks?

2️⃣ Values As Callbacks

Second, we're transforming that key-value interface into key-callback interface, where the callback function in the latter is accepting a parameter of the same type as the value in the former:

type IntermediateResult = {
  reset: never;
  setValue: string;
  setSelection: [number, number] | null;
  trimWhitespace: 'leading'|'trailing'|'both';
}

type Dispatcher = ValuesAsCallbacks<IntermediateResult>;
         ▲
┌───────────────────────────────────────────────────────────────────┐
│ type Dispatcher = {                                               │
│   reset: () => void;                                              │
│   setValue: (payload: string) => void;                            │
│   setSelection: (payload: [number, number] | null) => void;       │
│   trimWhitespace: (payload: 'leading'|'trailing'|'both') => void; │
│ }                                                                 │
└───────────────────────────────────────────────────────────────────┘

Implementation, and a bit of explanation

Union to Key-Value

Let's take a look at how to implement the first utility type 🕵️

type UnionToKeyValue<
  T extends { [key: string]: any },  ①
  K extends string  ②
> = ...

(1) The util accepts an interface, or a union of interfaces, indexed by keys being strings or string literals as a first parameter.

(2) It also requires a second parameter to be a string, or a string literal.

... = K extends `${infer Key}:${infer Value}`  ③
  ? Key extends keyof T  ④
    ? ...
    : never
  : never;

(3) Key and Value never appeared as a type parameter of the util. Thanks to template literal types, we can infer both from the type provided as the second parameter, so long as it's a string or a string literal, and it contains a colon somewhere inside.

Given 'type:payload' provided as a second parameter, we're going to infer that Key is 'type' and Value is 'payload'.

If we don't find a colon in the second parameter, we fail to pattern-match and we return never.

(4) Next, with the inferred Key, we double-check it belongs to the key set of the first parameter, T — an interface, or a union of interfaces. If it does not belong there, we return never.

? { [A in T as A[Key]]: Value extends keyof A ? A[Value] : never }  ⑤
...

(5) Now, we use mapped types to iterate through T, which implies T must be a union of types rather than a single interface to make mapping possible. With an interface, we'd see the use of keyof there.

The use of as combined with indexed access A[Key] also gives a clue about elements of the union being interfaces and not primitive types such as undefined or null.

Finally, if A[Key] does not exist in the element, we're not going to include it in the output. We're not that strict with the Value, if A[Value] does not exist, we represent that as never.

Final code

type UnionToKeyValue<
  T extends { [key: string]: any },
  K extends string
> = K extends `${infer Key}:${infer Value}`
  ? Key extends keyof T
    ? { [A in T as A[Key]]: Value extends keyof A ? A[Value] : never }
    : never
  : never;

That's most of the heavy work done!

Values as Callbacks

Going from interfaces to interfaces should be slightly easier, let's take a look.

type ValuesAsCallbacks<T extends { [key: string]: any }> = ...  ①

(1) This util accepts only one parameter, that must represent an interface with keys being strings or string literals and no constraints on the values.

... = {
  [K in keyof T]: T[K] extends never  ②
  ? () => void ③
  : (payload: T[K]) => void;  ④
};

(2) T is an interface, we iterate through all keys of the provided type, represented as K. Now, we check if the value, T[K], has type never.

(3) If we detect the value is of the type never, we return a type representing a callback not accepting any parameters.

(4) Otherwise, we return a type representing a single-parameter callback, where the parameter has the same type as the value in the original interface.

Final code

type ValuesAsCallbacks<T extends { [key: string]: any }> = {
  [K in keyof T]: T[K] extends never 
  ? () => void 
  : (payload: T[K]) => void;
};

That was it, the last missing piece in the puzzle of turning the union of interfaces into an interface with callbacks 🎉 We made it!

Complete Code

The complete code listing from this post can be found under this link:

Reusable types from this post in TypeScript playground ⤴

Final words

Now that you've explored one approach, I would encourage you to try other approaches, for example, splitting UnionAsKeyValue<T, K> into two separate utils and see how you find it.

Good luck!

Deriving types from other types in TypeScript — unions and interfaces

Maciej Smoliński — Fri, 20 May 2022 21:54:14 +0000

Maintaining a lot of similar types can be a mundane task, especially if some of them must stay in sync due to some dependency on one another.

You're going to learn how to, with a little bit of type-level programming, reduce that toil by deriving types from other types.

More specifically, I'm going to show how to, at type-level, turn union type into an interface, as well turn an interface into union type, and where that could be useful.

The transition from union type to interface, and back

💡 This post is going to show the practical use of mapped types, key remapping, indexed access, and conditional types from TypeScript

Use Case

Imagine we're building a simple text editor. We're going to keep track of its contents as well as the current selection, which could come in handy in the future if we decided to, for example, introduce text formatting support.

We can represent these requirements with the following interface:

interface EditorState {
  content: string;
  selection: [number, number] | null;
}

State transitions

In terms of interactions, we want to start with three basic cases:

Storing and updating the content
Storing and updating the active selection
Resetting the state of the editor

Our application is going to dispatch a message, often referred to as action, for each interaction type.

In order to distinguish one action from another, each message is going to include a type field, as well as, optionally, a payload field carrying extra information related to the message.

type Action
  = { type: 'reset' }
  | { type: 'setValue', payload: string }
  | { type: 'setSelection', payload: [number, number] | null };

💡 Why union type instead of interface?

Another option would be to create an interface with a type field defined as 'reset' | 'setValue' | 'setSelection' , and an optional payload field accepting any type.

However, with such a generic type we would lose a lot guarantees, and the type checker wouldn't complain about, for example, a reset action with extra payload, or a setValue action carrying numeric payload.

Current and future state

Reducer, a term often used by state management libraries, is nothing else than a regular function that accepts the current state, the action, and produces a new state.

With precise definitions of state and actions, we implement a simple reducer for the text editor returning different states for each of the actions:

function reducer(state: EditorState, action: Action): EditorState {
  switch (action.type) {
    case 'reset':
      return { ...state, content: '', selection: null };
    case 'setValue':
      return { ...state, content: action.payload };
    case 'setSelection':
      return { ...state, selection: action.payload };
    default:
      return state;
  }
}

Putting things together

Next, we'd like to expose a way of dispatching actions from the UI, so that we can actually modify the state. We're going to use React and the useReducer to keep the code nice and short.

import { useReducer } from 'react';

// ...

function Editor() {
  const initialState = { content: '', selection: null };
  const [state, dispatch] = useReducer(reducer, initialState);

  return (
    <div className="editor">
      <div className="editor__menu">
        <button>Reset</button>
      </div>
      <div className="editor__input">
        <textarea></textarea>
      </div>
    </div>
  );
}

The dispatch function is going to accept an Action as a parameter, and cause the state of the editor to update:

dispatch({ type: 'reset' });
// state becomes { content: '', selection: null }

dispatch({ type: 'setValue', payload: 'Some text' });
// state becomes { content: 'Some text', selection: null }

dispatch({ type: 'setSelection', payload: [3, 8] });
// state becomes { content: 'Some text', selection: [3, 8] }

We can use this knowledge to add behavior to the component we've previously built.

- <button>Reset</button>
+ <button onClick={() => dispatch({ type: 'reset' })}>Reset</button>

- <textarea></textarea>
+ <textarea
+   value={state.content}
+   onChange={({ target }) => {
+     const element = target as HTMLTextAreaElement;
+ 
+     dispatch({ 
+       type: 'setValue',
+       payload: element.value || ''
+     });
+   }}
+   onSelect={({ target }) => {
+     const element = target as HTMLTextAreaElement;
+     const { selectionStart, selectionEnd } = element;
+ 
+     dispatch({
+       type: 'setSelection',
+       payload: [selectionStart, selectionEnd],
+     });
+   }}
+ ></textarea>

Dispatcher Interface

It would be convenient to have a set of methods allowing us to build and dispatch these actions more easily, for example:

interface Dispatcher {
  reset: () => void;
  setValue: (payload: string) => void;
  setSelection: (payload: [number, number] | null) => void;
}

Besides hiding implementation details, we would also save a bunch of keystrokes, let's take setting selection as an example:

  <textarea
    ...
    onSelect={({ target }) => {
      const element = target as HTMLTextAreaElement;
      const { selectionStart, selectionEnd } = element;

-     dispatch({
-       type: 'setSelection',
-       payload: [selectionStart, selectionEnd],
-     });
+     actions.setSelection([selectionStart, selectionEnd]);
    }}
  ></textarea>

Limitations of the hand-written types

Unfortunately, creating the Dispatcher type by hand can be error-prone and introduce a bit of toil.

What if we decide to add a new action?

type Action
  = { type: 'reset' }
  | { type: 'setValue', payload: string }
  | { type: 'setSelection', payload: [number, number] | null }
+ | { type: 'trimWhitespace' }

Dispatcher does not support it out of the box, and therefore we have to expand the type accordingly

interface Dispatcher {
  reset: () => void;
  setValue: (payload: string) => void;
  setSelection: (payload: [number, number] | null) => void;
+ trimWhitespace: () => void
}

Now, what if the signature of one of the action changes?

type Action
  = { type: 'reset' }
  | { type: 'setValue', payload: string }
  | { type: 'setSelection', payload: [number, number] | null }
- | { type: 'trimWhitespace' }
+ | { type: 'trimWhitespace', payload: 'leading' | 'trailing' | 'both' }

We get no warnings. Dispatcher type is not in sync with the latest changes whatsoever 😢

Evolution with dynamic dispatcher type

To make the code less error-prone and avoid the toil of having to update types every time one of them changes, we can delegate the job of building the Dispatcher type to the type system.

The tools we're going to use are mapped types, key remapping, and conditional types:

type Dispatcher = {
  [Message in Action as Message['type']]: 
    Message extends { payload: any }
    ? (payload: Message['payload']) => void
    : () => void
}

Now, while hovering over the dispatcher type, we're going to see a dynamically generated type from the union type matching our requirements:

┌───────────────────────────────────────────────────────────────────┐
│ type Dispatcher = {                                               │
│   reset: () => void;                                              │
│   setValue: (payload: string) => void;                            │
│   setSelection: (payload: [number, number] | null) => void;       │
│   trimWhitespace: (payload: 'leading'|'trailing'|'both') => void; │
│ }                                                                 │
└───────────────────────────────────────────────────────────────────┘
         ▼
type Dispatcher = {

Goal achieved, we've mapped union type into an interface with callbacks derived from the payload in the original type 🎉

What about the other direction?

Now, what if we started with the dispatcher, and would like to derive a union of possible actions from it?

type Dispatcher = {
  reset: () => void;
  setValue: (payload: string) => void;
  setSelection: (payload: [number, number] | null) => void;
  trimWhitespace: (payload: 'leading' | 'trailing' | 'both') => void;
}

type Action = ?

Let's check the facts — we know the keys of the interface correspond to the type of the action, and we also know the parameter of the function, when present, defines the type of the payload.

This is enough information to derive the union from
the interface, let's see:

type Action = {
  [Key in keyof Dispatcher]: 
    Dispatcher[Key] extends () => void
    ? { type: Key }
    : { type: Key, payload: Parameters<Dispatcher[Key]>[0] }
}[keyof Dispatcher]

Now, let's hover over the dynamically computed Action type to see if it matches our expectations:

┌─────────────────────────────────────────────────────────────────────┐
│ type Dispatcher =                                                   │
│  | { type: "reset" }                                                │
│  | { type: "setValue"; payload: string }                            │ 
│  | { type: "setSelection"; payload: [number, number] | null }       │
│  | { type: "trimWhitespace"; payload: 'leading'|'trailing'|'both' } │
│ }                                                                   │
└─────────────────────────────────────────────────────────────────────┘
         ▼
type Action = {

It indeed satisfies our requirements 🎉

Summary

We've seen examples of how to transform a union type into an interface, as well as how an interface can be turned into a union type.

Type-level programming in TypeScript feels like a superpower, with a bit of use of mapped types and conditional types we are able to derive new types from existing types.

That's what we do every day when we work with values while programming, we process the values, we transform them, and we compute new values from other values.

I hope the example I used for presenting the transformation gave you a clearer picture of some of the extra capabilities of TypeScript.

I purposefully refrained from walking the reader line by line through the code examples. I believe some of these concepts can be better learned by examining the behavior of the code in a live environment. Therefore, I leave this part of the study as an exercise for the reader.

I promised you're going to learn how to turn union types into interfaces, and back, and explain where that could be useful, and I hope I delivered.

Please let me know your thoughts!

Bonus: Live version of the code

You can find a live version of this code on CodeSandbox:

Code from this post in action on CodeSandbox

Integrate PureScript with your JavaScript application

Maciej Smoliński — Tue, 17 Jul 2018 15:09:02 +0000

PureScript is a strongly-typed functional programming language that compiles to JavaScript. It means we can benefit from the type safety not only in new, but also existing applications.

PureScript has a top-notch FFI (Foreign-Function Interface) allowing us to call JavaScript functions from within PureScript. Not only this but we can also use PureScript modules from JavaScript.

Installing PureScript

First, we need to install global dependencies — the PureScript compiler, the package manager and the build tool: yarn global add purescript@0.11.7 psc-package pulp.

Generating project structure

Pulp, the build tool, allows us to generate a basic project structure by running a single command: pulp --psc-package init.

It will create the src and test directories as well as psc-package.json containing a list of dependencies. Once created, pulp will install PureScript packages to .psc-package directory.

You can now compile and run src/Main.purs by typing pulp --watch run. After modifying the contents of src/Main.purs, pulp will automatically recompile and run the module.

Installing code bundler

Since we'd like to build a JavaScript application that integrates with PureScript, a code bundler will come in handy.

Parcel helps to effortlessly transpile ES6 code, bundle modules and automatically reload the code in the browser with no extra configuration. You can install Parcel with yarn add parcel.

Defining npm script and running the bundler

Once installed, it is often a good practice to add a script to the package.json file so that we can easily run the bundler. We're going to define dev script that will bundle the code and serve the application on port 1234 after running yarn run dev in the terminal.

// package.json
"scripts": {
  "dev": "parcel serve src/index.html"
}

Next, we create src/index.html

<!-- src/index.html -->
<html>
  <head>
    <title>PureScript Application</title>
  </head>

  <body>
    <script src="./index.js"></script>
  </body>
</html>

And src/index.js

// src/index.js
console.log('Hello from JavaScript');

Now, after executing yarn run dev, a very basic JavaScript application is up and running on http://localhost:1234/.

Calling PureScript from JavaScript

Now, the final step. We'd like to execute PureScript code from src/Main.purs in our JavaScript application. We still want yarn run dev to be running in the background.

However, instead of running pulp --watch run and executing the PureScript code, we're going to run pulp --watch build to build the code and skip the execution part.

The PureScript module

Now, when both commands are running in the background, we can have a look at our src/Main.purs module.

module Main where

import Prelude
import Control.Monad.Eff (Eff)
import Control.Monad.Eff.Console (CONSOLE, log)

main :: forall e. Eff (console :: CONSOLE | e) Unit
main = do
  log "Hello from PureScript!"

Essentially, we can tell the module is named Main and it only has a single method called main. It imports a bunch of other modules in order to tell the compiler the main function is effectful and the particular side effect involved is JavaScript console. It also imports the log function which takes a string and prints it in the JavaScript console. The main function doesn't produce any value hence the Unit in the type definition.

Importing the module

Next, after we understood the PureScript module, we can import the compiled output from our JavaScript file.

// src/index.js
const Main = require('../output/Main/index');

console.log('Hello from JavaScript');

Main.main();

After opening the browser window again, we can see both the JavaScript code we wrote by hand and the JavaScript code produced by the PureScript compiler both executed and printed text to the JavaScript console.

Excellent! We just integrated existing JavaScript code with PureScript. Now we're free to write in both languages. We can also gradually introduce PureScript in some areas of our codebase as we learn the language.

Next steps

We learned integrating PureScript code with JavaScript doesn't have to be a difficult task. Parcel and Pulp make it a simple process. Parcel's documentation also explains how to bundle our application for production.

When it comes to learning PureScript, I highly recommend the "PureScript by Example" book by Phil Freeman, the creator of the language. It's a fantastic resource for learning the language as well as functional programming concepts in general!

Good luck!