TypeScript any vs unknown: Differences and When to Use

any and unknown both accept every value. The difference is what you can do with the value afterwards: any lets you do anything and checks nothing, while unknown lets you do almost nothing until you prove what the value is.

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

Without the @ts-expect-error line, u.toUpperCase() is compile error TS18046. The typeof check narrows u to string, and inside that block every string method is available.

any vs unknown at a Glance

In type theory terms, unknown is the top type: every type is assignable to it, and it is assignable only to unknown and any. any is an escape hatch that is assignable both ways, to everything except never.

any Switches Off Type Checking

A value typed any is trusted blindly. The compiler accepts typos, wrong types and missing properties, and the mistakes turn up at runtime instead.

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

The output shows the problem: a variable annotated number holds a string, and the last line throws Cannot read properties of undefined (reading 'city'). any also spreads. user.name is any, so any value computed from it is any, and one untyped value can switch off checking far from where it entered.

unknown Makes You Check First

With unknown, the compiler refuses every operation until the code narrows the value. Narrowing uses ordinary JavaScript checks, and inside each branch the value has the checked type.

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

The value === null check has to come before the object check because typeof null is "object". After "id" in value, TypeScript knows the object has an id property, typed unknown, since nothing says what it holds. String() turns it into text explicitly; to use it as a number you would check it with typeof first.

You can also skip the check with an assertion, value as string, and the compiler accepts it. That is a promise with no runtime check behind it, so prefer a real check; see type assertions.

Validating JSON with unknown

JSON.parse is declared to return any, so its result silently disables checking. Annotate the result as unknown and write a type guard that checks the shape before the rest of the code trusts it.

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

The first input prints dark at 14px, the second is rejected because fontSize is missing. With any, the second input would have flowed through as a Settings with fontSize undefined. For large schemas, a validation library does the same job and derives the type for you.

noImplicitAny

any does not only come from people writing it. A parameter with no annotation and no context to infer from would be any too. The noImplicitAny option, which strict turns on, reports that as an error:

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

The fix is an annotation, function double(x: number). Writing x: any explicitly also compiles, which is the point: any stays visible in the code and can be searched for and reviewed.

Where any Still Sneaks In

Even under strict, these produce any without the word appearing in your code:

The catch variable is unknown under strict because anything can be thrown, not only Error objects. Narrow it with e instanceof Error before reading e.message.

When any Is Acceptable

any is not forbidden, but each one is a spot the compiler no longer protects. Reasonable uses:

• Migrating a JavaScript codebase, where any marks what is not typed yet.
• Code the type system cannot express well, kept small and behind a typed function signature.
• Test code that deliberately passes bad data.

For everything else, unknown covers the same "I do not know this type" case while keeping the checks. Many teams enforce this with the @typescript-eslint/no-explicit-any lint rule. A related type, Record<string, unknown>, is the usual choice for "some object with unknown values".