TypeScript guidelines

Monorepo TypeScrypt-cheatsheet

Table of Contents

• Basics
• Monorepo Pages
  • getInitialProps definitions
  • Component declaration
• React Hooks types
  • useState
  • useRef
• Redux
  • actions
  • reducers
  • selectors
• Interface vs Type vs Class
  • Interface declarations
  • Interface with multiple types
  • Types
    • Types alias
    • Tuples
    • Conditional types
    • Mapped types
    • Exclude
    • Extract
    • Instance type
  • Class
  • Types or Interfaces?
  • Other types
    • Enums
• Functions
• Unions
• Cheat sheet

Basics

• Avoid using any, object or unknown types.
• In shared packages we can export types from the components folder that we want to import into other projects

// TodayTix component file:
import { CookieBannerLabels } from '@todaytix/shared/src/types';

const Labels: CookieBannerLabels = {} as CookieBannerLabels;

Pages

getInitialProps function

• Always declare context type with TTNextPageContext, AppContext or NextPageContext

PageName.getInitialProps = async (ctx: TTNextPageContext)

• Always return with the type

Promise < { props: PageProps<ModelName> } >
Promise < InitialProps < PageModel >>
Promise < InitialProps < PageProps < ModelName >>>
Promise < ModelName >

// Eg:
PageName.getInitialProps = async (ctx: TTNextPageContext): Promise<InitialProps<PageModel>>
{
}

Component declarations (See Interfaces vs types)

• Always declare prop types for custom props types and without inheritance

• Add return ReactElement types to components

import { ReactElement } from 'react';

type PropType = {
};
const ComponentName = (props: PropType): ReactElement

Hooks

useState

• Always declare the type when creating a new state

interface User {
  name: string;
  age: number;
}
const [user, setUser] = useState<User | null>(null);

// later...
setUser(newUser);

useRef

function Foo() {
  // - If possible, prefer as specific as possible. For example, HTMLDivElement
  //   is better than HTMLElement and way better than Element.
  // - Technical-wise, this returns RefObject<HTMLDivElement>
  const divRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    // Note that ref.current may be null. This is expected, because you may
    // conditionally render the ref-ed element, or you may forgot to assign it
    if (!divRef.current) throw Error('divRef is not assigned');

    // Now divRef.current is sure to be HTMLDivElement
    doSomethingWith(divRef.current);
  });

  // Give the ref to an element so React can manage it for you
  return <div ref={divRef}>etc</div>;
}

Redux

Actions

• declare an interface / contract for our redux action and action creator returns

interface Response {
  code: number;
  isOpen: boolean;
}

enum menuTypes {
  OPEN = "OPEN",
  CLOSE = "CLOSE",
}

export interface MenuOpenAction {
  type: menuTypes;
  payload?: Response;
  error?: string;
}

const openMenuAction = (): MenuOpenAction => ({
  type: menuTypes.OPEN,
  payload: {
    code: 201,
    isOpen: true
  }
}); 

Reducers

• Declare state type / contract

interface ResponseState {
  payload: Response;
}

const initalState: ResponseState = {
  code: 404,
  response: null
}

• On the reducer function use the action and state interfaces

const menuReducer = (
  state = initialState,
  action: MenuOpenAction,
): ResponseState => {};

Selectors

• In rootReducer.ts file we need to create a type for the state

const rootReducers = combineReducers({ Shows, Menu });
export type RootReducer = ReturnType<typeof rootReducers>;

or

const reducer = combineReducers({
  checkout,
  content,
  viewer,
});
export type StateType = ReturnType<typeof reducer>;

• Then use the state type in the selectors

import { StateType } from './rootReducer';

const selectMenuState = (state: StateType): Response => get(state, 'menu', {} as MenuState);

Interfaces

Interface declaration

class Someclass {}

interface Parent {
  parentProperty: Type;
  x: number;
  y: number;
  z?: number;
}

interface Child extends Parent, SomeClass {
  property: Type;
  optionalProp?: Type;
  optionalMethod?(argument: Type): ReturnType;
}

const myConst: Child; // { parentProperty, x, y, z, property, optionalProp, optionalMethod}

class MyClass implements Child {
  public parentProperty: Type;
  public x: number;
  public y: number;
  public property: Type;
  public optionalProp: Type;

  public optionalMethod(argument: Type): ReturnType {
    const myConst: Type;

    return myConst;
  }
}

• Interfaces can also extend other interfaces or classes using the extends keyword in order to compose more complex types out of simple types

Interface with multiple types

interface Pair<T1, T2> {
  first: T1;
  second: T2;
}

const myConst: Pair<number, string>; // {first, second} where first is a number and the second a string

Types

Type alias

type Name = string;

type Direction = 'left' | 'right';

type ElementCreator = (type: string) => Element;

type Point = { x: number; y: number };

type Point3D = Point & { z: number };

type PointProp = keyof Point; // 'x' | 'y'

const point: Point = { x: 1, y: 2 };

type PtValProp = keyof typeof point; // 'x' | 'y'

Basic tuples

let myTuple: [string, number, boolean?];
myTuple = ['test', 42];

Variadic tuples

type Numbers = [number, number];
type Strings = [string, string];

type NumbersAndStrings = [...Numbers, ...Strings]; // [number, number, string, string]
let myTuple: NumbersAndStrings;
myTuple = [1, 2, 'test1', 'test2'];

