-
Object is the type of all instances of class Object OR Contains stuff (like
toString(),hasOwnProperty()) that is present in all JavaScript objects. Any value (primitive, non-primitive) can be assigned toObjecttype.- It describes functionality that is common to all JavaScript objects
- It includes primitive values
const obj = {}; obj instanceof Object; // true obj.toString === Object.prototype.toString; // true declare function create(x: Object); create("string"); // OK create(null); // Error create(undefined); // Error
-
object is the type of all non-primitive values. You can't assign to it any primitive type like
boolean,number,string,bigint,symbol,nullorundefineddeclare function create(x: object); create([]); // OK create({ id: 0 }); // OK create(42); // Error create("string"); // Error create(false); // Error create(undefined); // Error
-
{} is an empty object. It is the same as
Object
interface RepoInterface {
isPublic: boolean; // property signature
hasRequests(x: string): void; // method signature, 'x' for documentation only
hasRequests: (x: string) => void; // method signature for ES6
[propName: string]: any; // index signature
(x: number): string; // call signature
new (x: string): RepoInstance; // construct signature
readonly admin: string; // readonly modifier
readonly [index: number]: string; // you can make index readonly like this
isArchive?: string; // optional modifier, auto set to undefined
isArchive: undefined; // in this case need set the property
}Helps to describe Arrays or objects that are used as dictionaries.
If there are both an index signature and property and/or method signatures in an interface, the type of the index property value must also be a supertype of the type of the property value and/or method
interface RepoInterface {
[propName: string]: boolean;
// 'number' is not assignable to string index type 'boolean'
star: number;
// '() => string' is not assignable to string index type 'boolean'
isCreated(): string;
}
// You can resolve above problem like this
interface RepoInterface {
[propName: string]: number;
star: number; // OK
isCreated(): number; // OK
}
// Or you can do this to your interface
interface RepoInterface {
[propName: string]: boolean | number | string;
star: number; // OK
isCreated(): string; // OK
}Enables interfaces to describe functions. NOTE this is the optional calling context of the function in this example:
interface ClickListener {
(this: Window, e: MouseEvent): void;
}
const myListener: ClickListener = (e) => {
console.log("mouse clicked!", e);
};
addEventListener("click", myListener);Enables describing classes and constructor functions. A class has two types:
- The type of the static side
- The type of the instance side
The constructor sits in the static side, when a class implements an interface, only the instance side of the class is checked.
interface ClockInterface {
tick(): void
}
interface ClockConstructor {
new (h: number, m: number): ClockInterface
}
/*
* Using Class Expression
*/
const ClockA: ClockConstructor = class Clock implements ClockInterface {
constructor(h: number, m: number) {...}
tick() {...}
}
const clockClassExp = new ClockA(18, 11)
/*
* Using Class Declaration with a Constructor Function
*/
class ClockB implements ClockInterface {
constructor(h: number, m: number) {...}
tick() {...}
}
function createClock( ctor: ClockConstructor, h: number, m: number): ClockInterface {
return new ctor(h, m)
}
const clockClassDeclaration = createClock(ClockB, 12, 17)Typically used in the signature of a higher-order function, but it's not limited to this.
type Point = {
x: number;
y: number;
};
type SetPoint = (x: number, y: number) => void;-
Engineers can’t just think of interfaces as “objects that have exactly a set of properties” or “objects that have at least a set of properties”. In-line object arguments receive an additional level of validation that doesn’t apply when they’re passed as variables.
-
TypeScript is a structurally typed language. To create a
Dogyou don’t need to explicitly extend theDoginterface, any object with abreedproperty that is of typestringcan be used as aDog:
interface Dog {
breed: string;
}
function printDog(dog: Dog) {
console.log("Dog: " + dog.breed);
}
const ginger = {
breed: "Airedale",
age: 3,
};
printDog(ginger); // excess properties are OK!
printDog({ breed: "Airedale", age: 3 }); // ERRORS
/*
Argument of type '{ breed: string; age: number }' is not assignable to parameter of type 'Dog'.
Object literal may only specify known properties, and 'age' does not exist in type 'Dog'.
*/
// To get rid of above problem, you can define interface with extra proprty with string index signature
interface Dog {
breed: string;
[propName: string]: any;
}Unlike an interface declaration, which always introduces a named object type, a type alias declaration can introduce a name for any kind of type, including primitive, union, and intersection types. With examples, you can find some in-depth difference between interface and type.
-
Objects / FunctionsBoth can be used to describe the shape of an object or a function signature. But the syntax differs.
Interface
interface Point { x: number; y: number; } interface SetPoint { (x: number, y: number): void; }
Type alias
type Point = { x: number; y: number; }; type SetPoint = (x: number, y: number) => void;
-
Other TypesUnlike an interface, the type alias can also be used for other types such as
primitives,unions, andtuples(Aforementioned).// primitive type Name = string; // object type PartialPointX = { x: number }; type PartialPointY = { y: number }; // union type PartialPoint = PartialPointX | PartialPointY; // tuple type Data = [number, string];
-
Extend
Both can be extended, but again, the syntax differs. Additionally, note that an interface and type alias are not mutually exclusive. An interface can extend a type alias, and vice versa.
interface extends interface
interface PartialPointX { x: number; } interface Point extends PartialPointX { y: number; }
type alias extends type alias
type PartialPointX = { x: number }; type Point = PartialPointX & { y: number };
interface extends type alias
type PartialPointX = { x: number }; interface Point extends PartialPointX { y: number; }
type alias extends interface
interface PartialPointX { x: number; } type Point = PartialPointX & { y: number };
-
ImplementsA class can implement an interface or type alias, both in the same exact way. Note however that a class and interface are considered static blueprints. Therefore, they can not
implement / extenda type alias that names a union type.interface Point { x: number; y: number; } class SomePoint implements Point { x = 1; y = 2; } type Point2 = { x: number; y: number; }; class SomePoint2 implements Point2 { x = 1; y = 2; } type PartialPoint = { x: number } | { y: number }; // ERROR: can not implement a union type class SomePartialPoint implements PartialPoint { x = 1; y = 2; } /* A class can only implement an object type or intersection of object types with statically known members. */
-
Declaration mergingUnlike a type alias, an interface can be defined multiple times, and will be treated as a single interface (with members of all declarations being merged).
// These two declarations become: // interface Point { x: number y: number } interface Point { x: number; } interface Point { y: number; } const point: Point = { x: 1, y: 2 };
const data = {
value: 123,
text: "text",
subData: {
value: false,
},
};
type Data = typeof data; // Data = { value: number; text: string; subData: { value: boolean; } }const data = ["A", "B"] as const;
type Data = typeof data[number]; // "A" | "B"const locales = [
{
locale: "se",
language: "Swedish",
},
{
locale: "en",
language: "English",
},
] as const;
type Locale = typeof locales[number]["locale"]; // "se" | "en"const currencySymbols = {
GBP: "£",
USD: "$",
EUR: "€",
};
type CurrencySymbol = keyof typeof currencySymbols; // "GBP" | "USD" | "EUR"Exampl-1:
interface HasPhoneNumber {
name: string;
phone: number;
}
interface HasEmail {
name: string;
email: string;
}
interface CommunicationMethods {
email: HasEmail;
phone: HasPhoneNumber;
fax: { fax: number };
}
function contact<K extends keyof CommunicationMethods>(
method: K,
contact: CommunicationMethods[K] // turning key into value - a mapped type
) {
// do something...
}
contact("email", { name: "foo", email: "[email protected]" });
contact("phone", { name: "foo", phone: 3213332222 });
contact("fax", { fax: 1231 });
// // we can get all values by mapping through all keys
type AllCommKeys = keyof CommunicationMethods;
type AllCommValues = CommunicationMethods[keyof CommunicationMethods];Exampl-2:
Let's take a prop function
function prop<T, K extends keyof T>(obj: T, key: K) {
return obj[key];
}
const todo = {
id: 1,
text: "Buy milk",
due: new Date(2016, 11, 31),
};
const id = prop(todo, "id"); // number
const text = prop(todo, "text"); // string
const due = prop(todo, "due"); // Dateinterface Person {
name: string;
age: number;
location: string;
}
type P1 = Person["name"]; // string
type P2 = Person["name" | "age"]; // string | number
// typing from string operations
type P3 = string["charAt"]; // (pos: number) => string
type P4 = string[]["push"]; // (...items: string[]) => number
type P5 = string[][0]; // stringArticle Links:
Properties marked with readonly can only be assigned to during initialization
or from within a constructor of the same class.
type Point = {
readonly x: number;
readonly y: number;
};
const origin: Point = { x: 0, y: 0 }; // OK
origin.x = 100; // Error
function moveX(p: Point, offset: number): Point {
p.x += offset; // Error
return p;
}
function moveX(p: Point, offset: number): Point {
// OK
return {
x: p.x + offset,
y: p.y,
};
}Gettable area property is implicitly read-only because there’s no setter:
class Circle {
readonly radius: number;
constructor(radius: number) {
this.radius = radius;
}
get area() {
return Math.PI * this.radius ** 2;
}
}Here are different usecases of readonly
-
readonly property
interface Apple { readonly types: string[] readonly origin: [string, string] } const apple: Apple = { types: ["Asian", "American", "European"] origin: ["Local", "Home Grown"] } apple.types.push("Russian") // OK, array is now mutable
-
property has readonly type
interface Apple { types: readonly string[] origin: readonly [string, string] } const apple: Apple = { types: ["Asian", "American", "European"] origin: ["Local", "Home Grown"] } apple.types.push("Russian") // Error, Property `push` does not exist on type 'readonly string[]'
-
Variable declaration with readonly
const array: readonly string[]; const tuple: readonly [string, string];
-
numberbecomes number literal// Type '10' let num = 10 as const;
-
array literals become
readonlytuples// Type 'readonly [10, 20]' let tuple = [10, 20] as const;
-
object literals get
readonlyproperties -
no literal types in that expression should be widened (e.g. no going from
"hello"tostring)// Type '{ readonly text: "hello" }' let input = { text: "hello" } as const;
-
object literals with array types becomes also readonly
// Type `{ readonly types: readonly ["A", "B"]}` let apple = { types: ["A", "B"] } as const; apple.types = ["C"]; // Error, 'types' is readonly, we can't reassign apple.push("C"); // Error, Property 'push' does not exist on type 'readonly ["A", "B", "C"]'
-
⛔
constcontexts don’t immediately convert an expression to be fullyimmutable.let types = ["Asian", "European"]; let apple = { name: "Green Apple", types: types, } as const; apple.name = "Red Apple"; // Error apple.types = ["American"]; // Error aaple.types.push("African"); // OK // to fix above, just do this little trick let types = ["Asian", "European"] as const; // OR let types: readonly string[] = ["Asian", "European"];
strict: true /* Enable all strict type-checking options. */is equivalent to enabling all of the strict mode family options:
noImplicitAny: true /* Raise error on expressions and declarations with an implied 'any' type */,
strictNullChecks: true /* Enable strict null checks */,
strictFunctionTypes: true /* Enable strict checking of function types */,
strictBindCallApply: true /* Enable strict 'bind', 'call', and 'apply' methods on functions */,
strictPropertyInitialization: true /* Enable strict checking of property initialization in classes */,
noImplicitThis: true /* Raise error on 'this' expressions with an implied 'any' type */,
alwaysStrict: true /* Parse in strict mode and emit "use strict" for each source file */You can then turn off individual strict mode family checks as needed.
In strict null checking mode, null and undefined are no longer assignable to
every type.
let name: string;
name = "Marius"; // OK
name = null; // Error
name = undefined; // Errorlet name: string | null;
name = "Marius"; // OK
name = null; // OK
name = undefined; // ErrorOptional parameter ? automatically adds | undefined
type User = {
firstName: string;
lastName?: string; // same as `string | undefined`
};- In JavaScript, every function parameter is optional, when left off their value
is
undefined. - We can get this functionality in TypeScript by adding a
?to the end of parameters we want to be optional. This is different from adding| undefinedwhich requires the parameter to be explicitly passed asundefined
function fn1(x: number | undefined): void {
...
}
function fn2(x?: number): void {
...
}
fn1() // Error
fn2() // OK
fn1(undefined) // OK
fn2(undefined) // OKType guard needed to check if Object is possibly null:
function getLength(s: string | null) {
// Error: Object is possibly 'null'.
return s.length;
}function getLength(s: string | null) {
if (s === null) {
return 0;
}
return s.length;
}
// JS's truthiness semantics support type guards in conditional expressions
function getLength(s: string | null) {
return s ? s.length : 0;
}function doSomething(callback?: () => void) {
// Error: Object is possibly 'undefined'.
callback();
}function doSomething(callback?: () => void) {
if (typeof callback === "function") {
callback();
}
}The
call()method calls a function with a giventhisvalue and arguments provided individually, whileapply()accepts a single array of arguments.The
bind()method creates a new function that, when called, has itsthiskeyword set to the provided value.
When set, TypeScript will check that the built-in methods of functions call,
bind, and apply are invoked with correct argument for the underlying
function:
// With strictBindCallApply on
function fn(x: string) {
return parseInt(x);
}
const n1 = fn.call(undefined, "10"); // OK
const n2 = fn.call(undefined, false); // Argument of type 'false' is not assignable to parameter of type 'string'.Verify that each instance property declared in a class either:
- Has an explicit initializer, or
- Is definitely assigned to in the constructor
// Error
class User {
// Type error: Property 'username' has no initializer
// and is not definitely assigned in the constructor
username: string;
}
// OK
class User {
username = "n/a";
}
const user = new User();
const username = user.username.toLowerCase();
// OK
class User {
constructor(public username: string) {}
}
const user = new User("adam");
const username = user.username.toLowerCase();- Has a type that includes undefined
class User {
username: string | undefined;
}
const user = new User();
// Whenever we want to use the username property as a string, we first have
// to make sure that it actually holds a string, not the value undefined
const username =
typeof user.username === "string" ? user.username.toLowerCase() : "n/a";never represents the type of values that never occur. It is used in the
following two places:
- As the return type of functions that never return
- As the type of variables under type guards that are never true
never can be used in control flow analysis:
function controlFlowAnalysisWithNever(value: string | number) {
if (typeof value === "string") {
value; // Type string
} else if (typeof value === "number") {
value; // Type number
} else {
value; // Type never
}
}unknown is the type-safe counterpart of the any type: we have to do some
form of checking before performing most operations on values of type unknown.
type Result =
| { success: true; value: unknown }
| { success: false; error: Error };
function tryDeserializeLocalStorageItem(key: string): Result {
const item = localStorage.getItem(key);
if (item === null) {
// The item does not exist, thus return an error result
return {
success: false,
error: new Error(`Item with key "${key}" does not exist`),
};
}
let value: unknown;
try {
value = JSON.parse(item);
} catch (error) {
// The item is not valid JSON, thus return an error result
return {
success: false,
error,
};
}
// Everything's fine, thus return a success result
return {
success: true,
value,
};
}Generics enable you to create reusable code components that work with a number of types instead of a single type.
function identity<T>(arg: T): T {
return arg;
}
let output = identity<string>("myString"); // type of output will be 'string'
let output = identity("myString"); // type argument inference
// compiler sets the value of `T` based on the type of the argument we pass infunction loggingIdentity<T>(arg: T): T {
console.log(arg.length); // Error: T doesn't have .length
return arg;
}
// to specify .length property we should make generic T to T[] or Array<T>
function loggingIdentity<T>(arg: Array<T>): Array<T> {
console.log(arg.length); // Array has a .length, so no more error
return arg;
}No value arguments are needed in this case:
function makePair<F, S>() {
let pair: { first: F; second: S };
function getPair() {
return pair;
}
function setPair(x: F, y: S) {
pair = {
first: x,
second: y,
};
}
return { getPair, setPair };
}
// Creates a (number, string) pair
const { getPair, setPair } = makePair<number, string>();
setPair(1, "y"); // must be type of (number, string)
getPair(); // will return pair of type { number, string }// Input a function `<T extends (...args: any[]) => any>`
// Output a function with same params and return type `:(...funcArgs: Parameters<T>) => ReturnType<T>`
function logDuration<T extends (...args: any[]) => any>(func: T) {
const funcName = func.name;
// Return a new function that tracks how long the original took
return (...args: Parameters<T>): ReturnType<T> => {
console.time(funcName);
const results = func(...args);
console.timeEnd(funcName);
return results;
};
}
function addNumbers(a: number, b: number): number {
return a + b;
}
// Hover over is `addNumbersWithLogging: (a: number, b: number) => number`
const addNumbersWithLogging = logDuration(addNumbers);
addNumbersWithLogging(5, 3);A generic class has a similar shape to a generic interface. Generic classes have a generic type parameter list in angle brackets (<>) following the name of the class.
class GenericNumber<T> {
zeroValue: T;
add: (x: T, y: T) => T;
}
let myGenericNumber = new GenericNumber<number>();
myGenericNumber.zeroValue = 0;
myGenericNumber.add = function (x, y) {
return x + y;
};Discriminated Unions provide a powerful pattern in TypeScript. Immensely useful for actions & reducers in ngrx/redux, and every time you have to distinguish between kinds of objects. They enaWtype inference which, combined with strict null checks, will catch a lot of bugs! By Minko Gechev
const enum Entity {
Individual,
Corporation,
}
interface Individual {
type: Entity.Individual;
ssn: string;
}
interface Corporation {
type: Entity.Corporation;
ein: string;
}
type TaxPayer = Individual | Corporation;
function magic(payer: TaxPayer) {
if (payer.type === Entity.Individual) {
taxIdentifier(payer.ssn);
taxIdentifier(payer.ein); // Property 'ein' does not exist on type 'Individual'
} else {
taxIdentifier(payer.ein);
taxIdentifier(payer.ssn); // Property 'ssn' doesn't exist on type 'Corporation'
}
}Album where the artist, and the artists biography might not be present in the data.
type AlbumAPIResponse = {
title: string;
artist?: {
name: string;
bio?: string;
previousAlbums?: string[];
};
};
// Instead of:
const maybeArtistBio = album.artist && album.artist.bio;
// ?. acts differently than && on "falsy" values: empty string, 0, NaN, false
const artistBio = album?.artist?.bio;
// optional chaining also works with the [] operators when accessing elements
// see more example for optional element access below
const maybeArtistBioElement = album?.["artist"]?.["bio"];
const maybeFirstPreviousAlbum = album?.artist?.previousAlbums?.[0];Optional chaining on an optional function:
interface OptionalFunction {
bar?: () => number;
}
const foo: OptionalFunction = {};
const bat = foo.bar?.(); // number | undefinedOptional Element Access
the optional element access which acts similarly to optional property accesses, but allows us to access non-identifier properties (e.g. arbitrary strings, numbers, and symbols):
/**
* Get the first element of the array if we have an array.
* Otherwise return undefined.
*/
function tryGetFirstElement<T>(arr?: T[]) {
return arr?.[0];
// equivalent to
// return (arr === null || arr === undefined) ?
// undefined :
// arr[0]
}Optional Call
optional call, which allows us to conditionally call expressions if they’re not null or undefined.
async function makeRequest(url: string, log?: (msg: string) => void) {
log?.(`Request started at ${new Date().toISOString()}`);
// roughly equivalent to
// if (log != null) {
// log(`Request started at ${new Date().toISOString()}`)
// }
const result = (await fetch(url)).json();
log?.(`Request finished at at ${new Date().toISOString()}`);
return result;
}Short-circutting
The short-circuiting behavior that optional chains have is limited property accesses, calls, element accesses - it doesn’t expand any further out from these expressions.
let result = foo?.bar / someComputation();
// doesn’t stop the division or someComputation() call from occurring. It’s equivalent to
let temp = foo === null || foo === undefined ? undefined : foo.bar;
let result = temp / someComputation();Value foo will be used when it’s “present”; but when it’s null or
undefined, calculate bar() in its place.
let x = foo ?? bar();
// instead of
let x = foo !== null && foo !== undefined ? foo : bar();It can replace uses of || when trying to use a default value, and avoids bugs.
When localStorage.volume is set to 0, the page will set the volume to 0.5
which is unintended. ?? avoids some unintended behaviour from 0, NaN and
"" being treated as falsy values.
function initializeAudio() {
let volume = localStorage.volume || 0.5; // Potential bug
}TypeScript 3.9 brings a new feature: // @ts-expect-error comments. When a line is prefixed with a // @ts-expect-error comment, TypeScript will suppress that error from being reported; but if there’s no error, TypeScript will report that // @ts-expect-error wasn’t necessary.
// @ts-expect-error
console.log(47 * "octopus"); // OK, no problem here
// @ts-expect-error
console.log(1 + 1); // Unused '@ts-expect-error' directive.In some ways // @ts-expect-error can act as a suppression comment, similar to // @ts-ignore. The difference is that // @ts-ignore will do nothing if the following line is error-free.
You might be tempted to switch existing // @ts-ignore comments over to // @ts-expect-error, and you might be wondering which is appropriate for future code. While it’s entirely up to you and your team, we have some ideas of which to pick in certain situations.
Pick ts-expect-error if:
- you’re writing test code where you actually want the type system to error on an operation
- you expect a fix to be coming in fairly quickly and you just need a quick workaround
- you’re in a reasonably-sized project with a proactive team that wants to remove suppression comments as soon affected code is valid again
Pick ts-ignore if:
- you have an a larger project and and new errors have appeared in code with no clear owner
- you are in the middle of an upgrade between two different versions of TypeScript, and a line of code errors in one version but not another.
- you honestly don’t have the time to decide which of these options is better
- Short-Circuiting Assignment Operators
- Template Literal Types
- Key Remapping in Mapped Types
- Checked Indexed Accesses (--noUncheckedIndexedAccess)
- Paths without baseUrl
- Destructured Variables Can Be Explicitly Marked as Unused
- (Template String Type Improvements)
- (Editor Support for @link Tags)
- (Go-to-Definition on Non-JavaScript File Paths)
- (Inlay Hints)
Will update soon
Thanks goes to these people for great examples:
