Forem: Ferdy Budhidharma

TypeScript and JSX Part IV - Typing the props of a component

Ferdy Budhidharma — Fri, 25 Jan 2019 02:12:43 +0000

In the last post we learned how TypeScript type checks JSX children with respect to a constructor's props. This time we'll delve deeper into the rest of a component's props and how those are used for typechecking which are valid when creating JSX.

TypeScript treats intrinsic, function, and class components differently when figuring out which attributes can be assigned to a JSX expression constructed by these components.

for intrinsic element constructors (lower-case tag name), it looks at the type of the same property name in JSX.IntrinsicElements
for function element constructors, it looks at the type of the first parameter in the call signature
for class-based element constructors, it looks at the type of the instance property that has the same name under JSX.ElementAttributesProperty, and if that doesn't exist, it will look at the type of the first parameter in the constructor call signature

Let's look at each case in detail:

Intrinsic Element Constructors

If your JSX namespace looks like this:

interface HTMLAttributes<T> {
  children?: ReactNode
  className?: string
  id?: string
  onClick?(event: MouseEvent<T>): void
  ref?: { current?: T }
}

namespace JSX {
  interface IntrinsicElements {
    a: HTMLAttributes<HTMLAnchorElement>
    button: HTMLAttributes<HTMLButtonElement>
    div: HTMLAttributes<HTMLElement>
    span: HTMLAttributes<HTMLElement>
  }
}

Then for an anchor element, the available attributes you can give an <a /> tag equivalent to JSX.IntrinsicElements['a']:

interface AnchorProps {
  children?: ReactNode
  className?: string
  id?: string
  onClick?(event: MouseEvent<HTMLAnchorElement>): void
  ref?: { current?: HTMLAnchorElement }
}

declare const props: AnchorProps

const myAnchor = <a {...props} />

Function Element Constructors

If your component looks like this:

interface Props {
  onClick?(event: MouseEvent<HTMLButtonElement>): void
  disabled?: boolean
  label: string
}

function MyButton(
  props: Props & { children?: ReactNode },
  some?: any,
  other?: any,
  parameters?: any
) {
  return <button />
}

Then the available attributes are Props along with { children?: ReactNode }, because that's the type of the first parameter in the function. Note that TypeScript will respect optional and required properties in the type of the props as well:

const button = <MyButton /> // error because label is marked as required in Props!

Class Element Constructors

If your class looks like this, and you have a JSX namespace like this:

interface Props {
  onClick?(event: MouseEvent<HTMLButtonElement>): void
  disabled?: boolean
  label: string
}

class MyComponent {
  _props: Props

  constructor(props: Props & { children?: ReactNode }) {
    this.props = props
  }

  render() {
    return <button />
  }
}

namespace JSX {
  interface ElementClass {
    render(): any
  }

  interface ElementAttributesProperty {
    _props: {}
  }
}

Then the available attributes for MyComponent are Props (note that this one cannot have children), because the instance type of MyComponent has a property called _props, which is the same as the property name inside JSX.ElementAttributesProperty. If that interface in the JSX namespace wasn't there, it would instead look at the first parameter's type in the constructor, which is Props with { children?: ReactNode }.

This covers all of the "internal" props that a component can use within it. In React, however, we have a concept of "external" props which is the actual contract of what you can pass into a JSX expression constructed by the component. An example of how external props differ from internal props would be ref and key, as well as defaultProps:

ref and key are not available to be used inside a component's implementation, but key can always be assigned to any JSX expression in React, and refs can be assigned to any class-based and intrinsic JSX expressions, as well as function based expressions using forwardRef.
defaultProps allows a specific prop to always be defined inside a component's implementation, but optional when assigning that same prop in a JSX expression of that component.

In the next post we will learn how TypeScript allows this to happen using some more JSX namespace magic.

Creating stores using React context, hooks, and Immer

