Proposal: reinstate typings bundle(s)

[jpsfs]

Hi,

Typings has always been an issue on Angular 2 and different strategies have been followed since the very beginning of the project (example: #3082)

PS: I'm available to implement this if the team feels like it's the way to go forward. I'm also available to provide more justification/clarification to this topic if you want.

Motivation

The latest strategy (#5248) although very suitable for a ToDo app, fails to work on more complicated environments (targeting ES6 on typescript is an example).

Deploying Angular2 with anything but NPM will also not work. Better than me, you all know that bower (and other) package managers are used and there is no need to have the entire angular source code in every dev machine when the bundle suffices.

Also,

"moduleResolution": "node"

breaks compatibility on typings with global definitions and internal modules and it's not yet fully supported on some IDE's (like Visual Studio - changing to cjs is not always an option).

Goal

Ease medium/large size projects development, allowing different distribution channels. Allow for ES6 direct compilation.

Proposal

Distribute typings packages to each module (angular/core, angular/common, ...). Dgeni should no longer be required (thus removing one more tool to maintain).

Use tools like https://github.com/SitePen/dts-generator or soon to be available compiler option microsoft/TypeScript#4433 to achieve this.

A simple test shown that if we cleanup somethings on the code (like this. where Promise is defined on es6-shim.d.ts but not declared on the file (nor catched by the generator), thus making hard even to read the code) dts-generator will work.

Example

Imagine a front-end project with the following structure:

| MyFrontEnd
| -- | index.html
| -- | bower_components
| -- | -- | core
| -- | -- | -- | core.bundle.js
| -- | -- | -- | core.bundle.d.ts
| -- | -- | module1
| -- | -- | -- | module1.bundle.js
| -- | -- | -- | module1.bundle.d.ts
| -- | -- | module2
...

This front-end project uses a framework (with business logic) that internally uses Angular2.
Both core and all the modules use other 3rd parties.

| MyFramework
| -- | core (core depends on angular2)
| -- | -- | core.ts
| -- | -- | ...
| -- | -- | tsconfig.json
| -- | addons (all modules depend on core)
| -- | -- | module1 
| -- | -- | -- | module1.ts
| -- | -- | -- | tsconfig.json
| -- | -- | module2
| -- | -- | -- | module2.ts
| -- | -- | -- | tsconfig.json

In this case, from angular we only need something like:

| angular2
| -- | angular2.core.js
| -- | angular2.core.d.ts
| -- | angular2.common.js
| -- | angular2.common.d.ts
...

This simple structure can easily be distributed.

[alexeagle]

Yes!
We agree that Angular should provide a typings bundle for cases like this.
Indeed we have been working with the TypeScript team on the bundling option in the compiler that you referenced. We met with them about a month ago to describe our requirements for using it. We intend to wait for that to be available before solving this issue, rather than hack around with the brittle regexes in dts-generator.
Also we've chatted with @blakeembrey who maintains the github.com/typings tool, and we need to investigate how he creates the synthetic external modules to see how that helps.

[blakeembrey]

@alexeagle Just quickly, the way typings bundles is actually similar to both dts-generator and microsoft/TypeScript#4433, except it's been expanded to support module resolution through typings.json. It also fixed some of the bugs with dts-generator, and strips all the references from source files (they're too ambiguous in the dependency context). It's not regexes, but using the TypeScript compiler to parse and then resolve the result.

[alexeagle]

cc @rkirov

[PavelPZ]

If I use this tsconfig.json in my project:

{
  "compilerOptions": {
    "declaration": true,
    "target": "es5",
    "module": "system",
    "moduleResolution": "node",
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "outFile": "index.js",
    "inlineSourceMap": true,
    "inlineSources": true
  }
}

new typescript compiler generates single ES6 .js bundle file and single definition .d.ts file for whole project. Resulting .d.ts looks like:

declare module "wwwroot/libs/utils/flux" {
  import * as rx from 'rxjs/Rx';
  export namespace flux {
...
declare module "wwwroot/libs/utils/parseUrl" {
  export namespace parseUrl {
...
declare module "wwwroot/apps/test-router/testrouter" {
  import * as router from 'angular2/router';
  import { flux } from "wwwroot/libs/utils/flux";
  export namespace testRouter {
...

If there exists similar process for both angular2 and rxjs projects, everybody could develop and build angular2 solution _without NPM_, using HTML page like:

<html>
<head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.35.0/es6-shim.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.24/system-polyfills.js"></script>
  <script src="https://npmcdn.com/angular2/es6/dev/src/testing/shims_for_IE.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/systemjs/0.19.24/system.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/angular2-polyfills.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/Rx.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/angular2.dev.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/http.dev.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/router.dev.js"></script>

  <script src="my-application-bundle.js"></script>
</head>

<body>
  <my-app>Loading...</my-app>
  <script>
    System.import('wwwroot/apps/test/main').then(function(m) { m.init(); }, function(m) { debugger; });
  </script>
</body>
</html>

Am I right?
What other typescript compiler features are neccessary for generating angular2.d.ts and rxjs.d.ts?

It could be a huge step for VS.NET developers to easily adopt angular2.

[alexeagle]

@PavelPZ yes, I have been meaning to try that since it was added in TS. Earlier we were blocked by inability to compile ng2 with TS 1.8. We should be able to do it now, as soon as I get some time.

Or you could try contributing this. The tricky thing is that we don't compile angular2 with a single tsc execution right now, instead we have the broccoli builder in browser_tree.ts so it will be a little bit of learning to find the right spot to generate the single .d.ts.

[PavelPZ]

I am nor NPM not node.js expert, so I made some one hour reverse engineering in order to create rxjs and angular 2 d.ts file, see rxjs-Angular2-DefinitelyTyped.

Basic idea is:

• capture and analyze folowing bundles for System.register("XXX"... module names:

https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/Rx.js
https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/angular2.dev.js
https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/http.dev.js
https://cdnjs.cloudflare.com/ajax/libs/angular.js/2.0.0-beta.9/router.dev.js

• download typescript sources (.ts, not .d.ts files) for those modules from github (angular and rxjs)
• make small modification which alow error free typescript compilation of source files (by means of GetJSBundleFiles.cs code)
• after that, I have typescript project, which generates .d.ts file (see ts-project.zip).

Whole magic is to specify typescript source files, which allow bug free typescript compilation.

[alexeagle]

@PavelPZ very clever, the file you built looks really good, it has comments, the right module names, and all the deps included.
The problem is it won't stay up-to-date as rxjs and angular2 continue to cut releases... so we still need something built into the build system for the long term.

[alexeagle]

Basically when we run the compiler over one unit of angular2 (eg. the "core barrel"), we want to do it again with the modified compiler settings to produce one file.
https://github.com/angular/angular/blob/master/tools/broccoli/broccoli-typescript.ts#L25
In this spot, we compile a variant with a different setting (whether to ignore @internal symbols in the d.ts output.
I think we'd want another compilation that produces the bundled typing for each compilation.

Also I don't think there should be a single file with the dependencies. This means if you use a different version of rxjs with a given version of angular2, you have no way to select matching typings. Instead, we should have a typings bundle for rxjs (we can ask them to produce one as well, once we have the recipe figured out) and one for each angular2 compilation unit (eg. a separate one for testing).

[PavelPZ]

@alexeagle, the Typescript is very clever, I only extracted correct Angular 2 x rxJS source files. I think that providing correct files to developers (one ZIP for every compilation variant) will be the most comprehensive way for them (ZIP could be similar to ts-project.zip in my github).

All other build products (d.ts files, ES6 JS bundle files, ES5 JS bundle files, minified, with embeded .MAP, with embeded TS sources etc.) is question of setting desired tsconfig.json. In addtion, all without NPM, just with the help of single tool - Typescript compiler.

Regarding different angular2 x rxjs definitions: I absolutely agree with you.

[alexeagle]

Producing equivalent bundles with TypeScript is way outside my scope right
now, though if someone has time, it would be interesting to see how they
compare with Webpack bundles.
Note that we are missing some test coverage after the bundling, and it's
not used by our internal customers either, so changes there are extra risky.
Another note, we are experimenting with using Closure Compiler for final
bundling, because it is the smallest minifier, and also you can bundle your
own sources together with the framework into a single script.

On Sun, Mar 13, 2016 at 9:55 AM Pavel Zika notifications@github.com wrote:

@alexeagle https://github.com/alexeagle, the Typescript is very clever,
I only extracted correct Angular 2 x rxJS source files. I think that
providing correct files to developers (one ZIP for every compilation
variant) will be the most comprehensive way for them (ZIP could be similar
to ts-project.zip in my github).

All other build products (d.ts files, ES6 JS bundle files, ES5 JS bundle
files, minified, with embeded .MAP, with embeded TS sources etc.) is
question of setting desired tsconfig.json. In addtion, all without NPM,
just with the help of single tool - Typescript compiler.

Regarding different angular2 x rxjs definitions: I absolutely agree with
you.

—
Reply to this email directly or view it on GitHub
#5796 (comment).

[PavelPZ]

@alexeagle, my basic problem is to select correct technology for my company (choosing React x Angular). After a month studying React I am examining Angular 2 now (from many points of view, NPM less development environment is one of them).

Now I stopped it due to problem with implementing basic things like breadcrumb (#5318) and product catalogue (#2753). I hope that Angular will prove to be feasible as soon as possible and I will be able to continue in this discussion.

[DzmitryShylovich]

@alexeagle is this still relevant?

[alexeagle]

It's relevant, in that we still ship typings in individual files, not bundled like the new flat ESM JS packages. But, I think we can close it anyway, because I don't know of a good reason that someone would need this.
For the record, we did discuss this with Microsoft, and had some idea of a walker over the types in the program that could produce this kind of flattened .d.ts bundle. It might also be useful in a distributed, multi-compilation-unit build where you could have fewer files to ship around between compilation actions. But it's not on our roadmap.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}