Conditional types

type Swapper = <T extends number | string>(
  value: T,
) => T extends number ? string : number;

equivalent to (if T is Number) (value: number) => number equivalent to (if T is String) (value: string) => string

Conditional mapped types

interface Person {
  firstName: string;
  lastName: string;
  age: number;
}

type StringProps<T> = {
  [K in keyof T]: T[K] extends string ? K : never;
};

type PersonStrings = StringProps<Person>;

// PersonStrings is "firstName" | "lastName"

Exclude

type Excluded = Exclude<string | number, string>; equivalent to number

Extract

type Extracted = Extract<string | number, string>; equivalent to string

InstanceType

class Renderer() {}
type Instance = InstanceType<typeof Renderer>;

is equivalent to

Renderer

Class

interface Child {
  methodProperty: (argument: Type) => ReturnType;
}

interface OtherChild {
  overloadedMethod(argument: Type): ReturnType;
}

class Parent {}

class Child extends Parent implements Child, OtherChild {
  public property: Type;
  public argument: Type;
  public defaultProperty = 'default value';
  static staticProperty: Type;
  private readonly _privateReadonlyProperty: Type;
  private _privateProperty: Type;

  constructor(argument: Type, public argumentTwo) {
    super(argument);
    this.argument = argument;
  }

  static staticMethod(): ReturnType {}
  private _privateMethod(): Type {}

  public methodProperty: (argument: Type) => ReturnType;
  public overloadedMethod(argument: Type): ReturnType;
  public overloadedMethod(argument: OtherType): ReturnType;
  public overloadedMethod(argument: CommonT): CommonReturnT {}
}

Types or Interfaces?

If you would like a heuristic (practical), use interface until you need to use features from type.

Here's a helpful rule of thumb:

1. Always use interface for public API's definition when authoring a library or 3rd party ambient type definitions, as this allows a consumer to extend them via declaration merging if some definitions are missing.
2. Consider using type for your React Component Props and State, for consistency and because it is more constrained.

Interface work better with objects and method objects, and types are better to work with functions, complex types, etc. You should not start to use one and delete the other. Instead of doing that, start to refactor slowly, thinking of what makes more sense to that specific situation.

Useful table for Types vs Interfaces

It's a nuanced topic, don't get too hung up on it. Here's a handy table:

Aspect	Type	Interface
Can describe functions	✅	✅
Can describe constructors	✅	✅
Can describe tuples	✅	✅
Interfaces can extend it	⚠️	✅
Classes can extend it	🚫	✅
Classes can implement it (implements)	⚠️	✅
Can intersect another one of its kind	✅	⚠️
Can create a union with another one of its kind	✅	🚫
Can be used to create mapped types	✅	🚫
Can be mapped over with mapped types	✅	✅
Expands in error messages and logs	✅	🚫
Can be augmented	🚫	✅
Can be recursive	⚠️	✅

⚠️ In some cases

(source: Karol Majewski)

Types Interface Equivalent

Other types

Arrays and tuples

Array of strings

string[] or Array<string>

Array of functions that return strings

tsx (() => string)[] or { (): string; }[] or Array<() => string>

Enums

// bad: lowercase enum names
enum options {}

// good: PascalCase (the first letter of every word is uppercase)
enum Options {}

// bad: properties in lower case
enum Colors {
   red = '#FF0000', 
}

// good: properties in PascalCase or UPPERCASE
enum Colors {
  Red = '#FF0000',
}

enum Colors {
  RED = '#FF0000',
}

// eg: different types of enums
enum Options {
  FIRST,
  EXPLICIT = 1,
  BOOLEAN = Options.FIRST | Options.EXPLICIT,
  COMPUTED = getValue(),
}

enum Colors {
  Red = '#FF0000',
  Green = '#00FF00',
  Blue = '#0000FF',
}

Functions

Function type

(argument: Type, argN: Type) => Type; or (argument: Type, argN: Type): Type;

Function type with optional param

(argument: Type, optional?: Type) => ReturnType

Function type with rest param

(argument: Type, ...allOtherArgs: Type[]) => ReturnType

Default argument

function myFunction(argument = 'default'): ReturnType {}

Arrow function

(argument: Type): ReturnType => { ...; return value; } or (argument: Type): ReturnType => value

Overloads

function myFunction(a: string): number;
function myFunction(a: number): string;
function myFunction(a: string | number): string | number {
    ...
}

Union and intersection types

Union

let myUnionVariable: number | string;

Intersection

let myIntersectionType: Foo & Bar;

Utility types

Partial

Partial<{ x: number; y: number; z: number; }> equivalent to { x?: number; y?: number; z?: number; }

Readonly

Readonly<{ x: number; y: number; z: number; }> equivalent to

{
    readonly x: number;
    readonly y: number;
    readonly z: number;
}

Record

Record<'x' | 'y' | 'z', number> equivalent to { x: number; y: number; z: number; }

Assertions / Cast

let val = someValue as string;

Ambient declarations

Global

declare const $: JQueryStatic;

Module

declare module "foo" {
    export class Bar { ... }
}

Handbook Cheat sheet

Sources:

• TypeScript-React cheat sheet.
• Differences between types-aliases
• TypeScript HandBook