Convert to UMD Definition Files for TypeScript

[kitsonk]

Currently our definitions are exported in a way that are considered "global" by current type acquisition engines, although we have never worked that way. There is a way to define types now as "UMD" definitions, which will effectively mirror the module structure of the code and create definitions that can be better consumed and namespaces by resulting packages.

[bryanforbes]

By "UMD" definitions, you mean generating a .d.ts file for each module within the package, correct?

[kitsonk]

Yes.

[kitsonk]

Ok, I have been able to generate valid .d.ts per file, but the challenge comes in when trying to utilise them:

• Under moduleResolution of classic, TypeScript 1.8 cannot find any of the modules.
• Under moduleResolution of node, TypeScript 1.8 can find all the modules and using something like import * as dojoCore from 'dojo-core' find the right definitions, but any other absolute references to modules are not resolved (e.g. it cannot find dojo-core/on), but if dojo-core/dist/umd is prefaced, the module is resolved (e.g. dojo-core/dist/umd/on).
• Using typings/typings to manage the definitions will import the definitions as ~dojo-core/dist/umd/on and also provide an alias to dojo-core/dist/umd/on. I have been unable to find a way to remap those and have opened ticket Remapping Module Alias Names typings/typings#558 to see if there is a way.
• Under TypeScript 2.0 (currently merged in typescript@next) is a way to provides paths for module resolution (see: Microsoft/TypeScript#5039. This looks like it would solve the resolution (though I haven't tried it yet).

So currently, the global typings work under classic resolution with an AMD loader (and in theory a SystemJS loader) that has been configured properly. The modular typings though currently require either "ugly" MIDs everywhere.

Also, because the distributions do not include the emitted modules as relative to the root of the package anymore, it breaks a CJS loader, as I am not sure there is any way to re-root the CJS loader. On the other hand, the CJS loader could easily just utilise the index.js which will point to dist/umd/main.js which should expose the public API. See dojo/core#166.

[kitsonk]

I have taken TypeScript 1.9.0-dev.20160528-1.0 for a project which has a build of dojo-core where each modules has its own definition file located in dist/umd. I added the following to the tsconfig.json:

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "dojo-core/*": [ "./node_modules/dojo-core/dist/umd/*" ]
        }
    }
}

And the compiler was able to resolve all the absolute modules (e.g. dojo-core/WeakMap), so this seems to be effective. The only challenge is that typings/typings could manage additional dependent typings, but would create module IDs that would not be resolved.

This still doesn't necessarily help those consuming in NodeJS, though we should be exporting our public facing APIs in packages in a main.ts and making that be the package's "main" then the following would work in TypeScript and works properly at runtime:

import { on } from 'dojo-core';

console.log(on);

So my thinking at the moment is that we start migrating to TypeScript 2.0 before it is released. We can pin to a particular pre-release version at the moment. It does mean we would need to utilise the pre-release version until TS 2 is released (likely to be within a few weeks of this writing).

[agubler]

@kitsonk can this be closed, now that either PRs have landed or they are ready for merge?