Is it idiomatic to use namespaces in Typescript?

Question

I am publishing a library that has a few functions. One of the functions returns an internal data structure in the library for debugging purposes. Currently, my type declaration file looks like this:

export default function doSomething(): void;
export function __dumpInternalRepresentation(): IR;

interface IR { ... }
interface Foo extends IR { ... }
interface Bar extends IR { ... }

However, I think this will be confusing to users because they will then be able to import IR, Foo, and Bar even though most people shouldn't import those.

As such, I am thinking of switching the declaration file to this:

export default function doSomething): void;
export function __dumpInternalRepresentation(): internal.IR;

export namespace internal {
    export interface IR { ... }
    export interface Foo extends IR { ... }
    export interface Bar extends IR { ... }
}

This way, all the internal data structures are hidden inside of internal.

However, I have read that Typescript namespaces are not recommended for newer code. If this is the case, what should I do?

Answer 1

they will then be able to import IR, Foo, and Bar even though most people shouldn't import those.'

It's strange. Either you want to export or not export a type, why would you care how consumer import it not? You can't control that.

Maybe you need this: Creating another module anotherModule.ts

export {doSomething} from 'thismodule'

So when consumer import ... form 'anotherModule', they won't see IR you want to hide. But they can still import {IR} from 'thisModule'.

Don't use namespace unless you want to organize type hierarchy from multiple projects, where types from different project can be merged into one. I even never tested it.