TypeScript's Secret Parallel Universe

Almost four years ago, I was a new TypeScript user, amazed by the possibilities that this freshly learned JavaScript dialect opened up to me. But just like every TypeScript developer, I soon ran into some hard-to-debug problems.

In TypeScript land, those problems usually stem from the programmer's lack of understanding about the language itself.

---

I'd like to introduce you to one of these early problems I had, mostly because it is related to one of the (in my opinion) most underreported topics in the TypeScript tutorial world: the type scope. It's kind of obvious once you realize it exists, but for me it was a frequent source of confusion when I didn't know about it.

The Problem

My problem was actually very simple: I was building a library with a bunch of classes distributed over various folders.

For the library's public API, I wanted those classes to be exposed as a single nested object (e.g. the Console class from Output/Console.ts being available as API.Output.Console).

So I defined some namespaces, imported the classes — and then I struggled. I was just not able to re-export the classes from inside the namespaces. 🤨

---

First attempt, turned out to be invalid TypeScript:

import Console from './Output/Console'

export namespace Output {
  export Console
  // TS Error 1128: Declaration or statement expected.
}

Maybe I need to import it under a different name. Okay, second attempt:

import ConsoleAlias from './Output/Console'

export namespace Output {
  export Console = ConsoleAlias
  // TS Error 2304: Cannot find name 'Console'.
}

Third attempt — maybe doing it the ES Modules way cuts it. (Spoiler: It didn't.)

import ConsoleAlias from './Output/Console'

export namespace Output {
  export { ConsoleAlias as Console }
  //TS Error 1194: Export declarations are not permitted in a namespace.
}

Fourth attempt using export const. This actually compiled. 🎉

import ConsoleAlias from './Output/Console'

export namespace Output {
  export const Console = ConsoleAlias
}

But unfortunately, whenever I wanted to type hint something with that API object, I got the following error:

import * as API from './API'

let console: API.Output.Console
// TS Error 2694: Namespace 'API.Output' has no exported member 'Console'.

...but I exported that member! Why is it not there!?

Hum. Maybe the export const is the problem. I should sprinkle some magic TypeScript keywords over the problem and try export type instead.

So without further ado: Fifth attempt. It compiles! 🥳

import ConsoleAlias from './Output/Console'

export namespace Output {
  export type Console = ConsoleAlias
}

Okay, reality check: Does the type hint work? It does! 🕺

...but that joy was short-lived as well. When I tried to create a new Console instance, TypeScript errors were all over me again:

import * as API from './API'

const console = new API.Output.Console()
// TS Error 2708: Cannot use namespace 'API' as a value.

Oh come on.

Needless to say that I was pretty fed up with TypeScript at that point.

However, I did not want to believe that there was no solution to my problem, so I went to StackOverflow and, after a couple of days with no answer, I created an issue directly in TypeScript's GitHub repository.

The Solution

Ryan from the TypeScript team was kind enough to answer my question just within a couple of minutes. To me, the solution seemed pretty obvious and pretty obscure at the same time:

I applied that approach — and it worked like a charm.

Why It Works

Back then, I just accepted that answer and used it in my code. It sounded kind of plausible to me — both, const and type, worked in some way, so I just need to combine them to make both use cases working. But there was a sense of unease in it. Why could I export two things under the same name without producing a big fat compiler error?

It took me some more months (maybe even years) of TypeScript experience to fully understand why this works, but I think that insight might be valuable for others as well, so I'll share it here:

TypeScript has a secret scope.

TypeScript basically maintains a type scope which is completely independent of the variable scope of JavaScript. This means that you may declare a variable foo and a type foo in the same file. 🤯 They don't even need to be compatible:

const foo = 'bar'
type foo = number

// ✅ This is absolutely fine for TypeScript

Now classes in TypeScript are a little bit special. What happens if you define a class Foo is that TypeScript not only creates a variable Foo (containing the class object itself) it also declares a type Foo, representing an instance of the Foo class.

class Foo {}

// We can use Foo as a type
let foo: Foo

// We can use Foo as a constructor (i.e. a value)
const bar = new Foo()

Similarly, when importing a name from another file (like we do with ConsoleAlias in the second code sample), both — the ConsoleAlias class object and the ConsoleAlias type — are imported.

In other words, that single name — the imported ConsoleAlias — holds both the class object and the type declared in Output/Console.ts.

So if we re-export Console from inside the Output namespace by writing export const Console = ConsoleAlias, only the class object is exported (because a const only ever holds a value, not a type). Similarly, if we'd do export type Console = ConsoleAlias, only the class type would be exported.

In a nutshell: Because of the independent scopes, it's valid to export a value as well as a type under the same name. And in some cases (like the one above), this is not only valid but necessary.

---

I hope this helped refine your mental model of TypeScript. 🤓

Comments

[Josh Girvin]

TypeScript's "secret" scope was something I was also running into, but mainly because I was moving to it from Flow.

Flow isn't shy about there being "type land" and "code land", and never-the-twain-shall-meet. I really liked that separation, but there are upsides to how TS tackles it as well: just means we need to remember things like this post every so often haha

[Florian Reuschel]

Honestly, I'm glad I'm not the only one who has hit that brick wall. I didn't learn TypeScript very linearly (i.e. I did not read the official TS manual start to finish) but I was quite surprised that until today, I've never encountered an article mentioning this distinction.

Even Ryan in his GitHub comment did not point me to any RTFM-style URL, so I suppose this concept is just implicitly accepted without anybody talking about it that much. 🤷‍♂️

[Josh Girvin]

That was about my experience too. The biggest thing that threw me for a loop and made me realise that there was this "mixing" of concerns going on? import-ing types as if they're actual code... but they're not code! Flow has import type { ... which is much cleaner, but Typescript is so damned useful that it's silly to not use it.

[Florian Reuschel]

I don't even dislike the concept of mixing things up. It's pretty neat to be able to import a class which can be used as a constructor as well as a type.

But it obviously is less transparent and really carries the risk of newbies getting burned.

[Orta]

Nice! TypeScript 3.8 (in beta ATM) has import type and it would give a compiler error if you used a type-ish import (like a class) from import type in a value position

[Florian Reuschel]

Interesting, didn't know that. 👍

For anyone wanting to read more: TypeScript 3.8 beta announcement

[Vijay Koushik, S. 👨🏽‍💻]

This is surprising. I, being a beginner in TypeScript thought that types were implicitly tied with the classes I defined. I thought types worked similar to Java where one imports a class also imports the type implicitly. Thanks for pointing out the "secret" in typescript.

[Florian Reuschel]

Your assumption is not wrong though! If a class has been declared in TypeScript, its value and its type do implicitly exist under the same name, therefore they're also imported together

But this is a rather special case for classes, most (all?) other entities do not create an implicit type alongside them.

[Basarat Ali Syed]

Not a secret. They are called declaration spaces : basarat.gitbook.io/typescript/proj... 🌹

[Florian Reuschel]

Of course not a secret. But as a title, it definitely sounds more appealing than "TypeScript's Lesser Known Parallel Universe". 😁
Thanks for the pointer to the official terminology though. 👍

[Sean G. Wright]

This separation of values and types explains so many issues I've had over the years... especially with older type definition files and bundlers.

Thanks for the explanation!

[Florian Reuschel]

You're welcome. 🙂