Description
Far be it from me to pour cold water on this solemn decision, but what on earth were the grounds to use the term "external" in External Modules?
Just let's stick with this decision for a while ... Then why are JavaScript files stored in separate files, loaded asynchronously from distinct sources into a document or scope called internal? By what reasons?
I believe the terms Internal Module and External Module are highly inappropriate and misleading. They could as well have been called Silver Module and Cheesy Module with the same semantical meaning.
Let's face it: The sole distinction beween so-called Internal Modules and External Modules is that Internal Modules are loaded manually by native environment while External Modules are loaded by a JavaScript loader module, hiding the native interface.
Hence, a far more appropriate naming would have been Native Modules for Internal Modules and Loader Modules for External Modules.
Thus I suggest:
Rename the term External Modules to Loader Modules
and the term Internal Modules to Native Modules
Renaming both terms will put so much relief to understanding the basics of TypeScript. Moreover, those new terms will actually describe the true meaning of the methology.
#### To give an impression on how much improvement a renaming would result in I have translated parts of the [TypeScript handbook](http://www.typescriptlang.org/Handbook) here:
Going External (rename to: "Using Loaders")
TypeScript also has the concept of a loader module. Loader modules are used in two cases: node.js and require.js. Applications not using node.js or require.js do not need to use loader modules and can best be organized using the native module concept outlined above.In loader modules, relationships between files are specified in terms of imports and exports at the file level. In TypeScript, any file containing a top-level import or export is considered a loader module.
Below, we have converted the previous example to use loader modules. Notice that we no longer use the module keyword – the files themselves constitute a module and are identified by their filenames.
The reference tags have been replaced with import statements that specify the dependencies between modules. The import statement has two parts: the name that the module will be known by in this file, and the require keyword that specifies the path to the required module:
Code Generation for Loader Modules
Depending on the module target specified during compilation, the compiler will generate appropriate code for either node.js (commonjs) or require.js (AMD) module-loading systems. For more information on what the define and require calls in the generated code do, consult the documentation for each module loader.Optional Module Loading and Other Advanced Loading Scenarios
The core idea of the pattern is that the import id = require('...') statement gives us access to the types exposed by the loader module. The module loader is invoked (through require) dynamically, as shown in the if blocks below. This leverages the reference-culling optimization so that the module is only loaded when needed. For this pattern to work, it's important that the symbol defined via import is only used in type positions (i.e. never in a position that would be emitted into the JavaScript).Pitfalls of Modules [!!!]
In this section we'll describe various common pitfalls in using native and loader modules, and how to avoid them.
/// <reference> to a loader module
A common mistake is to try to use the /// <reference> syntax to refer to a loader module file, rather than using import. To understand the distinction, we first need to understand the three ways that the compiler can locate the type information for a loader module.The final way is by seeing an "ambient loader module declaration", where we 'declare' a module with a matching quoted name.