External Modules - Inappropriate Naming

[SetTrend]

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.

[DanielRosenwasser]

@SetTrend we understand the confusion, and ultimately this naming scheme was a big foot-gun for our users. We have since decided to change the terminology, and for 1.5, we are introducing the namespace keyword and deprecating the usage of the module keyword.

In short, external modules are now just called modules, and internal modules are now just namespaces. Though, it seems that this change isn't on our beta release's blog post announcement. @jonathandturner, can you please make note of this for our official release?

I've since fixed the handbook up, though the changes are unfortunately not published yet.

---

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.

I will bring this up at our next design meeting. 😄

[SetTrend]

Excellent. Thanks a lot for clarifying.

Can't help having a grin imagining your meeting when you bring this up :))

[SetTrend]

Please allow me one more question: When will an official TS v1.5 documentation be available? Or, when will there be a beta TS v1.5 documentation be available for download and printing?

[danquirk]

@SetTrend we try to keep the documentation up to date as we go to some degree. For instance you'll note the old modules documentation in the wiki here has already been updated to refer to namespaces and not internal modules even though 1.5 isn't released yet. If there are specific things you see missing or are confusing please file issues appropriately (or submit a PR with the changes you'd like to see (https://github.com/Microsoft/TypeScript-wiki)

If you're referring to the TypeScript Handbook on typescriptlang.org that's something @jonathandturner might have an answer to.

[mhegazy]

The handbook sources are at https://github.com/Microsoft/TypeScript-Handbook; PRs are always welcome.

[SetTrend]

@mhegazy I'm still leaning TypeScript. That's why I need the handbook. And that's why I can't do PRs myself.

[DanielRosenwasser]

@basarat has an ebook available called TypeScript Deep Dive.

It covers a decent number of topics that the handbook still hasn't gotten to.

[basarat]

thanks for the mention 🌹

@SetTrend this particular topic is covered in this chapter : http://basarat.gitbooks.io/typescript/content/docs/project/project.html

[SetTrend]

I see. Thanks for pointing me to this valuable source. From giving it a quick browse I believe it's illuminating those areas which the handbook is missing, but it doesn't seem to replace the handbook, though.

Somewhere I've seen a manual depicting the new TS v1.5 initializers a few weeks ago, but I can't find it anymore. That initializer information is not in the handbook, either.

Do you by chance know if there is a comprehensive and definitive TS v1.5 sytax reference manual available? Something that gives a feeling of: "If it's not in the book then it doesn't exist"?

[basarat]

new TS v1.5 initializers

I'm not sure what you mean. Can you provide a code snippet.

Something that gives a feeling of: "If it's not in the book then it doesn't exist"

That would be the language specification : http://www.typescriptlang.org/Content/TypeScript%20Language%20Specification.pdf (expect an update with 1.5 release)

[DanielRosenwasser]

For the record, the spec is a lot easier to read online.

[basarat]

And its more up to date too! Thanks for the link 👍

[SetTrend]

Thanks to all. But that doc isn't v1.5, too. I hate to say it, but v1.5 apparently is missing documentation and referece material.

[kitsonk]

@SetTrend it is. Second line down. Why do you think it isn't?

[DanielRosenwasser]

Actually, it's true, the spec is outdated and doesn't cover many of the additions to 1.5. This is something we're working on as well. If I recall correctly, the aim is eventually for the spec to be treated as an extension to ES6 rather than ES5, which is a big change.

[SetTrend]

Let me describe how I see it:

The problem with the lack of a comprehensive, downloadable documentation, or spec, is that programmers are not able to evaluate and use the language without. (Let's leave out the inner grid of programmers here who are focussing their daily work on TypeScript and participating here at GitHub.) Hence, practically, TypeScript v1.5 remains in a private, experimental, concealed state until it is fully documented.

Without a single, publicly available, fully comprehensive documentation there is, in fact, no v1.5. Without it there is no roadmap, no goal to reach to be able to finally tell when TS v1.5 actually is a final v1.5.

Am I wrong with my point of view? What is your perspective on this issue?

(Not to mention that this is the time where I'm having a few free weeks to spend on learning which I'll lose now due to the lack of a current spec.)

[kitsonk]

@SetTrend I think your expectations are a little bit high for software that is still in beta, also considering it is an OpenSource product. I think beta is the common moniker used for experimental software.

[danquirk]

@SetTrend

Without a single, publicly available, fully comprehensive documentation there is, in fact, no v1.5.

The final version of 1.5 has not been released yet, it is still in beta. Writing deep amounts of documentation for features that are still changing is not the most efficient use of our time. There's generally a sufficient amount of information within the repo to get started with any new/in progress features, and if something is lacking, logging an issue here or getting in the Gitter room is a good way to get more information and ask any specific questions. For 1.5 in particular the spec is undergoing a significant rewrite which may delay it more than a normal release.

Without it there is no roadmap, no goal to reach to be able to finally tell when TS v1.5 actually is a final v1.5.

1.5 is final when we release the final bits, not when the spec is released, although we do try to have the spec ready alongside or near after the bits themselves are available. You'll find links to most if not all of the large scale changes here: https://github.com/Microsoft/TypeScript/wiki/Roadmap and progress on issues in the current milestone here: https://github.com/Microsoft/TypeScript/milestones

I'm going to close this as the issue in the original post has been answered. Feel free to continue the discussion on docs here or in a new thread.