Unknown

unknown is the supertype of all types. All values are unknown, but you must refine an unknown value before performing any operations on it.

When to use this​

Use unknown instead of any when you need to accept arbitrary values — unknown forces you to refine before use, so it is type-safe to use. If you know the set of possible types upfront, prefer a union for better specificity.

Overview​

In general, programs have several different categories of types:

A single type:

Here the input value can only be a number.

function square(n: number) {
  return n * n;
}

A group of different possible types:

Here the input value could be either a string or a number.

function stringifyBasicValue(value: string | number) {
  return '' + value;
}

A type based on another type:

Here the return type will be the same as the type of whatever value is passed into the function.

function identity<T>(value: T): T {
  return value;
}

These three are the most common categories of types. They will make up the majority of the types you'll be writing.

However, there is also a fourth category.

An arbitrary type that could be anything:

Here the passed in value is an unknown type, it could be any type and the function would still work.

function getTypeOf(value: unknown): string {
  return typeof value;
}

These unknown types are less common, but are still useful at times.

You should represent these values with unknown.

Anything goes in, Nothing comes out​

unknown will accept any type of value. Strings, numbers, objects, functions– anything will work.

function stringify(value: unknown) {
  // ...
}


stringify("foo");
stringify(3.14);
stringify(null);
stringify({});

When you try to use a value of a unknown type you must first figure out what the actual type is or you'll end up with an error.

function stringify(value: unknown) {
  return "" + value; // Error!
}


stringify("foo");

Instead you must ensure the value is a certain type by refining it.

function stringify(value: unknown) {
  if (typeof value === 'string') {
    return "" + value; // Works!
  } else {
    return "";
  }
}


stringify("foo");

Because of the typeof value === 'string' check, Flow knows the value can only be a string inside of the if statement. This is known as a refinement.

Versus any​

unknown is safe, while any is not. Both accept all values, but any also unsafely allows all operations.

Versus empty​

unknown is the opposite of empty:

• Everything is an unknown, but few operations are permitted on it without first refining to a specific type. It is the supertype of all types.
• Nothing is empty, but any operation is permitted on it. It is the subtype of all types.

Refining unknown​

typeof is the most common way to narrow an unknown value (see refinements for the full list of forms), but several other idioms come up regularly when working with unknown.

Array.isArray​

Narrows unknown to ReadonlyArray<unknown>. Elements are still unknown and must be refined before use.

declare const value: unknown;
if (Array.isArray(value)) {
  value as ReadonlyArray<unknown>; // OK
}

'key' in value​

The in operator requires its right-hand side to already be a non-null object, so 'key' in value on a bare unknown is a type error. Narrow to an object first; in then refines the value to an object with that property (the property type is unknown and needs further refinement before use):

declare const value: unknown;
if (typeof value === 'object' && value !== null && 'foo' in value) {
  value as {readonly foo: unknown, ...}; // OK
}

The value !== null step is required because typeof null === 'object'.

instanceof​

value instanceof SomeClass narrows unknown to that class:

class User {
  name: string = '';
}


declare const value: unknown;
if (value instanceof User) {
  value.name as string; // OK
}

See Also​

• Refinements — how to narrow unknown values to specific types before use
• Type Hierarchy — how unknown, any, and empty relate in the full type hierarchy
• Modernizing Legacy Flow Syntax — migrating the legacy mixed type to unknown