Ferdy Budhidharma — Sat, 19 Jan 2019 19:43:37 +0000

When creating any medium-to-large React applications, it's useful to have a store to contain your core application data. We don't want to be loading in the same data from APIs in scattered components, and we don't want to have to deal with the prop-drilling problem (passing through props down multiple levels in the React tree).

There are many application data management solutions out there, with Redux and MobX being two of the most popular. In this article we'll be creating our own home-grown store management solution using React context, hooks, and Immer.

Immer is an awesome library that allows you to perform mutations on non-primitive data structures in JavaScript, while still preserving the old data. It does this by creating a "draft copy" of the data structure you want to edit, and crawls through it and creating ES6 proxies to trap any mutations you perform. Those mutations are then recorded and replayed against a deep copy of your original data structure.

To start things off, we will create two React contexts: one to contain the store data, and one to allow editing that data. We'll do this using React's createContext API:

const initialState = {
  /* whatever you want */
}

const StateContext = React.createContext(initialState)
const UpdateContext = React.createContext(null) // soon to be populated with an updater function

We can even be clever and have the UpdateContext provider have a default updater function that throws an error in development mode to ensure that we always have an enclosing provider:

function invariantUpdaterFn() {
  if (process.env.NODE_ENV === 'development') {
    throw new Error('Updater was called without an enclosing provider.')
  }
}
const UpdateContext = React.createContext(invariantUpdaterFn)

Next, we want to encapsulate the two contexts into a single provider, so that they're always paired with each other.

export function StoreProvider({ children }) {
  return (
    <UpdateContext.Provider>
      <StateContext.Provider>{children}</StateContext.Provider>
    </UpdateContext.Provider>
  )
}

But we actually want to add the values for our providers so that they can actually be updated! We can leverage a built-in hook for that:

export function StoreProvider({ children }) {
  const [state, setState] = React.useState(initialState)
  return (
    <UpdateContext.Provider value={setState}>
      <StateContext.Provider value={state}>{children}</StateContext.Provider>
    </UpdateContext.Provider>
  )
}

This approach would work for the simplest kind of updater function, where a consumer can just pass in an entirely new store state and the entire state will be replaced. We want something better though; we want to be able to leverage the functionality of Immer to be able to just edit the state, which gives the user the most power while also preserving the old state. To do that, we can use a reducer function instead, using React's useReducer hook:

import produce from 'immer'

export function StoreProvider({ children }) {
  const [state, updater] = React.useReducer(produce, initialState)
  return (
    <UpdateContext.Provider value={updater}>
      <StateContext.Provider value={state}>
        {children}
      </StateContext.Provider>
    </UpdateContext.Provider>
  )
}

The useReducer hook takes a reducer function as its first parameter, and the initial state as the second parameter. The reducer function itself has a signature that takes the current state as its first parameter, and some kind of action for the second parameter.

The action itself can be anything (in canonical Redux it's a plain object with a type and a payload). In our case however, the action will be some updater function that takes a proxied copy of the state, and mutates it. Luckily for us, that's exactly the same function signature that Immer's produce function expects (because it's modeled as a reducer)! So we can just pass the produce function as-is to useReducer.

This completes the implementation of our provider, which implements the necessary logic to update our store's state. Now we need to provide a way for users to actually be able to grab the store state, as well as update it as necessary. We can create a custom hook for that!

export function useHook() {
  return [useContext(StateContext), useContext(UpdateContext)]
}

This custom hook will return a tuple that can be deconstructed into the state, and the updater function, much like the useState hook.

With our implementation complete, this would be how an application would use this (with our favorite example, the Todo app):

// store.js
import React from 'react'
import produce from 'immer'

// an array of todos, where a todo looks like this: 
// { id: string; title: string; isCompleted: boolean }
const initialTodos = []

const StateContext = React.createContext(initialTodos)
const UpdateContext = React.createContext(null)

