Module resolution via "--paths" fails against declaration files generated alongside "--outfile:"

[josh-sachs]

TypeScript Version: 2.4.0 / nightly (2.5.0-dev.201xxxxx)
2.5.2
Code

/bundles
- app.js
- app.d.ts
- common.js
- common.d.ts
- core.js
- core.d.ts

/app
- main.ts
- tsconfig.ts

/src/common
- index.ts
- file1.ts
- tsconfig.json

/src/core
- index.ts
- file1.ts
- tsconfig.json

//app/main.ts
import { resource } from '@bundles/core'
import { somethingElse } from '@bundles/common'

//common/index.ts
export * from './file1.ts'

//core/index.ts
export * from './file1.ts'

//app/tsconfig.json
...
"target": "es5",
"module": "system",
"rootDir": ".",
"outFile": "../bundles/app.js",
"declarations": true,
"paths": {
   "@bundles/*": ["../bundles/*"]
}
...

//common/tsconfig.json
...
"target": "es5",
"module": "system",
"rootDir": ".",
"outFile": "../bundles/common.js",
"declarations": true,
"paths": {
   "@bundles/*": ["../bundles/*"]
}
...

//core/tsconfig.json
...
"target": "es5",
"module": "system",
"rootDir": ".",
"outFile": "../bundles/core.js",
"declarations": true
"paths": {
   "@bundles/*": ["../bundles/*"]
}

// bundles/common.d.ts
declare module "index" {
    export * from 'file1'
}

// bundles/core.d.ts
declare module "index" {
    export * from 'file1'
}
...

Expected behavior:
TSC to correctly resolve the import statements within app/main.ts against the configured --paths, applying the same logical resolution strategy that lets it resolve barrels.

