TypeScript includes declaration merges from declaration file in typeRoots without import

[sgronblo]

TypeScript Version: 2.7.0-dev.201xxxxx

Context

I am trying to create a local type declaration file for winston-papertrail that adds a new property to winston.transports.Papertrail. There is a @types/winston but no @types/winston-papertrail. Requiring "winston-papertrail" should augment winston.transports to also contain this additional Papertrail property. My assumption was that types inside of 'typeRoots' do not take effect until after the corresponding import statement has been made.

I am able to make it work by doing the following:

Code

The main file is index.ts:

import * as winston from 'winston'
// import 'winston-papertrail'

winston.transports.

tsconfig.json:

{
  "compilerOptions": {
    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */
    "strict": true,                            /* Enable all strict type-checking options. */
    "typeRoots": [ "node_modules/@types", "types" ]                       /* List of folders to include type definitions from. */
  },
  "include": [ "index.ts" ]
}

types/winston-papertrail/index.d.ts:

import * as winston from 'winston'

declare module "winston" {
    interface Transports {
        Papertrail: any
    }
}

export { }

Expected behavior:

The expected behavior is that the Papertrail property is NOT showing up in the autocompletion suggestions for properties on the winston.transports value since I haven't imported "winston-papertrail" yet.

Actual behavior:

The Papertrail property is showing up in the autocompletion suggestions.

typeRoots are used for including global definitions automatically without needing an explicit reference.
If you don't want that you could use "typeRoots": [].

[sgronblo]

I see, then everything is as expected. Is this behavior documented somewhere, though? Personally I found it a bit unituitive.

There is http://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types although we aren't doing a good job of specifying what "included" means. Imported modules don't need to be included, just global definitions.

[sgronblo]

So does it then mean that the structure of the @types folder is irrelevant? By default every node_modules/@types/foobar/index.d.ts is included? I fooled myself into thinking that whether they are included or not would be controller by the import statements in your code, because the @types structure reflects the actual package names that you import.

We normally automatically look through @types in case anything contains global definitions (such as @types/node or @types/jquery). It is possible to explicitly choose which ones are determined by specifying types in your tsconfig.json, as well as by using /// <reference types="foo" /> comments.

[sgronblo]

Gotcha, thanks