export function TodosProvider({ children }) {
  const [todos, updateTodos] = React.useReducer(produce, initialTodos)
  return (
    <UpdateContext.Provider value={updateTodos}>
      <StateContext.Provider value={todos}>
        {children}
      </StateContext.Provider>
    </UpdateContext.Provider>
  )
}

export function useTodos() {
  return [React.useContext(StateContext), React.useContext(UpdateContext)]
}

// app.js
import { TodosProvider } from 'store'

export function App() {
  return (
    <TodosProvider>
      {/* ... some deep tree of components */}
    </TodosProvider>
  )
}

// todo-list.js
import { useTodos } from 'store'

export function TodoList() {
  const [todos, updateTodos] = useTodos()

  const completeTodo = id =>
    updateTodos(todos => {
      todos.find(todo => todo.id === id).isCompleted = true
    })

  const deleteTodo = id =>
    updateTodos(todos => {
      const todoIdxToDelete = todos.findIndex(todo => todo.id === id)
      todos.splice(todoIdxToDelete, 1)
    })

  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}>
          <span>{todo.title}</span>
          <button>Complete</button>
          <button>Delete</button>
        </li>
      ))}
    </ul>
  )
}

It's that easy! Our logic for creating the store is so generic, that we can even wrap it up into our own createStore function:

// create-store.js
import React from 'react'
import produce from 'immer'

export function createStore(initialState) {
  const StateContext = React.createContext(initialState)
  const UpdateContext = React.createContext(null)

  function StoreProvider({ children }) {
    const [state, updateState] = React.useReducer(produce, initialState)
    return (
      <UpdateContext.Provider value={updateState}>
        <StateContext.Provider value={state}>
          {children}
        </StateContext.Provider>
      </UpdateContext.Provider>
    )
  }

  function useStore() {
    return [React.useContext(StateContext), React.useContext(UpdateContext)]
  }

  return { Provider: StoreProvider, useStore }
}

// app.js
import { createStore } from 'create-store'

const TodosStore = createStore([])

export const useTodos = TodosStore.useStore

export function App() {
  return <TodosStore.Provider>{/* ... */}</TodosStore.Provider>
}

// todo-list
import { useTodos } from 'app'

export function TodoList() {
  const [todos, updateTodos] = useTodos()
  /* ... */
}

This approach works very well for small applications, where the React tree is shallow and debugging won't take forever. However for larger applications or larger teams you probably want to use Redux as it enforces a specific style, and also allows you to debug actions better by inspecting the dev tools.

How do you see a list of your own unpublished posts?

Ferdy Budhidharma — Sat, 19 Jan 2019 00:27:49 +0000

It seems that when I save an unpublished post, I get the secret link but unless I save it, I can't see it in my own profile page.

TypeScript and JSX Part III - Typing JSX children

Ferdy Budhidharma — Thu, 17 Jan 2019 23:51:14 +0000

In the last post we learned about what kinds of types can be JSX constructors, and now it's time to dive deeper into how children work.

The concept of children in JSX is interesting: it can both be in the form of a JSX attribute, as well as nested inside an upper-level JSX expression:

// both are valid ways to write children
const myNestedDiv1 = (
  <div>
    <span>I'm stuck!</span>
  </div>
)

