typescript@2_ ambient module cannot be resolved in the right way

[chenzhutian]

TypeScript Version: 2.0.3
OS: win10
Nodejs: 6.6.0

Code
In ./src/index.ts

/// <reference path="./types/koa-passport/index.d.ts" />
import * as koa from "koa";
import * as passport from 'koa-passport'; //error: [ts] Cannot find module koa-passport

In ./src/types/koa-passport/index.d.ts

import * as express from 'express';
declare module "koa-passport" {
    export function foo();
}

In tsconfig.json

{
    "compilerOptions": {
        "target": "es6",
        "module": "commonjs",
        "sourceMap": true,
        "preserveConstEnums": true,
        "rootDir": "src",
        "declaration": true,
        "traceResolution": true,
        "baseUrl": "."
    },
    "exclude": [
        "node_modules",
        "dist",
        ".vscode"
    ],
    "files": [
        "src/index.ts",
        "types/koa-passport/index.d.ts"
    ]
}

Expected behavior:
package koa-passport can be imported and have intellisense in the right way.

Actual behavior:

No intellisense and cannot find the module koa-passport
According to the tracing log of module resolution, typescript will resolve the module koa-passport in a path likes .../node_modules/**/koa-passport. Therefore the module cannot be find.
However, the handbook mentions that

If that didn’t work and if the module name is non-relative (and in the case of "moduleA", it is), then the compiler will attempt to locate an ambient module declaration.

So is this a bug ? Or I just made some mistakes and didn't write the ambient module declaration correctly ?

[chenzhutian]

After reading issue #11133 , I find out that when I move the import * as express from 'express'; into declare module "koa-passport" {}, everything will be alright.

However, this module extends another module. According to the module-plugin.d.ts in handbook, when I want to extend and add some new functions or properties into another module, I have to import the module which will to be extended outside the declare module '...' statement.

Then the bug happens again.
So is this a bug or by design? Do I need to write two separate declaration files, one to define the module and the other to extend another module ?

[chenzhutian]

When I try to move the extension into declare module "koa-passport", everything works again.
I cannot find any guidance and document about this problem.

// Type definitions for Koa-Passport v2.2.2
declare module "koa-passport" {
    import * as express from 'express';
    export function foo();

    import * as koa from "koa";
    module "koa" {
        export interface Request {
            authInfo?: any;
        }

        export interface Middleware {
            (ctx: koa.Context, next: () => Promise<any>): any;
        }
    }
}

[mhegazy]

first in your tsconfig.json add "moduleResolution": "node".

Second. is this file intended to live on definitlyTyped and @types?

The way you defined the module should work:

// Declare your module
declare module "koa-passport" {
    import * as express from 'express';
    export function foo();

    // Augment `Koa` module
    module "koa" {
       ....
    }
}

I would recommend however, you define

// types/koa-passport/index.d.ts

// Local exports
export declare function foo();

// Augment the other module Koa
declare module "Koa" {
    ......
}

then add path mapping entry in your tsconfig for this file:

{
    "compilerOptions": {
       "koa-passport" : ["types/koa-passport"]
    }
}

[chenzhutian]

Thanks for your help.
The declaration is not intended to publish to @types currently. But it may be in the future.
I followed your suggestion and it works. So do I need to write the path mapping for every package which has no declaration file in the npm/@types ?

[aluanhaddad]

@mhegazy do you mean

{
  "compilerOptions": {
    "baseUrl": ".", 
    "paths": { 
       "koa-passport" : ["types/koa-passport"]
    }  
  }
}

or has this changed?

[mhegazy]

thanks @aluanhaddad for the correction. yes. i meant to include paths.

[mhegazy]

So do I need to write the path mapping for every package which has no declaration file in the npm/@types ?

up to you. you could also do a wild card matching like so:

{
  "compilerOptions": {
    "baseUrl": ".", 
    "paths": { 
       "*" : [ "*" , "types/*"]
    }  
  }
}

which says: For every module "mod", look it up under <baseUrl>\mod first, if not found look it up under <baseUrl>\types\mod.

[chenzhutian]

thank you very much.
It really help a lot.