Import class in definition file (*d.ts)

After two years of TypeScript development, I've finally managed to solve this problem.

Basically, TypeScript has two kind of module types declaration: "local" (normal modules) and ambient (global). The second kind allows to write global modules declaration that are merged with existing modules declaration. What are the differences between this files?

d.ts files are treated as an ambient module declarations only if they don't have any imports. If you provide an import line, it's now treated as a normal module file, not the global one, so augmenting modules definitions doesn't work.

So that's why all the solutions we discussed here don't work. But fortunately, since TS 2.9 we are able to import types into global modules declaration using import() syntax:

declare namespace Express {
  interface Request {
    user: import("./user").User;
  }
}

So the line import("./user").User; does the magic and now everything works :)

Thanks to the answer from Michał Lytek. Here is another method I used in my project.

We can import User and reuse it multiple times without write import("./user").User everywhere, and even implements it or re-export it.

declare namespace Express {
    type User = import('./user').User;

    export interface Request {
        user: User;
        target: User;
        friend: User;
    }

    export class SuperUser implements User {
        superPower: string;
    }

    export { User as ExpressUser }
}

Have fun :)

For sake of completeness:

if you have an ambient module declaration (i.e, without any top level import/export) it is available globally without needing to explicitly import it anywhere, but if you have a module declaration, you will need to import it in the consumer file.
if you want to import an existing type (which is exported from some other file) in your ambient module declaration, you can't do it with a top level import (because then it wouldn't remain an ambient declaration).

So if you do this: (https://stackoverflow.com/a/39132319/2054671)

// index.d.ts
import { User } from "./models/user";
declare module 'express' {
  interface Session {
    user: User;
    uuid: string;
  }
}

this will augment the existing 'express' module with this new interface. https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation

but then to use this you would have to import this in your consumer file, it will not be available by default globally like ambient declaration as it is no more an ambient declaration

so, to import an existing type exported from another file, you have to import it inside the declare block (talking about this example, in other examples where you are not declaring a module, you can import inline at other places)
to do this, you cannot use a regular import like this
```
declare module B {
  import A from '../A'
  const a: A;
}
```
because in current implementation, the rules for resolution of this imported module are confusing, and hence ts does not allow this. This is the reason for the error Import or export declaration in an ambient module declaration cannot reference module through relative module name. (I am not able to find the link to the relevant github issue, if someone finds it, please edit this answer and mention. https://github.com/microsoft/TypeScript/issues/1720)

Please note, you can still do something like this:
```
declare module B {
  import React from 'react';
  const a: A;
}
```
because this is an absolute path import and not a relative path import.
so the only way to correctly do this in an ambient module is using the dynamic import syntax (https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-9.html#import-types)
```
declare namespace Express {
 interface Request {
   user: import("./user").User;
 }
}
```
as mentioned in the accepted answer (https://stackoverflow.com/a/51114250/2054671)
you can also do a global augmentation with something like this:
```
import express = require('express');
import { User } from "../models/user";

declare global {
    namespace Express {
        interface Session {
            user: User;
            uuid: string;
        }
    }
}
```
but remember global augmentation is only possible in a module not an ambient declaration, so this would work only if you import it in the consumer file, as mentioned in @masa's answer (https://stackoverflow.com/a/55721549/2054671)

All the above points are valid for importing a module which is exported from somewhere else, in your ambient modules, but what about importing an ambient module in another ambient module? (This is helpful if you want to use an existing ambient declartion in your own ambient module declaration and make sure those ambient types are also visible in the consumer of your ambient module)

you can use the /// <reference types="../../a" /> directive

// ambientA.d.ts
interface A {
  t: string
}

// ambientB.d.ts
/// <reference types="../ambientA.d.ts" />
declare module B {
  const a: A;
  export { a };
}

Links to other relevant answers:

Ambient declaration with an imported type in TypeScript

Import class in definition file (*d.ts)

Tags:

Typescript

Typescript Typings

Related

Recent Posts