const myNestedDiv2 = (
  <div
    children={<span>I'm stuck!</span>}
  />
)

// what gets rendered?
const myNestedDiv3 = (
  <div
    children={<span>Child A</span>}
  >
    <span>Child B</span>
  </div>
)

In myNestedDiv3, the runtime result is ambiguous, and could potentially vary between libraries! Remembering that JSX is just a syntactic sugar, in React we have this:

// before JSX
const myNestedDiv3Untranspiled = (
  <div
    children={<span>Child A</span>}
  >
    <span>Child B</span>
  </div>
)

// after JSX
const myNestedDiv3Transpiled = React.createElement(
  'div',
  { children: React.createElement('span', null, 'Child A') },
  React.createElement('span', null, 'Child B')
)

Thus, it's actually entirely up to the React runtime to figure out how it wants to render the actual markup. It could prioritize over the children prop, or it could prioritize the rest parameters, or it could do some kind of merge of both!

Because the concept of children is not enforced by the JSX specification, TypeScript provides a way to typecheck the nested JSX expressions against the element attributes type. The element attributes type is the type of all attributes added to a JSX expression, i.e. it's the type of the object passed into the second parameter in React.createElement.

This typechecking is done by specifying a property under the JSX namespace (see the previous post for more info on the JSX namespace) called ElementChildrenAttribute. With a guiding example, let's say your JSX namespace is this:

namespace JSX {
  interface ElementChildrenAttribute {
    enfants: {} // 'children' in french
  }
}

And you have a component defined like so:

interface Props {
  enfants?: JSX.Element | JSX.Element[]
  children?: string | string[]
}

function MyComponent(props: Props) { 
  return <div>{props.enfants}</div>
}

Then the following will happen:

// error! the type `string` is not assignable 
// to the type `JSX.Element | JSX.Element[]` for the `enfants` attribute
const myComponentElement1 = <MyComponent>hello world!</MyComponent>

// good! `enfants` is of type `JSX.Element` which is assignable
// to itself or on array of itself
const myComponentElement2 = (
  <MyComponent>
    <MyComponent />
  </MyComponent>
)

So this is TypeScript's way of defining a connection between nested JSX and some property in the interface that you declare.

How is it that when you use React, you always seem to be able to access this.props.children in a React.Component? Well that's actually just part of the React types themselves, and not some intrinsic feature of TypeScript itself. The React type definitions automatically inject children as an optional property for convenience.

In the example above, we defined some function MyComponent that takes a parameter called props with a specific interface. It returns JSX so it's a valid JSX constructor type.

How does TypeScript know that you can't just add any random attribute to a <MyComponent /> element? That enfants, children, and key are the only ones you can add?

In the next post in the series, we'll learn more about how TypeScript collects all of the possible attributes (and their types) you can add to a component element.

TypeScript and JSX Part II - What can create JSX?

Ferdy Budhidharma — Thu, 17 Jan 2019 03:46:48 +0000

In Part I of this series, we learned basic JSX syntax and some basic terminology when discussing the abstract syntax tree of JSX expressions. Let's now dive into how TypeScript checks the type validity of JSX expressions.

Not everything can be valid JSX constructors, you can't just shove any random value into the opening tag of a JSX expression:

// bad! it's actually 'a'
const badAnchor = <anchor href='dev.to'>Go to dev.to!</anchor>

// bad! it's not a function!
const MyComponent = {}
const badFunctionElement = <MyComponent>Hi!</MyComponent>

// bad! it's not something that can render!
class MyClassComponent {
  constructor(props: any) { this.props = props }
}
const badClassElement = <MyClassComponent>Hi!</MyClassComponent>

So how does TypeScript know when something is a valid JSX element constructor? The answer lies in the magical JSX namespace. Remembering how the jsxFactory compiler option (or the @jsx pragma) works, we have that the factory function for React is React.createElement. You might also be using some other library, where the factory function is often called h:

// @jsx React.createElement
import React from 'react'

// @jsx h
import { h } from 'preact'

TypeScript will attempt to look up a namespace called JSX under the factory function and fallback to a global one if none is found:

for factory functions that are under another namespace, like React.createElement, it will look for React.JSX
for factory functions that are just a naked identifier, like h, it will look for h.JSX
if no JSX namespace is found, it looks for a global JSX namespace

The React type definitions declares a global JSX namespace, though that's not a good idea and we should change that soon 😅.

So what's the use of the JSX namespace? TypeScript looks for specific interfaces under it to figure out what's acceptable for each type of JSX element constructor:

for "intrinsic" element constructors (lower-case tag name), it looks if a property with that same key exists under JSX.IntrinsicElements.
for function element constructors, it checks if its return type is assignable to the JSX.Element interface.
for class-based element constructors, it checks if its instance type is assignable to the JSX.ElementClass interface.

Let's look at each case in detail:

Intrinsic Element Constructors

If your JSX namespace looks like this:

namespace JSX {
  interface IntrinsicElements {
    a: HTMLAttributes<HTMLAnchorElement>
    button: HTMLAttributes<HTMLButtonElement>
    div: HTMLAttributes<HTMLElement>
    span: HTMLAttributes<HTMLElement>
  }
}

Then you can render these elements:

const validIntrinsicElements = [<a />, <button />, <div />, <span />]
// error properties 'select', 'main', and 'nav' do not exist on type 'JSX.IntrinsicElements'
const invalidIntrinsicElements = [<select />, <main />, <nav />]

We'll talk about what the types of the properties themselves actually mean in the next part of the series.

Function Element Constructors

If your JSX namespace looks like this:

namespace JSX {
  interface Element {
    key?: string
    type: string | (() => any)
    props: { [propName: string]: any }
  }
}

And you have a function like this:

function MyComponent(props: any) {
  return {
    type: MyComponent,
    props: props
  }
}

Then you have a valid constructor! Because its return type is assignable to JSX.Element:

const myFunctionElement = <MyComponent /> // good to go!

How is it though, that when you have a function without its return type annotated, but it returns JSX, it's still okay? That's because TypeScript will treat any JSX expression's type to be the same type as JSX.Element!

function MyComponent() {
  return <div>Hi!</div>
}

const myFunctionElement = <MyComponent /> // still okay

const nakedElement = <div>hi!</div>
type NakedElementType = typeof nakedElement // the type is JSX.Element

An astute reader will notice that this has some odd pitfalls when it comes to what React allows you to return from a component. Remember that React allows you to return arrays, strings, numbers, and booleans from a component, which it will happily render:

function MyStringFragment() {
  return ['a', 'b', 'c'] // type is string[]
}

const myFragment = <MyStringFragment /> // TS error!

Uh oh, this is an unfortunate limitation of the type checker; if we want to get the check to pass, we need to assert the type of the return value:

function MyStringFragment() {
  return ['a', 'b', 'c'] as any as JSX.Element
}

const myFragment = <MyStringFragment /> // good now!

There is an open issue for the TypeScript repo that will hopefully resolve this issue in the future: https://github.com/Microsoft/TypeScript/issues/14729.

Class Element Constructors

If your JSX namespace looks like this:

namespace JSX {
  interface ElementClass {
    render(): any
  }
}

And you have a class like this:

class Component {
  constructor(props: any) {
    this.props = props
  }

  render() {
    return { obviouslyNotAnElement: 'fooled ya!' }
  }

  someOtherMethod(): string
}

Then you have a valid constructor! Because its instance type is assignable to JSX.ElementClass:

const myComponentInstance = new Component({})

type myComponentInstanceType = {
  render(): { obviouslyNotAnElement: string }
  someOtherMethod(): string
}

type ComponentInstanceType = {
  render(): any
}

Obviously the real React type is different, but that's why we always extend from React.Component, because this is what it roughly looks like in React's types:

namespace React {
  type Renderable = JSX.Element | JSX.Element[] | number | string | boolean | null
  class Component {
    /* other methods like setState, componentDidUpdate, componentDidMount, etc */
    render(): Renderable
  }

  namespace JSX {
    interface ElementClass {
      render(): Renderable
    }
  }
}

And now any class that you declare that extends React.Component will be a valid constructor!

In summary: before we even talk about props, TypeScript has to check if a component is actually a valid JSX constructor, otherwise it rejects it when you try to use it in a JSX expression.

In the next post in this series, we'll be talking about what TypeScript considers to be valid attributes given a specific JSX expression (remember: attributes are the props you give to a JSX expression, like HTML element attributes).

TypeScript and JSX Part I - What is JSX?

Ferdy Budhidharma — Wed, 16 Jan 2019 02:16:34 +0000

As of 2019, TypeScript has grown more and more popular as the programming language of choice for web developers. In this post series we'll be exploring how the TS compiler treats JSX and how it all interacts with the most popular framework that utilizes JSX: React.

First things first-- how does JSX work? Here are a couple of examples of JSX:

// a native 'span' element with some text children
const mySpan = <span>Hello world!</span>

// a custom 'CustomSpan' element with some props and some children
const myCustomSpan = (
  <CustomSpan
    key='_myspan'
    bold
    color="red"
  >
    Hello world!
  </CustomSpan>
)

// a native, self-closing 'input' element without any children
const myInput = <input />

// a custom 'Container' element with multiple children
const myWidget = (
  <Container>
    I am a widget
    <Button>Click me!</Button>
  </Container>
)

JSX is a non-ECMAScript compliant syntax addition to JavaScript, which is supported by TypeScript through the --jsx compiler flag. If you're a React developer, then JSX is actually just syntactic sugar that will compile down to this (if you use the TypeScript compiler):

// a native 'span' element with some text children
const mySpan = React.createElement('span', null, 'Hello world!')

// a custom 'CustomSpan' element with some props and some children
const myCustomSpan = React.createElement(
  CustomSpan,
  { key: 'myspan', bold: true, color: 'red' },
  'Hello world!'
)

// a native, self-closing 'input' element without any children
const myInput = React.createElement('input', null)

// a custom 'Container' element with multiple children
const myWidget = React.createElement(
  Container,
  { onClick: console.log },
  'I am a widget',
  React.createElement(Button, null, 'Click me!')
)

This is already quite a lot to dissect; let's note some interesting things in this transform:

The entire JSX expression is turned into a call against a function called React.createElement. This is actually why you always need to import React from 'react' if you use JSX, even though the variable React never actually gets used in your code!
The tag name in the JSX expression is moved to the first parameter of the function call.
- If the tag name begins with an uppercase character, or (not shown in the example) it is a property access (like <foo.bar />), it is left as is.
- If the tag name is a single lowercase word, it is turned into a string literal (input -> 'input')
All of the props (or attributes, as they are called in the abstract syntax tree) are transformed into an object that is moved to the second parameter of the function call, with some special syntax to note:
- If no props are passed in, the value is not an empty object, nor undefined, but just null.
- Shorthand attribute syntax (like the bold prop in myInput), is transformed into just an objet property with the value true.
- Even though React treats key and ref as special, they are still (as far as syntax is concerned) regular attributes in the transform.
- The order of the object's properties is the same order that they appear as attributes in the JSX expression.
Children are transformed if needed (if they are also JSX), and are placed in the order that they appear, as the rest of the arguments to the function call.
- React has a specific behavior where a single child in JSX appears as just that node in props.children, but as an array of nodes for multiple children. This is not enforced by the syntax or specification at all. In fact, Preact will always wrap children in an array regardless of how many there are, so that part is an implementation detail.

That's really all there is to JSX syntax; at the end of the day it's just syntactic sugar for building nested function calls without hurting your brain.

Why is it then, does the compiler know to use React.createElement as the function instead of something else? Turns out that you can change that to whatever you want! All you have to do is add either a comment at the top of your file or set a compiler flag:

/* @jsx myCustomJsxFactory.produce */

// your code here

// tsconfig.json
{
  "compilerOptions": { "jsxFactory": "myCustomJsxFactory.produce" }
}

They do the same thing, and it just turns out that the default value is React.createElement.

In the next posts in the series, we'll be exploring how TypeScript knows how typecheck against JSX syntax through a working example of building our own JSX factory function.