TypeScript ‘unknown’ Type: Explained with Examples

Updated: January 8, 2024 By: Guest Contributor Post a comment


Embrace a journey into the TypeScript lands where the ‘unknown’ type awaits, an enigmatic force that ensures type safety in the wilderness of dynamic data. Our expedition through examples galore shall reveal its utility and mastery.

Introduction to ‘unknown’

Like the murmuring Mississippi under a hazy moon, the unknown type in TypeScript is a shadowy player, at once familiar and alien to JavaScript travelers. Before TypeScript’s version 3.0, like riverboats without a compass, we were all adrift in ambiguity when confronting unexpected data types. Yet, with the introduction of unknown, TypeScript provided us a safe haven – a type-safe harbor, if you will – where we could defer the type assignment to a later time when we’re better acquainted with the data, preventing potential runtime errors that are as treacherous as the jagged cliffs by the river’s edge.

Basic Usage of ‘unknown’

let exampleOne: unknown;

exampleOne = 'A string of pearls and promise'; // Acceptable
exampleOne = 42; // Just as welcomed
exampleOne = { name: 'Huckleberry', purpose: 'Friend' }; // No objections here

We begin our exploration by assigning various life-forms to our unknown vessel – strings, numbers, and objects are all welcomed alike, no questions asked. However, direct interaction with these stowaways is forbidden without proper identification.

Type Checking

if (typeof exampleOne === 'string') {
  console.log(exampleOne.toUpperCase()); // Now safe to navigate

True understanding comes with examining one’s character, much as one scrutinizes a river’s current before taking the plunge. By using type checking, we ascertain the nature of our unknown passenger, allowing for secure passage through previously unnavigable territories.

More Complex Interactions

Should our journey require a crossing with unknown types of greater complexity, such as function arguments or return values as cryptic as the nocturnal hoot of an owl, TypeScript stands ready with its toolkit at hand.

function greet(entrant: unknown): string {
  if (typeof entrant === 'string') {
    return `Welcome, ${entrant}!`;
  throw new Error('A traveler unknown can’t be greeted justly.');

greet('Finn'); // Welcome, Finn!
// greet(123); // Throws an Error

Only after thorough interrogation and confirmation do we extend pleasantries or invoke reactions—a necessary precaution before unceremoniously casting them into TypeScript’s unforgiving runtime.

Advanced Maneuvers with ‘unknown’

Intersection Types

type Ferry = { float: () => void };
function raft(boat: unknown): boat is Ferry {
  return (boat as Ferry).float !== undefined;

let mysteriousVessel: unknown = //{ float: () => console.log('Afloat we remain!') };

if (raft(mysteriousVessel)) {
  mysteriousVessel.float(); // We can confidently set sail with our verified vessel.

Like the Mississippi’s confluence with its tributaries, combining the unknown with intersection types allows for a rich blend of options as varied as the river’s delta, each vein leading to a diverse fate, permitting us to inspect and incorporate unknown entities into the fold of our typified arsenal.

Type Assertion

Sometimes, a captain of TypeScript must take charge and assert dominion over the unknown, like so:

let mysteriousScroll: unknown = 'A hidden treasure map!';
let decryptedScratchings: string = mysteriousScroll as string;
console.log(decryptedScratchings); // Proceed with a clear directive.

An assertion is akin to shooting one’s pistol in the air, demanding recognition and yielding instantaneous results, provided you are certain of the unknown entity’s nature.

Dealing with ‘unknown’ in Generics

For times when you encounter a creature as mutable as the moon’s faces, TypeScript’s generics come into play:

function openChest(content: T): T {
  return content;

let pandorasBox: unknown = ['a medley of fortunes and woes'];
let contents = openChest(pandorasBox);
console.log(contents); // The once unknown now has form and structure.

Using generics, we cater to the varying nature of our contents, finally shaping the unknown like the potter with his clay, giving it identity and purpose.


In sum, the ‘unknown’ type is a tool of savvy and sensibility, akin to a telescope on the deck of our TypeScript galleon. It forces us to confront and understand our data before we act, thus steering us clear from the jagged rocks of assumptions and towards the horizon of type safety and predictability. So, hearty coder, utilize ‘unknown’ with the wisdom and restraint fitting of a riverboat captain, and May your programs run as true as the stars above the great Mississippi.