Type space vs value space

Two parallel namespaces

Why does TypeScript need two separate namespaces at all? Because types are erased — the runtime world and the compile-time world are physically separate, and a name can live in one, the other, or both. If you do not know which world a name belongs to, errors like “only refers to a type” will seem arbitrary rather than mechanical.

TypeScript maintains two separate symbol tables. The value space holds things that exist at runtime — variables, functions, the constructor side of a class. The type space holds things that are erased before runtime — type aliases, interfaces, the instance shape of a class. The same name can be registered in one, the other, or both, and position decides which table the compiler consults.

const port = 3000;        // `port` is in VALUE space only
type Port = number;       // `Port` is in TYPE space only

const x: Port = port;     // type position uses Type table, value position uses value table — fine
const y = Port;
// Error: 'Port' only refers to a type, but is being used as a value here.

A type annotation position (after :, in extends, inside <...>) is read against the type table. An expression position (the right-hand side of =, a function argument, after return) is read against the value table. Port exists only in the type table, so summoning it in an expression position fails — and the error tells you exactly which world it lives in.

Who lives where

The crucial detail for everyday code: declarations differ in which namespaces they populate.

A class is the one that trips people up most: its name means two different things depending on position. In value position it is the constructor function; in type position it is the instance shape.

class Logger {
  level = "info";
}

const a = new Logger();   // value position: `Logger` is the constructor
//    ^? const a: Logger
function use(l: Logger) {} // type position: `Logger` is the instance type
const ctor: typeof Logger = Logger; // the constructor's TYPE (see next section)

The bridges: typeof (value→type) and keyof (type→type)

You frequently have a value and want to talk about its type without writing the type out by hand. The typeof type operator is the bridge from value space into type space.

const config = { host: "localhost", port: 5432, tls: false };

type Config = typeof config;
//   ^? type Config = { host: string; port: number; tls: boolean }

function connect(c: typeof config) {} // reuse the inferred shape, no duplication

Note: this is the type-level typeof, used in a type position — it is unrelated to JavaScript’s runtime typeof x operator that returns the string "object". Same keyword, two worlds.

keyof is a different bridge — it stays entirely inside type space, mapping an object type to the union of its keys.

type Config = typeof config;
type ConfigKey = keyof Config;
//   ^? type ConfigKey = "host" | "port" | "tls"

Compose them and you get the workhorse pattern for typed lookups:

function get<K extends keyof typeof config>(key: K): (typeof config)[K] {
  return config[key];
}
const p = get("port");
//    ^? number
const h = get("host");
//    ^? string
get("nope");
// Error: Argument of type '"nope"' is not assignable to parameter of type
//        'keyof typeof config'.  ("host" | "port" | "tls")

The two classic errors, decoded

Both halves of the world-crossing mistake have their own exact diagnostic, and reading the wording tells you which direction you crossed.

interface User { id: string }

const a: User = { id: "1" };   // fine: User in type position
const b = User;
// Error: 'User' only refers to a type, but is being used as a value here.
//        (you used a type-only name where a value is required)

const handler = () => {};
type T = handler;
// Error: 'handler' refers to a value, but is being used as a type here.
//        Did you mean 'typeof handler'?
//        (you used a value-only name where a type is required — bridge it with typeof)

The fix is always the same logic: figure out which space the name lives in, and either move to the matching position or use a bridge (typeof) to cross deliberately. And because interface/type are type-only, they vanish at runtime — you cannot instanceof User an interface — whereas a class survives, which is exactly why classes are the tool when you need a runtime-checkable shape. When you encounter either diagnostic in a real codebase, read the wording first: it tells you the direction of the crossing and the bridge you need.