(note: I've had to escape the [@] symbols for some reason at the start of these lines).

"[@]bundles/common" => '../bundles/common.d.ts' => '../bundles/common.d.ts [declared module "index"]'   (OK)

"[@]bundles/core" => '../bundles/core.d.ts' => '../bundles/core.d.ts [declared module "index"]'   (OK)

"[@]bundles/*" => '../bundles/*.d.ts  => "[declared module *]" => "[declared module index]"  => "../bundles/*/index.d.ts" => "[declared module *]" => "[declared module index]"

Actual behavior:

It appears the path part of the import statement is currently expected to be included in the declared module name.

"[@]bundles/common" => '../bundles/common.d.ts' => '../bundles/common.d.ts [declared module "@bundles/common"]'   (FAIL)

Even if I name index.ts to common.ts for example, this will still fail because the resolution logic is expecting the "@bundles" path token to be in the declared module name.

I can coerce the expected behavior by creating a "Bundles (@bundles)" folder inside my module - but the whole point is that the "--paths" option shouldn't be married to the module structure.

/src/common
- @bundles/
-- common.ts

//src/common/@bundles/common.ts
export * from '../index'

//bundles/common.d.ts
declare module "index" {
  exports "file1
}

declare module "@bundles/common" {
   exports "index"
}

[mhegazy]

can you share a repo i can look at, the tsconfig.json seem to be missing baseurl. also it will be easier for me to look at the trace output.

[josh-sachs]

I've created a repo here: https://github.com/josh-sachs/typescript-18311

[mhegazy]

there is not a module in file bundles\broken.d.ts, this is just a global file. so you need to change the file to be a module. i.e.

// bundles\broken.d.ts
export * from "resource-1";

// bundles\resource-1.d.ts
export class Resource1 {
}

[josh-sachs]

I'm not sure I follow...

All of the exports are declared as modules within the declaration files. The declaration files are generated by TSC via the compiler options:

-- moduleResolution: "node",
-- outFile: "...",
-- module: "system"
-- declaration: true

// bundles/broken.d.ts
declare module "resource-1" {
    export class Resource1 {
    }
}
declare module "index" {
    export * from "resource-1";
}

// bundles/workaround.d.ts
declare module "resource-2" {
    export class Resource2 {
    }
}
declare module "index" {
    export * from "resource-2";
}
declare module "@bundles/workaround" {
    export * from "index";
}

Typescript successfully resolves the declaration files broken.d.ts and workaround.d.ts but incorrectly scans them for the convention based entrypoint module "index" and instead only scans for an entry point named for the supplied path (e.g. "@bundles/workaround")

If I were not using the --outFile argument this wouldn't be an issue because typescript identifies typescript modules with an export statement as modules. The problem is that Typescript does not correctly apply the node module resolution strategy to the declaration files it generates.

In essence the declaration file produce by TSC in conjunction with the --outFile option should undergo an additional resolution step where the entire file is treated as if it were a folder... since that is basically what the amd and system module formats encapsulate as modules, and the module resolution strategy is node.

[josh-sachs]

Mohamed Hegazy (@mhegazy) I think you were too quick to label this thread as a question. Please review again as there is an issue here with module resolution against declaration files generated via --outFile.

[mhegazy]

A module is a file that has at least one top-level import/export declarations. a non-module file is refereed to as a global script. Modules have their own logic for scoping, declaration merging and resolution.

An ambient module declaration, something of the form declare module "resource-1" {...} lives in the global scope.
On a related note, compiling a with --outFile says this file is going to be in the global scope, otherwise, how else would it be consumed. if this is a node project, do not use --outFile, and instead distribute your modules as they are.

Now, for module resolution, the target of an import needs to be a module. the compiler asserts that. in the case of your import { Resource1 } from '@bundles/broken';.. here is what goes on:

• there is a path mapping entry for this, the compiler will use it "@bundles/*": [ "../bundles/*" ]
• this lands on a file, ../bundles/broken.d.ts, great, looks like what we were looking for..
• but broken.d.ts is not a module..
• error.

[mhegazy]

more info about module can be found in http://www.typescriptlang.org/docs/handbook/modules.html

[josh-sachs]

With all due respect, it's starting to feel like you aren't taking the time to evaluate the information I've put together. The declaration file declares modules. Typescript resolves the modules, but not using the proper resolution strategy. I've put together extremely clear repro steps to demonstrate exactly where the resolution strategy is breaking down. Please take a moment to review.

…

________________________________ From: Mohamed Hegazy <notifications@github.com> Sent: Monday, September 11, 2017 1:31:13 PM To: Microsoft/TypeScript Cc: Joshua Sachs; Author Subject: Re: [Microsoft/TypeScript] Module resolution via "--paths" fails against declaration files generated alongside "--outfile:" (#18311) more info about module can be found in http://www.typescriptlang.org/docs/handbook/modules.html — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#18311 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ALFAbUlgZK3Flo0z7CUoUSJaFcmzkcSmks5shW5hgaJpZM4PP7kc>.

[mhegazy]

The declaration file declares modules.

This file does declare modules, one called "index" and one called "resource-1"
The file itself (broken.d.ts), is not a module. it just happens that you are importing the file.

declaring a global module called "index" does not help resolving the module.

declare module "resource-1" {
    export class Resource1 {
    }
}
declare module "index" {
    export * from "resource-1";
}

Typescript resolves the modules, but not using the proper resolution strategy.

Not sure i understand what you mean.

[josh-sachs]

Typescript allows import statements against the definition file.

If you get the repo and open src/app/main.ts you will see the following imports:

import { Resource1 } from '@bundles/broken'
import { Resource2 } from '@bundles/workaround'

the path '@bundles/*' is defined within tsconfig.json.

Typescript correctly resolves bundles\broken.d.ts and bundles\workaround.d.ts as containing module definitions.

Now notice the following:

import { Resource1 } from '@bundles/broken' - does not work.
import { Resource2 } from '@bundles/workaround' - does work.

The reason that the { Resource 1 } import does not work is because the bundles\broken.d.ts declaration file doesn't declare a module explicitly named:

/// this module is not declared within broken.d.ts
declare module "@bundles/broken" { 
    ...
}

The reason that the { Resource2 } import does work is because I've modified the source folder structure to include a folder called @bundles with a file inside called workaround.ts - this causes the workaround.d.ts file to contain a module explicitly named to include "@bundles/workaround":

/// this module is declared within workaround.d.ts
declare module "@bundles/workaround" { 
    export * from "index"
}

What is expected to happen is that TSC should automatically find the index module when when importing @bundles/broken because an explicitly named module is not present in the declaration file.

/// by convention, this is the default entry point for the *.d.ts file yet typescript doesn't recognize that currently.
declare module "index" {
....
}

Typescript already resolves barrels this way when --outFile is not present...

from: https://www.typescriptlang.org/docs/handbook/module-resolution.html

1. /root/src/moduleB.ts
2. /root/src/moduleB.tsx
3. /root/src/moduleB.d.ts
4. /root/src/moduleB/package.json (if it specifies a "types" property)
5. /root/src/moduleB/index.ts
6. /root/src/moduleB/index.tsx
7. /root/src/moduleB/index.d.ts

In this case, moduleB is a single file... lets call it moduleb.d.ts - typescript already succeeds to this point in scanning moduleb.d.ts for

declare module "moduleb" {
...
}

When it does not find that, it does not continue to apply the resolution steps 5-7.... it should do this - which would mean additionally scanning for:

declare module "index" {
...
}

within moduleb.d.ts.

Is this more clear now?

[mhegazy]

the two processes happen at different times. the module resolution is a preprocessing step, and does not know about what ambient module declarations are there in the global scope. at the time the second step happens it is too late to change the results of the first step. hope that clarifies it.

[josh-sachs]

This doesn't make sense, as having an ambient declaration explicitly shimmed into the .d.ts file as with the example repo's workaround.d.ts package makes everything work fine.

import { josh } from @path/josh

/// josh.d.ts

// * this should work but doesn't
declare module 'josh' {
...
}

// * this should work but doesn't
declare module 'index' {
...
}

// * this works, and is an ambient declaration. 
declare module '@path/josh' {
...
}

When --outFile is applied, the entire declaration file is a system/amd representation of a package's physical file structure... tsc should expect the same naming conventions to apply.

Keep in mind none of this is an issue if you don't use the --outFile argument, but right now there is no way to tell tsc to bundle emitted javascript but to not bundle emitted declaration files. The only way to consume a bundle produced by tsc with the --outFile argument is to shim into the package a folder structure that anticipates the consuming project's tsconfig --paths setup which seems ridiculous.